huskies: merge 513_story_startup_reconcile_pass_that_detects_drift_between_crdt_pipeline_items_and_filesystem_shadows

README.md

@@ -89,6 +89,48 @@ script/release 0.7.1
 
 This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.
 
+## Startup reconcile pass
+
+On startup, after CRDT replay and database initialisation, huskies runs a
+**reconcile pass** that compares pipeline state across three sources:
+
+1. **In-memory CRDT** — the primary source of truth, reconstructed from
+   `crdt_ops` on startup.
+2. **`pipeline_items` table** — a shadow/materialised view written alongside
+   CRDT updates, used for fast DB queries.
+3. **Filesystem shadows** (`.huskies/work/N_stage/*.md`) — legacy rendering
+   still written by some paths and read by agent worktrees.
+
+Any disagreement between these sources is **drift**. The reconcile pass logs a
+structured line for each drifted item:
+
+```
+[reconcile] DRIFT story=X crdt_stage=Y db_stage=Z fs_stage=W
+```
+
+(`MISSING` is used where a source has no record for that story.)
+
+### Drift types
+
+| Type | Meaning |
+|------|---------|
+| `CRDT-only` | Story present in CRDT but absent from `pipeline_items` |
+| `DB-only` | Story present in `pipeline_items` but absent from CRDT |
+| `FS-only` | Story on the filesystem but absent from both CRDT and DB |
+| `stage-mismatch` | Story present in both CRDT and DB but with different stage values |
+
+Note: a filesystem shadow that lags behind the CRDT/DB stage (both of which
+agree) is **not** treated as drift — the FS is a best-effort rendering and is
+allowed to lag.
+
+If any drift is detected, the Matrix/Slack/WhatsApp bot startup announcement
+includes a count and a suggestion to check the server logs.
+
+### Opt-out
+
+Set `reconcile_on_startup = false` in `.huskies/project.toml` to disable the
+pass during the migration window if it produces noise.
+
 ## License
 
 GPL-3.0. See [LICENSE](LICENSE).