docs(roadmap): verify and correct #434 sub-item status

ROADMAP.md

@@ -94,7 +94,7 @@ Living tracker of projects shipped using this wizard. **Rule:** only list projec
 | 302 | User-level setup-wizard + repo-local lifecycle split — **DESIGN-CERTIFIED, implementation deferred** | GH issue #302 proposes splitting the wizard so `setup` lives user-level/global and `sdlc`/`update`/`feedback` stay repo-local ("install once, bootstrap anywhere"). Cross-model design review completed 2026-05-20 (Codex gpt-5.5 xhigh, [`.reviews/302-design-codex-review.md`](.reviews/302-design-codex-review.md)) scored Claude's first-pass analysis 5/10 NOT CERTIFIED and replaced it with a concrete channel contract. **Decided channel split:** plugin channel = user-level/global path (already exists: `.claude-plugin/plugin.json` + `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}`); npm/npx = explicit repo-local bootstrap/update path; no npm `postinstall` writing to `~/.claude/` (fragile under CI/containers/read-only HOME/Windows). **Design questions answered:** (1) `setup` global via plugin, not also copied repo-local (precedence #338 makes the global copy dead weight when both exist); preserve auditability via `SDLC.md` metadata or install manifest, not duplicate same-name skill. (2) `feedback` global via plugin, can still read repo-local `SDLC.md` at invocation time. (3) `update-wizard` stays repo-local (reads `SDLC.md` metadata, runs drift detection, mutates project files). (4) `npm install -g` installs the CLI binary only — no lifecycle scripts. (5) Migration: leave existing repos unchanged; new split is opt-in only; later major release can stop copying `setup`/`feedback` repo-local for new installs. **Hard constraint Claude missed:** "global setup auto-triggers anywhere" is FALSE — `hooks/instructions-loaded-check.sh:14-22` and `hooks/sdlc-prompt-check.sh:27-35` exit silently when `SDLC.md`/`TESTING.md` don't exist, and `tests/test-hooks.sh:2507/2522` actively assert that silence. A plugin-only fresh-repo bootstrap signal must be designed before the global skill can satisfy the "always available" promise from the issue. **Existing dual-channel surface to respect:** `cli/init.js:286-302` blocks npm-on-plugin (duplicate `/update-wizard`), `hooks/instructions-loaded-check.sh:195-206` warns on dual install. Adding npm-global skills would create a third overlapping surface — deprecate one channel first. **Implementation sequence (5 steps, do NOT start without dedicated session):** (1) lock the channel contract in `CLAUDE_CODE_SDLC_WIZARD.md` + ARCHITECTURE.md; (2) doc the fresh-repo trigger limitation + migration story in #302 comment; (3) prototype plugin-only fresh-repo bootstrap signal + assert current silent-hook tests still pass; (4) write global-skill collision/backup/update tests if any installer touches `~/.claude/skills/`; (5) only then alter `init` behavior for new installs, leaving existing ones intact. **Why deferred 2026-05-20:** session shipped v1.74.0 → v1.75.0 → v1.75.1 (Trusted Publishing migration), maintainer fatigued, #302 is architectural — needs a fresh planning session. **Trigger to revisit:** explicit user request OR a second repo install where "install once" friction is felt acutely. |
 | 350 | CC feature-discovery cadence — replacement-for-#231 ranker has no enforced cadence | **Process gap discovered 2026-05-24 via #347 correction.** #231 Phase 3d (v1.54.0, 2026-04-29) deleted the in-CI Claude ranker from `weekly-update.yml` to take it to $0/week. The fallback was "maintainer runs `claude --print "$(cat .github/prompts/analyze-release.md)"` weekly on Max." That ran zero times in 5 weeks. Consequence: native CC `/goal` shipped in v2.1.139 (~mid-May) and was missed until a user asked a related question 2026-05-24 — wizard then published wrong research saying "no /goal exists." 39 CC versions accumulated since the last auto-PR (v2.1.118 → v2.1.150). **Scope (Actionable now, low-cost cleanup):** (a) restore a thin cron — `weekly-update.yml` still runs detection ($0 GH API call); add a single follow-up step that opens a "CC version drift" GitHub issue when our `<!-- SDLC Wizard Version -->` baseline is >5 minor versions behind latest npm — pure GitHub API, no LLM, no API spend; (b) the issue body links the maintainer to the on-Max command + the changelog URL + a one-line "what to do" reminder; (c) session-start `instructions-loaded-check.sh` already has the staleness nudge (#196 — "N minor versions behind") — verify it actually fires when the gap is ≥3 minor AND link to the analyze-release runbook in the loud branch. **Why this beats #85 Phase 2** (which we killed 2026-05-24): #85 Phase 2 was "auto-rank features in CI via LLM" — expensive and conflicted with #231. This is "open a stale-baseline issue when we detect drift" — cheap, GH API only, just a maintainer reminder. **Status:** DONE 2026-05-25 (PR #354, v1.77.0 — `.github/workflows/cc-version-drift.yml` ships: Mon 09:30 UTC cron + workflow_dispatch, `scripts/cc-drift-check.sh` SemVer-delta logic, machine-readable issue marker for idempotent edits, only re-opens closed issues when delta WIDENED. Verified live 2026-05-25 via manual workflow_dispatch on main: ran clean, "Open or update tracking issue" step SKIPPED — silent when no drift, as designed). Paired with #347 in same release arc. |
 | 424 | Cowork plugin enhancement — prompt-based hooks, verified install, README corrections | **Maintainer pain event:** `cowork/` plugin exists (PR #410, v1.83.0) with 2 skills (sdlc + feedback) and CI drift tests, but has NEVER been installed or tested in a real Cowork session. README says "Cowork hook support is unverified" — **this is wrong.** Anthropic's own `cowork-plugin-management` plugin (v0.2.2, `knowledge-work-plugins` marketplace) documents hooks as first-class plugin components with 9 event types including **prompt-based hooks** that need no shell access. Deep-research workflow (2026-06-19, 101 agents, Codex 7/10) confirmed Claude Cowork is a separate product from Claude Code but shares the same plugin format. **Scope (multi-phase):** (a) Verify install path — actually install the plugin in a Cowork session via GitHub URL, confirm skills load and invoke correctly; (b) Add prompt-based hooks — TDD reminder (`PreToolUse` on Write/Edit), SDLC baseline injection (`UserPromptSubmit`), confidence check (`Stop`). Use `"type": "prompt"` not `"type": "command"` — no shell needed; (c) Update README — remove "unverified" language, clarify Code vs Cowork product distinction, document prompt-hook enforcement; (d) Update `tests/test-cowork-drift.sh` Test 8 — flip from "no hooks = PASS" to "hooks exist and match format = PASS"; (e) Evaluate adding SDLC-specific agents (code-reviewer, tdd-checker) per plugin agent schema. **Entry gate:** maintainer pain event — dead code with CI tests, never tested in target environment. Relates to #302 (user-level setup split) — Cowork plugin is the "global" distribution surface. **Token cost note:** `/deep-research` used for initial research burned 2.5M tokens (23x median session, GH issue #423). Do NOT use for follow-up work — use targeted WebFetch. |
-| 434 | AI Setup Lanes v3 — Sonnet 5 + model-aware effort + auto-escalation | **Maintainer pain event:** AI_SETUP_LANES.md still references Sonnet 4.6 and recommends blanket `max` effort. Sonnet 5 launched June 30 and beats Opus 4.6 on every benchmark (SWE-bench Verified 85.2% vs 80.8%, Terminal-Bench 80.4% vs 65.4%). Opus 4.6 cannot advise Sonnet 5 (pairing table rejects it). Fable+Codex cross-model review both confirmed: Sonnet 5 high + Fable advisor is the new recommended primary, Opus 4.8 xhigh for escalation. **Scope (multi-part):** (a) ✅ DONE: Update AI_SETUP_LANES.md with Sonnet 5, model-aware effort per model, escalation ladder (PR pending); (b) Update `model-effort-check.sh` to recommend effort per model (not blanket max) — Sonnet 5: high/xhigh, Opus 4.8: xhigh, Opus 4.6: max, Fable: high; (c) Update `/sdlc` skill frontmatter from `effort: max` to model-aware; (d) Add auto-escalation detection to `sdlc-prompt-check.sh` — after 3+ failures or context >200K, suggest `/effort xhigh` then `/model opus`; (e) Add quota-burn awareness — detect when session is burning Max limits fast and suggest effort downgrade; (f) Sync updated lanes to sibling wizards (gdlc, rdlc) — **still open 2026-07-05.** Maintainer intent: fold this into the Fable-led sibling upgrade pass (#438) once this repo's own v1.84.0 retrospective fixes land, rather than a separate sync pass — one Fable run per sibling repo covers both the Lanes v3 sync and the #438 bloat/review sweep. **Entry gate:** maintainer pain event — stale model recommendations, Opus 4.6 pairing broken with Sonnet 5. Cross-model verified: Fable recommended Opus 4.6 stability, Codex recommended Sonnet 5 switch — data favors Sonnet 5 but wizard lets users choose. |
+| 434 | AI Setup Lanes v3 — Sonnet 5 + model-aware effort + auto-escalation | **Maintainer pain event:** AI_SETUP_LANES.md still references Sonnet 4.6 and recommends blanket `max` effort. Sonnet 5 launched June 30 and beats Opus 4.6 on every benchmark (SWE-bench Verified 85.2% vs 80.8%, Terminal-Bench 80.4% vs 65.4%). Opus 4.6 cannot advise Sonnet 5 (pairing table rejects it). Fable+Codex cross-model review both confirmed: Sonnet 5 high + Fable advisor is the new recommended primary, Opus 4.8 xhigh for escalation. **Scope (multi-part) — status verified 2026-07-10, not just re-asserted:** (a) ✅ DONE (v1.84.0, extended by #439): AI_SETUP_LANES.md has Sonnet 5, model-aware effort per model, escalation ladder, and (as of #439) GPT-5.6 Sol as reviewer. (b) ✅ DONE (v1.84.0): `hooks/model-effort-check.sh` implements a model-independent floor (SessionStart's payload has no model field, so it can't detect which model is active) — `high`/`xhigh` are always silent; `max` is silent only when set via the `CLAUDE_CODE_EFFORT_LEVEL` env var, since Claude Code doesn't actually persist a settings.json-only `max` (that case still warns, correctly — it's a real CC quirk, not a bug in this row's claim). Blanket "max is the only acceptable value" nagging is gone. (c) ✅ DONE (v1.84.0): `skills/sdlc/SKILL.md`'s hardcoded `effort: max` frontmatter was removed in the same release (git history confirms); driver effort now comes from the session/lane, not the skill. (d) **Partially superseded, not simply "still pending"** — (d)'s full original scope (3+ failures OR context >200K, escalating to both `/effort xhigh` and `/model opus`) was never fully built. What existed was narrower: ROADMAP #195's "Dynamic effort auto-bump hook" (`sdlc-prompt-check.sh` scanning prompts for LOW-confidence/FAILED/CONFUSED signals, firing after 2 signals in a 30-min window, suggesting only `/effort xhigh` — no context-size trigger, no `/model opus` escalation). That narrower detector was explicitly reviewed and *kept* during the v1.69.0 bloat audit ("earned its keep and stayed untouched," per CHANGELOG.md's v1.69.0 entry — CHANGELOG only records the original addition, not what came next), then later **deleted 2026-07-06** during #236(b)'s follow-up bloat-hunt as "unfired" (per ROADMAP #236's own entry and commit `3aa2779`). So: the failure-signal half of (d) was built, judged valuable once, later judged unfired and removed; the context-size/model-escalation half was never attempted. Re-scoping (d) means deciding whether to rebuild the once-killed mechanism or try the untried half — not a clean "still open" or "fully superseded." (e) **Adjacent detector exists, but not this one** — `hooks/token-spike-check.sh` (ROADMAP #220) already does automated, per-session token-burn detection: it reads transcript history and warns when the *last completed* session's burn deviates >2σ above the rolling median, catching CC-side regressions (caching bugs, prompt-inflation defaults). That's a different problem than (e) asked for: a *live*, in-session monitor that watches the Max 5-hour-cap burn rate as it happens and suggests an effort downgrade before the cap hits, not a post-hoc statistical-anomaly check against past sessions. No hook does that. The concept is otherwise only manual guidance (`AI_SETUP_LANES.md`'s Credit-Spend Warning section, a `/usage` doc-table row pairing quota-burn investigation with `scripts/audit-session-load.sh`). Per this repo's own Prove-It Gate ("new addition? default answer is NO — real gap or theoretical?"), leave the live-monitor half unbuilt until a real incident motivates it. (f) **Tracked, not started** — today's GPT-5.6 sibling issues ([claude-gdlc-wizard#15](https://github.com/BaseInfinity/claude-gdlc-wizard/issues/15), [claude-rdlc-wizard#10](https://github.com/BaseInfinity/claude-rdlc-wizard/issues/10)) plus follow-up comments flag both gaps (stale reviewer model AND the missing Sonnet-5 driver lane) — but neither sibling repo has actually changed yet; both `AI_SETUP_LANES.md` files still use GPT-5.5 and Opus 4.6 as primary as of this writing. Filing/commenting is visibility, not implementation. **Entry gate:** maintainer pain event — stale model recommendations, Opus 4.6 pairing broken with Sonnet 5. Cross-model verified: Fable recommended Opus 4.6 stability, Codex recommended Sonnet 5 switch — data favors Sonnet 5 but wizard lets users choose. |
 | 425 | Dynamic Workflows + ultracode evaluation — CC v2.1.154 feature we missed | **Maintainer pain event (#350 cadence gap manifested again).** CC v2.1.154 (May 28, 2026) shipped Dynamic Workflows — JavaScript scripts orchestrating subagents at scale. We're on v2.1.173 and missed it for 3 weeks. ROADMAP #71 (KAIROS/Coordinator Mode) was watching for this class of feature — Dynamic Workflows may or may not be related to KAIROS internally (not verifiable from public sources). Deep-research (2026-06-19, Codex 7/10 verified) confirmed: (a) only built-in workflow is `/deep-research`; custom workflows save to `.claude/workflows/` (project) or `~/.claude/workflows/` (user); (b) `ultracode` is a new effort level (`/effort ultracode`) = xhigh reasoning + automatic workflow orchestration, session-only; (c) `agent()`, `parallel()`, `pipeline()`, `phase()` primitives are NOT in official Anthropic docs — internal implementation, treat as non-public API; (d) Agent Teams are separate (experimental, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`), not superseded. **Scope:** (a) Update #71 wording — Dynamic Workflows shipped as the public multi-agent orchestration feature, relationship to KAIROS unknown, Agent Teams still separate/experimental; (b) Evaluate `ultracode` vs `max` — Codex says ultracode should NOT replace max as default (it's xhigh + auto-workflow, not deeper reasoning), document as opt-in escalation for audits/migrations/research; (c) Document Workflows in wizard — when to use, cost awareness (deep-research = 2.5M tokens), `.claude/workflows/` save path; (d) Evaluate whether wizard should ship custom SDLC workflows (Prove-It Gate applies — prove quality before adding). **Entry gate:** maintainer pain event — #350 cadence gap. Sources: [code.claude.com/docs/en/workflows](https://code.claude.com/docs/en/workflows), [Anthropic blog](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code), Codex review `.reviews/codex-deep-research-triage.md`. |
 | 436 | Fable self-enforcement audit — codex-gate-check.sh + tdd-pretool-check.sh never actually blocked | **Maintainer pain event 2026-07-04:** "I hate having to remind 'don't forget to cross-model review with codex'." Root-cause audit found two enforcement hooks that printed the right warning text but always `exit 0` — including on their "REQUIRED"/blocking branches. Claude Code only denies a `PreToolUse` call on `exit 2` + stderr; `exit 0` always allows regardless of stdout content. Both hooks had shipped this way since introduction, silently decorative the whole time. **Scope shipped:** (a) `codex-gate-check.sh` — the two "CROSS-MODEL REVIEW REQUIRED" branches now `exit 2`; (b) `tdd-pretool-check.sh` — new edit-ordering gate blocks (`exit 2`) writes to `src/**` unless a test file was touched earlier in the session (proxy for TDD RED — a bash hook can't run the suite to confirm a real failing test, this is the best mechanically-available approximation); (c) new `Stop` hook (`codex-review-stop-check.sh`) closes a third gap — a session can end with `git commit` never invoked, so the Bash-triggered gate never fires; non-blocking (Stop can't deny), warns once per session on significant uncommitted changes with no REVIEWED/CERTIFIED handoff; (d) fixed 3 pre-existing distribution-parity bugs surfaced by a new stronger test (`test_hooks_json_script_parity`, compares actual registered scripts per hook event, not just event-name presence) — `codex-gate-check.sh` was never wired into the plugin's `hooks/hooks.json` (plugin users had zero cross-model gate), `goal-confidence-check.sh` was missing from the project's own `.claude/settings.json`, `token-spike-check.sh` was missing from the CLI template and from `cli/init.js`'s FILES array entirely (never actually copied to consumer repos by `npx ... init`). **Entry gate:** maintainer pain event — the exact mechanism this whole wizard exists to provide (mechanical enforcement instead of verbal reminders) was non-functional. **Verified:** 22 test files run clean post-fix (185 hook tests run twice for isolation, plus doc-consistency/cowork-drift/cli/plugin/audit-session-load/tdd-fires-once and 15 more referencing the changed files). |
 | 437 | Codex-gate handoff staleness — `.reviews/handoff.json` status isn't checked for freshness or branch match | **Found while shipping #436, 2026-07-04:** `codex-gate-check.sh` only checks `.reviews/handoff.json`'s `status` field (`CERTIFIED`/`REVIEWED` → allow commit). It does not check `review_id`, `branch`, `requested_at` staleness, or that `files_changed` overlaps the actually-staged diff. Live evidence: a week-old `REVIEWED` handoff (`review_id: "drift-baseline-fix-001"`, dated 2026-06-28, for an already-merged and unrelated PR #431) was still sitting in `.reviews/` and would have silently satisfied the gate for #436's entirely different, never-reviewed changes had it not been manually overwritten before committing. **Independently re-confirmed 2026-07-05** via the v1.84.0 post-ship retrospective (Fable + Codex dual audit): 2 real commits landed after round-11 CERTIFIED and both sailed through the gate on the same stale certification — proving the gap live a second time, on this exact hook. **Design settled (Fable-reviewed 2026-07-05), simpler than the branch/files_changed idea above:** certification writes `commit_sha` (HEAD at cert time) into `handoff.json`; the gate compares current `git rev-parse HEAD` to that SHA — mismatch (or missing `commit_sha`, e.g. old-format handoff files) = stale, exit 2. This directly answers the open design question below: it allows exactly one commit after certification (HEAD still equals the recorded SHA at that commit's `PreToolUse` check) and blocks the next one until re-cert, rather than needing a branch/superset-diff heuristic. `CODEX_GATE_SKIP=1` remains the logged-justification escape hatch for legitimate small follow-ups. **Original open design question (superseded by the above):** how to avoid false-positiving on legitimate small follow-up commits after a review already covered the substance (e.g. a one-line typo fix Codex itself suggested) — a naive "any new diff invalidates the handoff" rule would defeat the recheck/dialogue loop the protocol already relies on. **Entry gate:** maintainer pain event — demonstrated live twice now, not theoretical. Not fixed in #436 (separate, non-trivial concern; scope discipline). **Status: ✅ DONE 2026-07-05** (v1.86.0 — Pass 2 of the v1.84.0 retrospective fix plan, standalone TDD PR, 2 new tests + 2 existing tests updated to real git-repo fixtures, 191/191 hook tests green). |