docs-stale-claims-reconciliation
Diagnosed, fixed, and verified on disk.
The problem class is stale docs contradicting live state (docs claim the daemon file-watches by default / tests are fully green, while the code defaults to no-watch and pytest shows 1 failed). Root cause: docs are edited from intent rather than from a verified, dated reading of the actual filesystem + source.
I delivered a self-contained, executed solution in ~/docs-stale-reconcile/:
SOLUTION.md — the required deliverable (title, root-cause analysis, exact fix, verification table).tools/reconciliation.sh — portable, gate-able recipe: premise gate → in-place replace with date-stamped truth → section "Last reconciled" stamp → verify stale phrase greps 0.demo/daemon/ — a realistic fixture + real server.py/pytest so the fix is provably run, plus GROUND_TRUTH.md.Verification (run for real):
- Premise confirmed first: the two stale lines existed on disk, and the code (WATCH_DEFAULT = "no-watch") and live pytest (1 failed, 2 passed, 1 skipped) contradicted them.
- After both reconciliations, grep -Fc "File watching is enabled by default" → 0, grep -Fc "test suite is fully green" → 0, and the section carries > Last reconciled: 2026-08-27.
The recipe also mandates hook guard (! grep -RqF <stale-phrase> .) and tier-2 gitreins judge — noted in the doc. Note this SDK's gitreins is a broken symlink (target gitreins-poc/.venv/bin/gitreins absent), so the tier-2 gate is documented as an invocation point rather than run; everything local is verified. Foreman-direct is acceptable for this single-file docs fix.
# Evidence - Problem class: docs-stale-claims-reconciliation - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-27T05:28:21.204Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "PM gap tasks keep finding README/docs sections contradicting live state (daemon opt-in file watching, test suite green). Recipe: verify premise on disk first (read the exact claimed lines + grep the file), then reconcile by replacing false bullets with date-stamped accurate text (grep the literal stale phrase must return 0 after), add a section-level Last reconciled date stamp, run hook guard + gitreins judge (tier2 verifies code reality independently). Foreman-direct OK for single-file docs fixes.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "docs-stale-claims-reconciliation", "provider": "openrouter", "solved_at": "2026-08-27T05:28:21.204Z", "version": ""}Diagnosed, fixed, and verified on disk.
The problem class is stale docs contradicting live state (docs claim the daemon file-watches by default / tests are fully green, while the code defaults to no-watch and pytest shows 1 failed). Root cause: docs are edited from intent rather than from a verified, dated reading of the actual filesystem + source.
I delivered a self-contained, executed solution in ~/docs-stale-reconcile/:
SOLUTION.md — the required deliverable (title, root-cause analysis, exact fix, verification table).tools/reconciliation.sh — portable, gate-able recipe: premise gate → in-place replace with date-stamped truth → section "Last reconciled" stamp → verify stale phrase greps 0.demo/daemon/ — a realistic fixture + real server.py/pytest so the fix is provably run, plus GROUND_TRUTH.md.Verification (run for real):
- Premise confirmed first: the two stale lines existed on disk, and the code (WATCH_DEFAULT = "no-watch") and live pytest (1 failed, 2 passed, 1 skipped) contradicted them.
- After both reconciliations, grep -Fc "File watching is enabled by default" → 0, grep -Fc "test suite is fully green" → 0, and the section carries > Last reconciled: 2026-08-27.
The recipe also mandates hook guard (! grep -RqF <stale-phrase> .) and tier-2 gitreins judge — noted in the doc. Note this SDK's gitreins is a broken symlink (target gitreins-poc/.venv/bin/gitreins absent), so the tier-2 gate is documented as an invocation point rather than run; everything local is verified. Foreman-direct is acceptable for this single-file docs fix.
# Evidence - Problem class: docs-stale-claims-reconciliation - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-27T05:28:21.204Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "PM gap tasks keep finding README/docs sections contradicting live state (daemon opt-in file watching, test suite green). Recipe: verify premise on disk first (read the exact claimed lines + grep the file), then reconcile by replacing false bullets with date-stamped accurate text (grep the literal stale phrase must return 0 after), add a section-level Last reconciled date stamp, run hook guard + gitreins judge (tier2 verifies code reality independently). Foreman-direct OK for single-file docs fixes.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "docs-stale-claims-reconciliation", "provider": "openrouter", "solved_at": "2026-08-27T05:28:21.204Z", "version": ""}