From bcce705d3968b00c6359483d9dce9cc7382f39df Mon Sep 17 00:00:00 2001 From: Stefan Ayala Date: Sun, 5 Jul 2026 14:49:11 -0700 Subject: [PATCH] docs(v1.85.0): post-ship retrospective fixes for v1.84.0 Independent Fable + Codex audit of the just-shipped v1.84.0 release found 4 gaps in CLAUDE_CODE_SDLC_WIZARD.md: - Stale "7 rounds" example (actually 11); round 8, not round 5, was the sharper illustrative finding - Missing "CERTIFIED is not the finish line" lesson (cross-model review and CI are different verification layers) - CI Feedback Loop section weaker than skills/sdlc/SKILL.md's own copy (missing NEVER AUTO-MERGE, read-logs-even-when-green, cross-model CI-log audit) - No Policy Migration Inventory checklist item, despite SDLC.md already documenting this exact lesson from v1.84.0 Also settles ROADMAP #437's open design question (commit_sha-based staleness check, implementation to follow as a separate TDD PR) and records maintainer intent for #434/#438 (Fable-led sibling-repo sync after this release, not GH issue posting from this session). Version bumped 1.84.0 -> 1.85.0 across all tracked locations. Codex cross-model review (2 rounds) caught 2 more stale version pointers outside the documented checklist (ROADMAP.md living-tracker row, cowork/README.md) - fixed, and the checklist itself updated so the gap doesn't recur. --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- CHANGELOG.md | 13 +++++++++++++ CLAUDE_CODE_SDLC_WIZARD.md | 17 +++++++++++------ ROADMAP.md | 8 ++++---- SDLC.md | 6 +++--- cowork/.claude-plugin/plugin.json | 2 +- cowork/README.md | 2 +- package.json | 2 +- skills/update/SKILL.md | 4 ++-- 10 files changed, 38 insertions(+), 20 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 51ffa882..818395f9 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ "name": "sdlc-wizard", "source": ".", "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd", - "version": "1.84.0", + "version": "1.85.0", "author": { "name": "Stefan Ayala" }, diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a827eac1..7c198310 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sdlc-wizard", - "version": "1.84.0", + "version": "1.85.0", "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd", "author": { "name": "Stefan Ayala", diff --git a/CHANGELOG.md b/CHANGELOG.md index bb85d8f0..b3c2c97e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,19 @@ All notable changes to the SDLC Wizard. > **Note:** This changelog is for humans to read. Don't manually apply these changes - just run the wizard ("Check for SDLC wizard updates") and it handles everything automatically. +## [1.85.0] - 2026-07-05 + +### Fixed +- **Post-ship retrospective on v1.84.0** (independent Fable + Codex audits, both verified against primary sources before acting on them): `CLAUDE_CODE_SDLC_WIZARD.md`'s "Exception — known-large migrations" example still cited the wrong round count ("7 rounds... round 5") after the review ran to 11 rounds and round 8 turned out to be the more consequential find — corrected to the actual numbers. +- The `### Convergence` section had no record of this release's own sharpest lesson: cross-model review and CI are different verification layers. Round-11 CERTIFIED plus a full local sweep still missed 3 real bugs (a content regression, an npm-version JSON format change, a missing executable bit) that only surfaced once the PR was actually pushed and CI ran. Added a "CERTIFIED is not the finish line" callout so this isn't relearned per-release. +- `## CI Feedback Loop — Local Shepherd` (the portable wizard doc's version) was measurably weaker than `skills/sdlc/SKILL.md`'s own copy of the same section — missing "read CI logs even when green" (a green checkmark hides warnings/skipped steps/degraded scores — see v1.24.0), missing the cross-model CI-log-audit step, missing explicit "NEVER AUTO-MERGE" language (PR #145 evidence). Synced to match. +- `Release Review Focus` had no "Policy Migration Inventory" checklist item, despite the wizard doc itself documenting (in `SDLC.md`'s Lessons Learned) that exactly this gap is what turned v1.84.0's migration into an 11-round review instead of ~4-5. Added, with v1.84.0 as the cited evidence. +- `ROADMAP.md` #437 (the codex-gate handoff-staleness gap, filed 2026-07-04) settled its previously-open design question: `commit_sha`-in-`handoff.json` compared against current HEAD, not a branch/files-changed heuristic — simpler, and directly answers the "how do legitimate follow-up commits not false-positive" question the original entry raised. Implementation is a separate, standalone TDD PR (not bundled with this doc-only release). +- **Codex round 1 caught 2 more stale `1.84.0` version pointers this release's own version-bump checklist didn't cover:** `ROADMAP.md`'s "Built With SDLC Wizard" living-tracker row (this repo's own entry) and `cowork/README.md`'s "Version" section — neither matches the canonical checklist's two string patterns (`SDLC Wizard Version:` prefix or a `"version":` JSON key), since both read as plain prose. Fixed, and `SDLC.md`'s version-bump-checklist lesson updated with a broader canonical grep (`grep -rn "" . --include="*.md" --include="*.json"`, manually triage every hit) so the narrower two-pattern grep isn't the only check next release. + +### Why +Same-session retrospective (2026-07-05) on the just-shipped v1.84.0: the user asked Fable and Codex, independently, "how well did this release follow its own `/sdlc` checklist, and what's missing from the doc itself." Both converged on real, independently-verified findings — this release fixes the doc-only subset; the hook-behavior fix (#437) and any sibling-repo (`claude-gdlc-wizard`, `claude-rdlc-wizard`, etc.) sync follow as separate, explicitly-scoped work per Fable's own recommendation to split rather than bundle. + ## [1.84.0] - 2026-07-04 ### Fixed diff --git a/CLAUDE_CODE_SDLC_WIZARD.md b/CLAUDE_CODE_SDLC_WIZARD.md index 18e47aae..8bb9e62c 100644 --- a/CLAUDE_CODE_SDLC_WIZARD.md +++ b/CLAUDE_CODE_SDLC_WIZARD.md @@ -2503,7 +2503,9 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e 3 recheck rounds (4 total including initial review) is the default budget for a typical change. If still NOT CERTIFIED after round 4, escalate to the user with a summary of open findings rather than spinning indefinitely. -**Exception — known-large migrations:** the round cap is a heuristic against spinning on a shrinking tail of nitpicks, not a hard stop. Judge convergence by the *trend* in finding quality, not the round number: if every round is still surfacing a genuinely new, independently-verified, real issue — especially if severity is flat or increasing (later rounds finding live-code bugs, not just prose) — keep going past round 4. Only stop when a round returns CERTIFIED, or consecutive rounds return nothing but nitpicks/false positives. (Source: v1.84.0 release review — a repo-wide model-recommendation migration ran 7 rounds, each finding something real; round 5 found a live `SessionStart` hook actively contradicting the new policy, more consequential than anything rounds 1-3 found. Escalating at round 4 per the default heuristic would have shipped that bug. 2026-07-04.) +**Exception — known-large migrations:** the round cap is a heuristic against spinning on a shrinking tail of nitpicks, not a hard stop. Judge convergence by the *trend* in finding quality, not the round number: if every round is still surfacing a genuinely new, independently-verified, real issue — especially if severity is flat or increasing (later rounds finding live-code bugs, not just prose) — keep going past round 4. Only stop when a round returns CERTIFIED, or consecutive rounds return nothing but nitpicks/false positives. (Source: v1.84.0 release review — a repo-wide model-recommendation migration ran 11 rounds, each finding something real; round 8 found a mandatory-reading setup-wizard template whose tutorial hook code had silently drifted from the real shipped hook (broken, non-blocking), more consequential than anything in rounds 1-3. Escalating at round 4 per the default heuristic would have shipped that bug. 2026-07-04.) + +**CERTIFIED is not the finish line.** A CERTIFIED verdict and a green CI run are different verification layers that catch different bug classes — a CERTIFIED review does not substitute for actually pushing and watching CI. Confirmed on the same v1.84.0 release: after round-11 CERTIFIED and a full local test sweep, real CI still caught 3 more genuine bugs the review never touched — a content regression in an unrelated section silently dropped by an earlier edit (caught by a pre-existing local test that simply hadn't been re-run since), an environment-specific CLI output-format change invisible to any local run against an older tool version, and a new test file committed without the executable bit (passes every local `bash tests/foo.sh` invocation, only fails when CI runs it as `./tests/foo.sh`). Budget for at least one more fix-push-recheck cycle after CERTIFIED, and don't treat CERTIFIED as license to skip reading the actual CI logs — see the CI Feedback Loop section below. ``` Self-review passes → handoff.json (round 1, PENDING_REVIEW) @@ -2539,8 +2541,9 @@ Before any release/publish, add these to `review_instructions`: - **Stale examples** — hardcoded version strings in docs match current release - **Docs accuracy** — README, ARCHITECTURE.md reflect current feature set - **CLI-distributed file parity** — live skills, hooks, settings match CLI templates +- **Policy Migration Inventory** — for a repo-wide blanket-recommendation migration (e.g. changing a default model, effort level, or policy referenced in many places), enumerate every surface it could touch *before* the first review round: skill frontmatter, setup/update wizard menus, live hooks, tutorial doc templates, CHANGELOG. Discovering surfaces one review round at a time is what turns a 4-5 round review into an 11-round one. -Evidence: v1.20.0 cross-model review caught CHANGELOG section loss and stale wizard version examples that passed all tests and self-review. +Evidence: v1.20.0 cross-model review caught CHANGELOG section loss and stale wizard version examples that passed all tests and self-review. v1.84.0's Sonnet-5-default migration ran 11 rounds because each round surfaced a new, previously-uninventoried surface (skill frontmatter, then setup wizard, then a live hook, then tutorial templates) rather than catching them all upfront. ### Multiple Reviewers (N-Reviewer Pipeline) @@ -2663,12 +2666,12 @@ Reproduce → Isolate → Root Cause → Fix → Regression Test **This is the "local shepherd" — your CI fix mechanism.** It runs in your active session with full context. -**The SDLC doesn't end at local tests.** CI must pass too. +**The SDLC doesn't end at local tests.** CI must pass too. **NEVER AUTO-MERGE — do NOT run `gh pr merge --auto`.** Auto-merge fires before review feedback can be read; the shepherd loop below IS the process. (Evidence: PR #145 auto-merged before its review was read — a reviewer-found P1 dead-code bug shipped as a result.) ``` Local tests pass -> Commit -> Push -> Watch CI | - CI passes? -+-> YES -> Present for review + CI passes? -+-> YES -> Read logs anyway -> Cross-model audit -> Present for review | +-> NO -> Fix -> Push -> Watch CI | @@ -2697,7 +2700,9 @@ Local tests pass -> Commit -> Push -> Watch CI - Diagnose root cause (same philosophy as local test failures) - Fix and push again 4. Max 2 fix attempts - if still failing, ASK USER -5. If CI passes - proceed to present final summary +5. **Read CI logs whether pass or fail — not just on failure.** A green checkmark hides warnings, skipped steps, and degraded scores (v1.24.0 shipped a degraded E2E score and a silently excluded test suite behind a passing check). Use `gh run view --log`, not just `--log-failed`. +6. **Cross-model audit the CI logs** — same `codex exec` pattern as the Cross-Model Review Loop above. Prompt: *"Audit for silent failures, skipped tests, degraded metrics, warnings-that-should-be-errors."* Do this even when every check is green. +7. Only after logs are read and audited — proceed to present final summary **Context GC (compact during idle):** While waiting for CI (typically 3-5 min), suggest `/compact` if the conversation is long. Think of it like a time-based garbage collector — idle time + high memory pressure = good time to collect. Don't suggest on short conversations. @@ -3070,7 +3075,7 @@ If deployment fails or post-deploy verification catches issues: **SDLC.md:** ```markdown - + diff --git a/ROADMAP.md b/ROADMAP.md index 26957010..837e5b8b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -207,7 +207,7 @@ Living tracker of projects shipped using this wizard. **Rule:** only list projec | Project | Repo | Status | |---------|------|--------| -| SDLC Wizard itself | BaseInfinity/claude-sdlc-wizard | Dogfooded, v1.84.0 | +| SDLC Wizard itself | BaseInfinity/claude-sdlc-wizard | Dogfooded, v1.85.0 | | Codex SDLC Adapter | BaseInfinity/codex-sdlc-wizard | v0.7.x, shipped with SDLC workflow | | GDLC Wizard (games sibling) | BaseInfinity/claude-gdlc-wizard | v0.2.x, persona-driven playtest cycles | | _(add as projects are marked)_ | | | @@ -318,9 +318,9 @@ Living tracker of projects shipped using this wizard. **Rule:** only list projec | 347 | Goal-mode checkpoint workflow (Codex `$gdlc` equivalent) — **CORRECTED 2026-05-24: native `/goal` exists, scope shrunk to ~30-line skill wrapper** | GH issue #347 asks whether Claude Code has a native primitive for long-running goal-bound work (Codex `$sdlc + $gdlc` pattern with persistent constraints, checkpoint cadence, explicit stop boundaries). **2026-05-23 research was WRONG** — claude-code-guide subagent said no native primitive, but CC **v2.1.139 shipped native `/goal`** (confirmed via raw changelog curl; docs at [code.claude.com/docs/en/goal.md](https://code.claude.com/docs/en/goal.md); follow-up fixes v2.1.140 hook-disabled hang + v2.1.143 subagent race). Corrected research at [`.reviews/347-goal-mode-research-CORRECTED.md`](.reviews/347-goal-mode-research-CORRECTED.md). **What `/goal` does:** session-scoped, evaluator-driven (Haiku default judges transcript after each turn yes/no), survives `--resume` but not `/clear`, no disk writes, no native turn/time cap. UX = `/goal ` + `/goal` (status) + `/goal clear`. **Old verdict OBE.** **Corrected scope = ~30-line skill wrapper in existing `/sdlc` (NOT a `GOAL.md` template — `/goal` writes nothing to disk).** Per [`.reviews/347-goal-mode-research-CORRECTED.md`](.reviews/347-goal-mode-research-CORRECTED.md), the wizard should add: (a) **pre-flight checklist** — workspace trusted, hooks not disabled at any settings layer, CC ≥ v2.1.143; (b) **condition-writing guidance** mirroring SDLC reporting standards (measurable end state + check + constraints + hard turn/time bound since `/goal` has no native cap); (c) **compose-with-hooks note** — `UserPromptSubmit`/`SessionStart`/`PreCompact` fire normally inside the goal loop, so `sdlc-prompt-check.sh` + `precompact-seam-check.sh` keep gating each turn; (d) **resume caveat** — `--resume` resets turn/time counters; (e) **anti-pattern callout** — don't use `/goal` for "doneness" the evaluator can't see in the transcript (evaluator can't call tools). **Status:** DONE 2026-05-24 (PR #351, v1.76.0 — `/goal` wrapper section added to `/sdlc` skill + `/update` skill changelog entry; followed by PR #355 v1.77.0 adding HIGH-95% confidence gate + DLC-binding requirement + condition-as-contract guidance). **Original 5-step plan + `GOAL.md` template scaffolding OBE.** **Meta-lesson captured in CORRECTED doc:** require explicit citation of an authoritative source (docs index, raw changelog grep) before accepting a "feature does not exist" claim — negative claims are easier to fake than positive ones. **Process gap also caught:** auto-update PR workflow stopped flagging features at CC v2.1.118 (2026-04-23, last PR #210) because #231 Phase 3d (v1.54.0) gutted the in-CI LLM-ranker to $0. Manual replacement (`claude --print --allowedTools "WebFetch,Read,Bash" "$(cat .github/prompts/analyze-release.md)"`) was supposed to run weekly on Max — it didn't, which is how `/goal` slipped past unnoticed for ~5 weeks. See #350 for the cadence fix. | | 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 `` 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). **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):** (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. | | 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. **Scope (not yet designed):** add a check that the handoff's `branch` matches the current branch AND either `files_changed` is a superset of `git diff --name-only`/staged files, or `requested_at`/mtime is within some reasonable staleness window. **Open design question:** 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, not theoretical. Not fixed in #436 (separate, non-trivial concern; scope discipline). | -| 438 | Cross-repo Fable audit sweep — track and follow up on the 5 GH issues filed across the ecosystem | **Maintainer call-out 2026-07-04:** "use fable to review/upgrade these repos while it's free... reduce bloat and fix and review all that stuff," extended across every repo that matters, not just this one. Fable-led review/upgrade/bloat-reduction issues were filed on 5 repos as a time-boxed sweep before the July 1-7 free-inclusion window closes: [claude-gdlc-wizard#14](https://github.com/BaseInfinity/claude-gdlc-wizard/issues/14), [claude-rdlc-wizard#9](https://github.com/BaseInfinity/claude-rdlc-wizard/issues/9), [audit-agent#1](https://github.com/BaseInfinity/audit-agent/issues/1) (ADLC), [anticheat#1](https://github.com/BaseInfinity/anticheat/issues/1), [pdlc#6](https://github.com/BaseInfinity/pdlc/issues/6). This repo's own equivalent is tracked separately as #236 (bloat-hunt, re-triggered 2026-07-04 with the same Fable-window urgency) — #438 is specifically the cross-repo tracking/follow-up, since those 5 issues live in repos this ROADMAP doesn't otherwise cover. **Scope:** (a) follow up on each filed issue once picked up — verify Fable was actually used (not silently misrouted to another model, per the `CLAUDE_CODE_SUBAGENT_MODEL` bug found the same night, see #436 commit history) via the subagent self-identifying its model in its report; (b) after the July 7 window, note in each issue whether it was completed in time or needs re-scoping for metered Fable; (c) if a genuine pattern/finding recurs across 3+ of these repos (e.g. the same stale-doc-vs-lessons-learned contradiction found in this repo's own SDLC.md), consider whether it's worth a wizard-level fix (a hook/test/template change here) rather than 5 separate one-off fixes; (d) **maintainer add 2026-07-04:** extend the audit to measure token efficiency and ROI per repo — for each swept repo, capture roughly how many tokens the Fable pass spent (`/usage` or session cost) against what it actually fixed/found (bugs caught, bloat removed, doc drift corrected), so the sweep reports back "was this worth it" per repo, not just "did it run." Design not yet started — needs a lightweight before/after measure (e.g. char-count or token-bloat-audit delta plus a qualitative finding count) that doesn't require its own new tooling per repo. **Entry gate:** maintainer pain event — issues filed but nothing tracks whether the cross-repo sweep actually happened or paid off. | +| 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:** design settled, implementation pending (Pass 2 of the v1.84.0 retrospective fix plan, TDD, standalone PR). | +| 438 | Cross-repo Fable audit sweep — track and follow up on the 5 GH issues filed across the ecosystem | **Maintainer call-out 2026-07-04:** "use fable to review/upgrade these repos while it's free... reduce bloat and fix and review all that stuff," extended across every repo that matters, not just this one. Fable-led review/upgrade/bloat-reduction issues were filed on 5 repos as a time-boxed sweep before the July 1-7 free-inclusion window closes: [claude-gdlc-wizard#14](https://github.com/BaseInfinity/claude-gdlc-wizard/issues/14), [claude-rdlc-wizard#9](https://github.com/BaseInfinity/claude-rdlc-wizard/issues/9), [audit-agent#1](https://github.com/BaseInfinity/audit-agent/issues/1) (ADLC), [anticheat#1](https://github.com/BaseInfinity/anticheat/issues/1), [pdlc#6](https://github.com/BaseInfinity/pdlc/issues/6). This repo's own equivalent is tracked separately as #236 (bloat-hunt, re-triggered 2026-07-04 with the same Fable-window urgency) — #438 is specifically the cross-repo tracking/follow-up, since those 5 issues live in repos this ROADMAP doesn't otherwise cover. **Scope:** (a) follow up on each filed issue once picked up — verify Fable was actually used (not silently misrouted to another model, per the `CLAUDE_CODE_SUBAGENT_MODEL` bug found the same night, see #436 commit history) via the subagent self-identifying its model in its report; (b) after the July 7 window, note in each issue whether it was completed in time or needs re-scoping for metered Fable; (c) if a genuine pattern/finding recurs across 3+ of these repos (e.g. the same stale-doc-vs-lessons-learned contradiction found in this repo's own SDLC.md), consider whether it's worth a wizard-level fix (a hook/test/template change here) rather than 5 separate one-off fixes; (d) **maintainer add 2026-07-04:** extend the audit to measure token efficiency and ROI per repo — for each swept repo, capture roughly how many tokens the Fable pass spent (`/usage` or session cost) against what it actually fixed/found (bugs caught, bloat removed, doc drift corrected), so the sweep reports back "was this worth it" per repo, not just "did it run." Design not yet started — needs a lightweight before/after measure (e.g. char-count or token-bloat-audit delta plus a qualitative finding count) that doesn't require its own new tooling per repo. **Entry gate:** maintainer pain event — issues filed but nothing tracks whether the cross-repo sweep actually happened or paid off. **Recurring pattern confirmed 2026-07-05** (this is the #438(c) trigger): the v1.84.0 post-ship retrospective independently re-found the exact stale-doc-vs-lessons-learned pattern #438(c) called out by name (see #437's staleness gap, and the CI-Feedback-Loop/Convergence gaps fixed in `CLAUDE_CODE_SDLC_WIZARD.md` the same day) — a wizard-level fix (this repo's own doc + hook) is underway rather than 5 one-off fixes. **Maintainer intent 2026-07-05:** once this repo's fixes land, maintainer will run the Fable-led upgrade on each sibling repo (gdlc, rdlc, etc.) pointed at this repo's now-updated guidelines, so the siblings pick up similar patterns/discipline rather than each independently reinventing them — the 5 filed issues are the vehicle for that, not just a bloat-reduction pass. | diff --git a/SDLC.md b/SDLC.md index 412d09c7..f77dd93d 100644 --- a/SDLC.md +++ b/SDLC.md @@ -1,4 +1,4 @@ - + @@ -10,7 +10,7 @@ | Property | Value | |----------|-------| -| Wizard Version | 1.84.0 | +| Wizard Version | 1.85.0 | | Last Updated | 2026-07-04 | | Claude Code Minimum | v2.1.154+ (required for `opus[1m]` alias resolution); v2.1.105+ for `PreCompact` hook | | Claude Code Recommended | v2.1.195+ — comma-separated hook matcher fix (v2.1.191), hyphenated matcher exact-match fix (v2.1.195), `sandbox.credentials` setting (v2.1.187), `autoMode.classifyAllShell` setting (v2.1.193) | @@ -116,7 +116,7 @@ Portable technical gotchas promoted from private memory via the Memory Audit Pro ### Versioning + Releases -- **Version-bump checklist: grep ALL `SDLC Wizard Version` meta-comments, not just the obvious file.** The string lives in (a) `package.json`, (b) `SDLC.md` (top comment + table row), (c) `.claude-plugin/plugin.json`, (d) `.claude-plugin/marketplace.json`, (e) `CLAUDE_CODE_SDLC_WIZARD.md` line ~2984 (template inside the wizard doc), (f) `skills/update/SKILL.md` (changelog example block). Missing any one trips a different test: (e) trips `tests/test-hooks.sh::test_sdlc_version_matches_wizard`; (f) trips `tests/test-docs-usability.sh`. Single canonical command before tag: `grep -rn "SDLC Wizard Version: " .` and `grep -rn '"version": ""' .`. Caught at v1.76.0 (missed wizard doc template) and v1.77.0 (missed update skill example). (Source: v1.76.0 + v1.77.0 release arc, 2026-05-24) +- **Version-bump checklist: grep ALL `SDLC Wizard Version` meta-comments, not just the obvious file.** The string lives in (a) `package.json`, (b) `SDLC.md` (top comment + table row), (c) `.claude-plugin/plugin.json`, (d) `.claude-plugin/marketplace.json`, (e) `CLAUDE_CODE_SDLC_WIZARD.md` line ~2984 (template inside the wizard doc), (f) `skills/update/SKILL.md` (changelog example block), (g) `cowork/.claude-plugin/plugin.json`, (h) `cowork/README.md`'s "Version" section, (i) `ROADMAP.md`'s "Built With SDLC Wizard" living-tracker table (this repo's own row). Missing any one trips a different test: (e) trips `tests/test-hooks.sh::test_sdlc_version_matches_wizard`; (f) trips `tests/test-docs-usability.sh`; (g)/(h)/(i) have no dedicated test yet — caught only by a Codex cross-model review round at v1.85.0, because neither matches the canonical command's string patterns (no literal "SDLC Wizard Version:" prefix, no `"version": "..."` JSON key — they read as prose like "Dogfooded, v1.84.0" or "Tracks the main wizard version: **1.84.0**"). **Better canonical command** (catches (g)/(h)/(i) too, not just (a)-(f)): `grep -rn "" . --include="*.md" --include="*.json"`, then manually confirm every hit is either a tracked pointer (bump it) or genuinely historical narrative (leave it) — don't rely solely on the two fixed string-pattern greps below, they have blind spots. Caught at v1.76.0 (missed wizard doc template), v1.77.0 (missed update skill example), and v1.85.0 (missed the ROADMAP living-tracker row and cowork/README.md — both prose, not either tracked string pattern). Old (narrower) command, still useful as a first pass: `grep -rn "SDLC Wizard Version: " .` and `grep -rn '"version": ""' .`. (Source: v1.76.0 + v1.77.0 release arc, 2026-05-24; v1.85.0 Codex round 1, 2026-07-05) - **Merging to main does NOT trigger npm publish.** You must create and push a git tag (`git tag v && git push origin v`) to trigger `release.yml`. Verify with `npm view agentic-sdlc-wizard version`. (Source: v1.82.0 incident, 2026-06-11) - **Self-managed CC install vs npm install coexist invisibly until `which claude` differs from `npm root -g`.** The `curl install.sh` path puts CC at `~/.local/share/claude/versions/X.Y.Z` with a `~/.local/bin/claude` symlink; npm puts it at `/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/`. If `~/.local/bin` is earlier on PATH, `claude` resolves to the self-managed binary and `npm i -g @anthropic-ai/claude-code@latest` silently updates a parallel install that nothing invokes. Diagnosis: `which claude` vs `ls /opt/homebrew/bin/claude`. Self-managed bumps via `claude update` (not npm). To consolidate to one install: `rm ~/.local/bin/claude && rm -rf ~/.local/share/claude` (frees the version cache directory); npm install on PATH takes over. Also clean stale `installMethod: "native"` in `~/.claude.json` afterward. (Source: v2.1.118 → v2.1.150 upgrade debug, 2026-05-24) diff --git a/cowork/.claude-plugin/plugin.json b/cowork/.claude-plugin/plugin.json index ae8e86b9..adb2520b 100644 --- a/cowork/.claude-plugin/plugin.json +++ b/cowork/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "sdlc-wizard-cowork", - "version": "1.84.0", + "version": "1.85.0", "description": "SDLC enforcement for Claude Cowork — TDD, planning, self-review via prompt-based hooks and skills", "author": { "name": "Stefan Ayala", diff --git a/cowork/README.md b/cowork/README.md index 9cdda70e..6fde56a3 100644 --- a/cowork/README.md +++ b/cowork/README.md @@ -96,4 +96,4 @@ This plugin is for Cowork-only users who want methodology guidance without the f ## Version -Tracks the main wizard version: **1.84.0** +Tracks the main wizard version: **1.85.0** diff --git a/package.json b/package.json index 2bf8b756..afdb01e5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agentic-sdlc-wizard", - "version": "1.84.0", + "version": "1.85.0", "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command", "bin": { "sdlc-wizard": "cli/bin/sdlc-wizard.js" diff --git a/skills/update/SKILL.md b/skills/update/SKILL.md index 45e78484..096a977e 100644 --- a/skills/update/SKILL.md +++ b/skills/update/SKILL.md @@ -95,16 +95,16 @@ Parse CHANGELOG entries between the user's installed version and the resolved la ``` Installed: 1.42.0 -Latest: 1.84.0 +Latest: 1.85.0 What changed: +- [1.85.0] Post-ship retrospective fixes: CI Feedback Loop synced to SKILL.md's stronger version (NEVER AUTO-MERGE, read-logs-even-when-green, cross-model CI audit), CERTIFIED≠CI lesson, Policy Migration Inventory checklist, stale round-count correction (#437 hook-staleness fix follows separately). - [1.84.0] Hook enforcement fix: cross-model review gate + TDD RED gate now actually block (#436); model-aware effort docs replace blanket max recommendation. - [1.83.0] Model config batch: multi-model hook recommendation (#403), global [1m] pin detection (#391), version race fix (#405), effort config check (#384). - [1.82.0] Usage diagnostics: fix /usage row, Reading Usage Signals guide, advisor fallback procedure, Fable effort guidance, autocompact cross-reference. - [1.81.0] Native `advisorModel` support: Setup A gets Fable advisor, Setup B gets Opus advisor. Replaces manual subagent spawning. Requires CC v2.1.170+. - [1.80.0] Flip default: Opus 4.6 max becomes recommended flagship; Opus 4.8 demoted to opt-in `[l] Latest` tier. - [1.77.0] release-dry-run.yml + cc-version-drift.yml (#350) + /goal SDLC gates (95% + DLC binding). -- [1.76.0] /goal /sdlc wrapper (#347) + CC v2.1.150 feature adoption + ROADMAP demand-signal gate (4 excise, 4 kill). - [1.75.1] release-workflow fix — Node 22 → 24 (ships npm 11.x), dropped flaky `npm install -g` self-upgrade (hit MODULE_NOT_FOUND on v1.75.0 publish). Explicit npm-version guard. - [1.75.0] npm Trusted Publishing — `release.yml` swapped from `NPM_TOKEN` to OIDC. No more token rotation. Requires one-time publisher config on the npm package page. - [1.74.0] v1.43 salvage: #338 precedence preamble; #235ab `/insights`; codex `< /dev/null` stdin-hang fix; test env-isolation.