fix(cc-241): clean up v0.2.0 doc drifts surfaced by CC-219 gate#130
Merged
Conversation
The pre-milestone doc-freshness gate (CC-219, shipped in #129) flagged three pre-existing drifts when run against main. Fix: - BACKLOG.md:81 (CC-104p row): pr:TBD → pr:#114 (the actual merged PR that landed serialize_with_lock + routing-log fresh-HOME fix) - MILESTONES.md v0.2.0 section: rename "### Planned" → "### Roadmap (all shipped)" — the previous heading triggered the U2 keyword detection ("planned") even though every row is ✅; renaming kills the false positive without losing semantics (the v0.3.0 gate refinement is tracked separately) - README.md: add version badge linking to the v0.2.0 GitHub Release, satisfying U1's vN.N.N detection Verified: - bash scripts/check-docs-freshness.sh → 3 ok, 0 warnings, 0 blocking - bash scripts/check-docs-freshness.sh --json → valid JSONL - bash install.sh --verify --dry-run → preflight all suites pass Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
screenleon
added a commit
that referenced
this pull request
May 23, 2026
…day) Captures the agent-routing improvements proposed in the CC-060 retro: - CC-243 (🔵 active, P2): scripts/pm-prep-snapshot.sh writes a typed state snapshot to /tmp/pm-snapshot-<ts>.md before any PM agent spawn. Solves the two HALT classes hit during CC-242: caller brief carrying a stale main commit (#129+#130 had merged after the brief was written) and a ticket-ID collision (CC-241 was already consumed). Schema-like keys (branch_base/ticket_ids_consumed/project_tooling) chosen now to align with the future spike_v1 schema in CC-244. - CC-244 (🟢 someday): typed spike → brief → handover pipeline. Define spike_v1 schema + validator + gen-brief-from-spike helper. Deferred because only one spike doc (CC-060) exists today; schema value scales with N. Promote when 3+ spikes accumulate or an automation use case demands structured spike state. Validator: BACKLOG.md emits 31 E-* lines (unchanged from pre-existing CC-228 baseline; the 4 area/epic enum errors I initially hit on ops/agent-prep + agent-routing were resolved by picking valid tokens ops/arch + design). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
screenleon
added a commit
that referenced
this pull request
May 23, 2026
* backlog: add CC-243 (pm-prep-snapshot) + CC-244 (typed pipeline, someday) Captures the agent-routing improvements proposed in the CC-060 retro: - CC-243 (🔵 active, P2): scripts/pm-prep-snapshot.sh writes a typed state snapshot to /tmp/pm-snapshot-<ts>.md before any PM agent spawn. Solves the two HALT classes hit during CC-242: caller brief carrying a stale main commit (#129+#130 had merged after the brief was written) and a ticket-ID collision (CC-241 was already consumed). Schema-like keys (branch_base/ticket_ids_consumed/project_tooling) chosen now to align with the future spike_v1 schema in CC-244. - CC-244 (🟢 someday): typed spike → brief → handover pipeline. Define spike_v1 schema + validator + gen-brief-from-spike helper. Deferred because only one spike doc (CC-060) exists today; schema value scales with N. Promote when 3+ spikes accumulate or an automation use case demands structured spike state. Validator: BACKLOG.md emits 31 E-* lines (unchanged from pre-existing CC-228 baseline; the 4 area/epic enum errors I initially hit on ops/agent-prep + agent-routing were resolved by picking valid tokens ops/arch + design). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(cc-243): add pm pre-spawn snapshot capture * fix(cc-243): three pm-prep-snapshot bugs caught by local test run Codex's initial commit (d964e56) had three issues that the test suite caught on first local run: 1. printf '---\n' triggers `printf: --: invalid option` on bash 5.1.16 builtin printf — leading `---` is parsed as a flag prefix. Switched both occurrences to `printf '%s\n' '---'` (lines 246, 271). 2. `${#RECENTLY_MERGED[@]:-0}` is invalid bash syntax — the :- default operator cannot combine with the # length operator on an array. RECENTLY_MERGED is declared as an empty array at line 160, so `${#RECENTLY_MERGED[@]}` returns 0 safely. Dropped the :-0. 3. `collect_backlog_row()` used `awk -F'|'` and ran `gsub` on `$2` to trim whitespace for matching. Modifying `$2` causes awk to rebuild `$0` with the default OFS (space), which stripped all `|` from the emitted row — making the test for `| CC-244 |` literal fail. Fixed by copying `$2` into a local `candidate` variable, so `$0` stays untouched. The CC-243 test passing earlier was a false-positive: the literal `| CC-243 |` happens to appear inside the CC-243 body section's example YAML, so it matched there even though the actual row was malformed. Local verify: bash scripts/test-pm-prep-snapshot.sh -> 29 passed, 0 failed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(cc-243): address pr-gate findings (2 medium + 2 low) Gate findings on PR (CC-243 stacked on cc-060): - [medium, 3-reviewer overlap] Default snapshot output path used only a second-resolution timestamp (`/tmp/pm-snapshot-<ts>.md`); concurrent /pm spawns could collide and clobber each other's snapshots, feeding the wrong ground truth to PM. Switched the default to include PID + $RANDOM suffix (`/tmp/pm-snapshot-<ts>-$$.$RANDOM.md`), which is collision-resistant enough for solo + concurrent dispatches without introducing a mktemp portability concern. - [medium] Snapshot script hard-failed when `origin/main` could not be resolved (detached HEAD, missing remote, fresh local clone). Added a graceful fallback: try `origin/main` -> `main` (local) -> emit `branch_base: unresolved` with a `# warn:` line. The same fallback also degrades `ahead_by` to 0 + warns instead of hard-failing. - [low] BACKLOG.md CC-243 description claimed `project_tooling` was derived from a shell probe `ls Makefile project/backlog.yml 2>/dev/null`, but the script actually emits three fixed boolean keys (`makefile`, `backlog_render_target`, `has_validate_sh`). Updated the row text to match the impl contract and noted the map is extensible. Also updated the default OUT_PATH shape in the description and added pr:TBD ref (PR number unknown until open). - [low] CLI `--help` / unknown-flag paths had no test coverage. Added cli-help (exits 0, usage on stderr), cli-unknown-flag (non-zero, "unknown argument" message), and branch-base-warn-on-missing-origin-main (the medium #2 fix's positive case). Local verify: 31 tests passed (was 29), lint-scripts OK, validator emits 31 E-* lines (= CC-228 baseline unchanged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ci: add test-pm-prep-snapshot.sh to skill-refine shellcheck exclude Same pattern as the other test-*.sh harness consumers in this exclude list (test-codex-dispatch.sh, test-dispatch-handover.sh, ...): they source scripts/lib/test-harness.sh which exposes shared vars like tmp_root, and that pattern triggers a slew of style-tier shellcheck warnings (SC1090 non-constant source, SC2154 referenced-but-unassigned, SC2120 function arg passthrough). Excluding the file matches existing project policy rather than scattering inline disable directives. CI test-skill-refine job was red on PR #132 because the new file wasn't on the list. test-pm-prep-snapshot.sh itself was clean per the local `bash scripts/lint-scripts.sh` run (which uses a different shellcheck severity profile). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three pre-existing doc drifts flagged by the new CC-219 doc-freshness gate when run against main:
BACKLOG.md:81CC-104ppr:TBD(but ✅ closed)pr:#114MILESTONES.mdv0.2.0### Plannedheading triggers U2 keyword detection### Roadmap (all shipped)— kills the false positive, same semanticsREADME.mdhas novN.N.Nreference3-line diff. Pure data; no script/code touched.
Verified
bash scripts/check-docs-freshness.sh→ 3 ok, 0 warnings, 0 blockingbash scripts/check-docs-freshness.sh --json→ valid JSONLbash install.sh --verify --dry-run→ all preflight suites passNotes
### Plannedheading is renamed in v0.2.0 only (v0.1.0 doesn't use the same template). Future milestones using the same template would need the rename too; the broader fix is a CC-219 gate refinement (separate ticket).E-INDEX-MISMATCH/E-AREA-ENUM/E-REFS-PREFIXvalidator errors are unchanged — tracked under CC-228, out of scope here.Refs
🤖 Generated with Claude Code