docs-cli-readme-drift
Solution delivered. Summary:
The README's command table and Limitations section were hand-maintained. When start/stop/daemon/mcp shipped in the CLI, README.md wasn't regenerated: the table listed 4 of 8 commands, and Limitations claimed "no file watcher and no daemon … planned for a future release" — a direct contradiction of the shipped binary. Nothing enforced docs↔CLI sync.
~/speclang-cli/)scripts/sync-readme-commands.py — runs bin/speclang --help, extracts the Commands: section, and rebuilds the | Command | Description | table in README.md (8 rows: build, daemon, format, init, mcp, start, stop, validate).start/stop/daemon/mcp) and states the real limits (single-host watchers, format-rule reload needs daemon restart).scripts/verify-readme-commands.py — the programmatic gate: parses --help → Commands:, asserts every command appears in the README table, flags stale rows, and rejects Limitations text that denies/omits shipped commands.FAIL: commands in --help missing from README table: daemon, mcp, start, stop; Limitations still denies … 'planned' (exit 1)OK: all 8 commands from --help are in the README command table; no stale rows; Limitations matches the CLI surface. (exit 0)stale README table rows … frobnicate and 'planned' — proving the gate catches both table drift and limitation regression.Deliverable: ~/solution.md (self-contained: exact code, commands, before/after verification output); demo repo with mock CLI + scripts at ~/speclang-cli/.
# Evidence - Problem class: docs-cli-readme-drift - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-16T10:26:05.871Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "README documented limitations/command table contradicted shipped CLI. Fix: regenerate the command table from live `bin/speclang --help` output (extract Commands: section) and rewrite limitations to acknowledge daemon/file-watcher (start/stop/daemon/mcp exist). Verify programmatically: parse --help, assert every command appears in the README table.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "docs-cli-readme-drift", "provider": "openrouter", "solved_at": "2026-08-16T10:26:05.871Z", "version": ""}Solution delivered. Summary:
The README's command table and Limitations section were hand-maintained. When start/stop/daemon/mcp shipped in the CLI, README.md wasn't regenerated: the table listed 4 of 8 commands, and Limitations claimed "no file watcher and no daemon … planned for a future release" — a direct contradiction of the shipped binary. Nothing enforced docs↔CLI sync.
~/speclang-cli/)scripts/sync-readme-commands.py — runs bin/speclang --help, extracts the Commands: section, and rebuilds the | Command | Description | table in README.md (8 rows: build, daemon, format, init, mcp, start, stop, validate).start/stop/daemon/mcp) and states the real limits (single-host watchers, format-rule reload needs daemon restart).scripts/verify-readme-commands.py — the programmatic gate: parses --help → Commands:, asserts every command appears in the README table, flags stale rows, and rejects Limitations text that denies/omits shipped commands.FAIL: commands in --help missing from README table: daemon, mcp, start, stop; Limitations still denies … 'planned' (exit 1)OK: all 8 commands from --help are in the README command table; no stale rows; Limitations matches the CLI surface. (exit 0)stale README table rows … frobnicate and 'planned' — proving the gate catches both table drift and limitation regression.Deliverable: ~/solution.md (self-contained: exact code, commands, before/after verification output); demo repo with mock CLI + scripts at ~/speclang-cli/.
# Evidence - Problem class: docs-cli-readme-drift - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-16T10:26:05.871Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "README documented limitations/command table contradicted shipped CLI. Fix: regenerate the command table from live `bin/speclang --help` output (extract Commands: section) and rewrite limitations to acknowledge daemon/file-watcher (start/stop/daemon/mcp exist). Verify programmatically: parse --help, assert every command appears in the README table.", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "docs-cli-readme-drift", "provider": "openrouter", "solved_at": "2026-08-16T10:26:05.871Z", "version": ""}