Files

T

Bastien Chanot 9b1fb92d89 job4: SPEC-09 retire-real-state-snapshot

Deleted T4e + its coupled echo note in lib/tests/run-reconcile.sh and
the fixtures/real-state.snapshot it read — superseded by SPEC-08's T7,
which actually DRIVES the tree_clean/pushed/msg_committed oracles
instead of miming them via a static line-count regex. Closes J4-09
(WEAK+drift): T4e only counted fixture line-suffixes matching
`=(true|resolved|present)$`; the snapshot itself was stale
(BLK-009=open contradicted blockers-snapshot.md's already-resolved
status) and unowned, and the drift was inert (`=open` doesn't even
match the count regex) — the assertion could never have caught
anything.

Updated skills/reconcile/SKILL.md:53's hardcoded "20/20" claim to the
new total (unguarded file, same logical step, ordered after SPEC-08+
SPEC-10 per the report).

grep -c 'real-state.snapshot' lib/tests/run-reconcile.sh == 0
(verified). No red demo (deletion, per spec) — gate is the green run
+ that grep. GREEN: 25/25 passed, shellcheck clean.

2026-07-06 19:17:23 +02:00

4.2 KiB

Raw Blame History

name, description

name	description
reconcile	Use when you need the REAL open-work state of a project and the TODO or memory registries may be stale — "is the queue empty?", "what's left open?", "qu'est-ce qui reste", before /close, after a break, or when a checkbox/status looks doubtful. Confronts declared status (TODO checkboxes, registry statuses) against real git/fs state and surfaces the gaps. NOT memory curation (that is /prune-memory).

name

description

reconcile

Use when you need the REAL open-work state of a project and the TODO or memory registries may be stale — "is the queue empty?", "what's left open?", "qu'est-ce qui reste", before /close, after a break, or when a checkbox/status looks doubtful. Confronts declared status (TODO checkboxes, registry statuses) against real git/fs state and surfaces the gaps. NOT memory curation (that is /prune-memory).

/reconcile — declared vs real

Overview

The open-work queue lies whenever a [x]/[ ] checkbox, a registry status, or an ## Index row has drifted from what git/fs actually show. /reconcile answers "what is really left?" by verifying, never by believing a declarative source.

Founding principle — recursive coherence: never use a declarative source as an oracle (not the Index, not a checkbox, not a status claim, not a path name). Truth = registry BODY (## ID — headings), git, fs. The skill practices what it preaches — lib/tests/run-reconcile.sh T1 reds if the engine ever reads the Index.

When to use

"Is the queue empty / what's left to do?" — the naive answer (grep '[ ]') is a mirror of the TODO and inherits all its lies.
A checkbox or status looks doubtful; work suspected stale after merges/pushes.
Before /close, or re-orienting after a break.

Not for: curating/compressing registries → /prune-memory. The skill never edits registry content (read-only here).

How it runs

REQUIRED ENGINE: lib/reconcile.sh does the mechanical truth-probing. A capable agent CAN reconcile by hand — but burns ~50k tokens, depends on the question being phrased well, and still hits traps (compound status, a disclaimer instead of a check). The engine is deterministic, cheap, repeatable. Source it, then:

Enumerate registry entries from BODY headings (reconcile_enumerate_ids, never the Index).
Per declared item, run the matching oracle (reconcile_oracle_*, reconcile_blk_current_status = last block wins) and apply reconcile_verdict.
Classify into the four categories.
Gate the write-back (below).

Output — four categories

Actionable now — open AND real state confirms not done.
Blocked (external) — reconcile_blk_open: current status upstream/open, not our code.
Deferred — lexically-marked follow-ups + [~] items (conditional triggers).
TODO↔real gap — declared ≠ verdict (open-but-done, done-but-open, partial-but-done).

Plus contradiction candidates — reconcile_contradiction_candidates: accepted-BDR ⇄ open-chantier overlap, surfaced for human review.

The gate (mandatory)

Before applying (A/B): follow $HOME/.claude/lib/gitflow-aiguillage.md — TYPE chore. On main/develop the write-back branches to chore/<name> off develop first, so a reconciled TODO never lands direct on a protected base; on a working branch it applies in place. Never gitflow finish (human-gated).

Reconciling the TODO edits a tracked file → never silent. Show the proposed diff, then ask: A apply all · B select a subset · C touch nothing. Registries stay READ-ONLY (append-only; curation is /prune-memory).

Honest limits (do not over-read the guarantee)

Deferral detection is lexical — catches MARKED deferrals, misses unmarked ("à reprendre quand X"). Deterministic on the detectable; surface the ambiguous for human review, never assert.
Contradictions are candidates (token overlap), not verdicts — a human confirms.
Cross-repo items (oracle in another repo) → "not verifiable here", never flagged stale.
Cross-reference verdicts ("[~] done because chantier X below is complete") are SURFACED, not auto-resolved.

Common mistakes

Grepping [ ] and reporting it as open → reproduces the lie. Run the oracle.
Reading the ## Index for status → inherits its drift (T1 forbids it).
Writing a disclaimer ("à vérifier si déjà fait") instead of verifying → the engine verifies, it never hedges-and-advances.

Validation

bash lib/tests/run-reconcile.sh → 25/25, shellcheck clean. Oracle of record = the 2026-06-29 inventory (7 gaps + 3 blocked + 5 deferred + 1 contradiction), fixtures frozen under neutral names in lib/tests/fixtures/.

4.2 KiB Raw Blame History