feat(consistency): distributed multi-machine safety (CUST-WP-0026)

T01 — No-regress rule (C-15): fix-consistency now detects when a DB task
status is ahead of the workplan file (e.g. marked done on CoulombCore)
and emits C-15 WARN instead of regressing the DB back to the stale file
value. STATUS_ORDER ranking: todo(0) < in_progress/blocked(1) < done/cancelled(2).

T02 — Pull gate (C-16): fix_repo runs git fetch + rev-parse at the start
of every --fix run. If the local repo is behind its remote tracking branch,
all write operations are skipped and C-16 WARN is emitted. Best-effort:
offline/no-remote silently skips the check.

T03 — DB→file writeback: C-15 fix path patches the status field in the
matching task block and git-commits the change with a standard message.
--no-writeback flag disables writeback while keeping T01/T02 active.

T04 — CLAUDE.md + session-protocol.template updated with new guidance,
C-15/C-16 semantics, and fix-consistency-remote recommendation.

T05 — Makefile: fix-consistency-remote pulls then fixes in one step.

16 new tests; 155 passed total.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-26 10:19:23 +01:00
parent 41d239c166
commit 26c920ce3e
5 changed files with 422 additions and 21 deletions

View File

@@ -98,13 +98,28 @@ Every Claude Code session in this repository must follow this ritual:
```
Requires postgres running (`make db`) and `custodian_test` database to exist.
Create it once with: `psql -U custodian -c "CREATE DATABASE custodian_test"`
5. If any workplan files were written or modified this session, run:
5. If any workplan files were written or modified this session, first ensure the
local copy is up to date, then run the consistency sync:
```bash
git -C <repo_path> pull --ff-only
cd state-hub && make fix-consistency REPO=the-custodian
```
This syncs task blocks → DB and updates task statuses. Without this step, the
"Open Workstreams by Domain" chart will show 0 progress even for completed work.
The checker now enforces two safety rules for multi-machine workflows:
- **C-15** (no-regress): if the DB task status is already ahead of the file
(e.g. marked `done` on CoulombCore), the file is *written back* to match DB
rather than regressing the DB to the stale file value.
- **C-16** (pull gate): if the local repo is behind its remote tracking branch,
`--fix` is skipped entirely. A C-15 warning is normal when CoulombCore has
progressed tasks — it means writeback is keeping files in sync.
For repos where work runs on a remote machine, prefer the combined target:
```bash
cd state-hub && make fix-consistency-remote REPO=<slug>
```
**Workplan ↔ DB sync rule (prevents ghost workstreams):**
When creating a new workstream backed by a workplan file, **always write the file
first, then run `make fix-consistency`** — never call `create_workstream()` /