10 — Implementation Plan

From the Burrow™ specification set.

10 — Implementation Plan

Guiding Rule

Do not implement filesystem mutation until read-only discovery has been exercised against the owner's real storage and the results have been reviewed.

Milestone 0 — Repository Foundation

Deliver:

  • monorepo/repository structure;
  • Swift engine project;
  • Next.js documentation site (not the application UI; see ADR-004);
  • shared API contract approach;
  • SQLite migration framework;
  • test fixture generator;
  • CI/lint/type/test baseline.

Gate:

  • applications start locally;
  • UI can query engine health;
  • no filesystem mutation APIs exist.

Milestone 1 — Volume & Provider Discovery

Deliver:

  • mounted volume discovery;
  • stable volume IDs;
  • iCloud root detection;
  • OneDrive root/account detection;
  • external drive detection;
  • storage-root configuration UI.

Gate:

  • owner can see correct local/cloud/external locations;
  • no scans outside approved roots.

Milestone 2 — Inventory Scanner

Deliver:

  • recursive traversal;
  • exclusions;
  • metadata capture;
  • progress/cancellation;
  • per-item/root errors;
  • SQLite persistence;
  • incremental rescan foundation.

Gate:

  • representative fixture and real read-only scans complete;
  • no mutation detected.

Milestone 3 — Storage Analytics

Deliver:

  • capacity/utilization views;
  • largest files/folders;
  • age filters;
  • file-type summaries;
  • cloud/local allocation distinctions;
  • scan coverage/staleness indicators.

Engine query (VLT-32): Catalog.storageAnalytics() over the latest scan. Fixture corpus math is in StorageAnalyticsCorpus. UI cards and drill-down remain VLT-34 / VLT-36.

Gate:

  • dashboard numbers reconcile to test fixtures and reasonable filesystem checks.

Milestone 4 — Hashing & Duplicates

Deliver:

  • size grouping;
  • partial signatures;
  • full BLAKE3;
  • hash cache;
  • duplicate groups;
  • cross-storage duplicate analysis.

Gate:

  • false exact-duplicate rate is zero in test corpus;
  • same-name/different-content fixtures are handled correctly.

Milestone 5 — Recommendation Layer

Deliver read-only recommendations:

  • exact duplicates;
  • large/stale files;
  • archive candidates;
  • downloads/installers;
  • cloud-local-storage observations.

Gate:

  • every recommendation exposes deterministic reason/evidence;
  • no recommendation triggers an action.

Release v0.1 Review (VLT-38)

Mandatory human approval gate. Automated acceptance criteria do not authorize agents to approve this gate.

Run a controlled read-only validation against the owner's Mac internal storage, iCloud Drive, OneDrive, and a portable SSD. For each expected provider/location record VALIDATED, NOT_PRESENT, NOT_CONFIGURED, INACCESSIBLE, or FAILED. Missing or unconfigured iCloud/OneDrive is not a silent pass.

Owner review of those results is required before Release 0.2 hashing and duplicate analysis starts.

The written record and result-code rules live in 18 — Release 0.1 Review. Agents may collect evidence. They must not mark VLT-38 Done.

Release v0.2 Review

Mandatory human safety gate at the end of Duplicate Analysis. It must occur before Release 0.3 Backup enables Safety Level 1 or any production file-copy capability.

Review:

  • inventory accuracy;
  • duplicate-analysis accuracy;
  • cloud-provider behavior;
  • scanner performance;
  • hashing performance;
  • observed storage configuration;
  • safety-test results;
  • proposed backup topology;
  • proposed portable-drive usage.

Releases 0.3–1.0 remain progressive placeholders until both human gates are approved.

Milestone 6 — Backup

Only after approval:

  • Safety Level 1;
  • backup jobs;
  • portable drive target validation;
  • dry run;
  • incremental copy;
  • hash verification;
  • health dashboard.

Milestone 7 — Archive

  • archive plan;
  • copy + verify;
  • manifest;
  • restore lookup;
  • source cleanup remains separate.

Milestone 8 — Managed Cleanup

Only after explicit design approval:

  • Safety Level 2;
  • review queue;
  • Trash integration;
  • cloud warnings;
  • duplicate cleanup;
  • audit history.

Milestone 9 — Policy & Scheduling

  • scheduled backups;
  • stale-backup notifications;
  • explicit cleanup policies;
  • no autonomous permanent deletion.

Definition of Done — Every Work Item

  • acceptance criteria met;
  • tests added/updated;
  • safety constraints maintained;
  • lint/type/build checks pass;
  • error handling included;
  • documentation updated;
  • no unrelated scope expansion.