agentic-sdlc-wizard 1.62.0 → 1.64.0

package/.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.62.0",
+      "version": "1.64.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-wizard",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
   "author": {
     "name": "Stefan Ayala",

package/CHANGELOG.md

@@ -4,6 +4,56 @@ 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.64.0] - 2026-04-30
+
+### Added (XDLC ecosystem cross-references)
+
+- **README gets an "XDLC Ecosystem (Sibling Projects)" section.** The wizard ships as one of three published siblings — `agentic-sdlc-wizard` (this repo, Claude Code / SDLC), `codex-sdlc-wizard` (Codex CLI / SDLC), and `claude-gdlc-wizard` (Claude Code / Game Development Life Cycle). Until now, none of the three READMEs cross-referenced the others, so a user landing on one package on npm or GitHub couldn't discover the family. The new section is a 3-row table with package name + GitHub repo + one-line description, plus a pointer to the broader [XDLC ecosystem](https://github.com/BaseInfinity/xdlc) umbrella.
+
+- **Wizard doc references the GDLC sibling.** `CLAUDE_CODE_SDLC_WIZARD.md` already mentioned the Codex sibling in the MCP-tool-hooks audit (portability criterion); now expanded to mention `claude-gdlc-wizard` alongside it. Cross-host portability is reframed as "cross-host / cross-domain portability" since GDLC is a different domain (games), not just a different agent.
+
+- **ROADMAP "Built With SDLC Wizard" table adds the GDLC row.** Previously listed only this repo and `codex-sdlc-wizard`. Now lists all three siblings; status column shows current sibling versions (Codex v0.7.x, GDLC v0.2.x).
+
+### Tests
+
+- **3 new tests in `tests/test-doc-consistency.sh`** prevent drift:
+  - `test_readme_references_all_siblings` — README must mention both sibling package names by literal string match (`codex-sdlc-wizard`, `claude-gdlc-wizard`)
+  - `test_readme_has_ecosystem_section` — README must have a discoverable `## XDLC Ecosystem` / `## Family` / `## Siblings` heading (not just an inline mention)
+  - `test_wizard_doc_mentions_gdlc_sibling` — Wizard doc must reference `claude-gdlc-wizard` wherever Codex sibling is mentioned (regression guard for sibling parity)
+
+  TDD-verified: all three failed before the doc edits, all three pass after. 33/33 doc-consistency tests green.
+
+### Files
+
+- `README.md` (new "XDLC Ecosystem (Sibling Projects)" section)
+- `CLAUDE_CODE_SDLC_WIZARD.md` (line 501 expanded — Codex + GDLC siblings, cross-host/cross-domain portability framing)
+- `ROADMAP.md` ("Built With SDLC Wizard" table — added GDLC row, bumped this repo's status to v1.64.0)
+- `tests/test-doc-consistency.sh` (+3 tests, 33 total)
+- `CHANGELOG.md`, `SDLC.md`, `skills/update/SKILL.md`, `package.json`, `.claude-plugin/plugin.json` + `marketplace.json` (1.63.0 → 1.64.0)
+
+### Follow-up
+
+- Mirror issues filed in `BaseInfinity/codex-sdlc-wizard` and `BaseInfinity/claude-gdlc-wizard` so each sibling adds the same Ecosystem section pointing back here. Bidirectional cross-references means any of the 3 npm package pages surfaces the family.
+
+## [1.63.0] - 2026-04-30
+
+### Added (cache-cost observability closeout — closes ROADMAP #204)
+
+- **Explicit cache-miss regression test in `tests/test-token-spike.sh`.** ROADMAP #204 had a Prove-It Gate: "require at least one quality test proves the hook/skill catches an actual cache-cost regression pattern." This release closes that gate. New `test_cache_miss_pattern_triggers_spike_warning` builds a 20-row baseline of cache-hit-heavy sessions (high cache_read, low cache_creation), appends one cache-miss session (cache_read collapses to 0, cache_creation spikes to 50000), and asserts the >2σ spike warning fires. Negative control `test_high_cache_read_no_warning` confirms the detector keys on cost-bearing fields (`costly_tokens = input + cache_creation + output`), not raw token count — a session with 10× cache reads but unchanged costly_tokens does NOT fire (hot cache is healthy, not expensive).
+
+- **Wizard doc gains "Cache-Cost Surprises" subsection in Token Efficiency.** Quantifies the 10-20× silent blowup pattern, points at `hooks/token-spike-check.sh` as the detection mechanism, references the Anthropic 2026-04-23 post-mortem, and lists practices to avoid silent invalidation. NOT added to `skills/sdlc/SKILL.md` — that file is already at the 5000-token session-load threshold (audit-session-load.sh trim ceiling). The hook itself fires the warning automatically; the wizard doc has the action-focused guidance for when a user explicitly asks.
+
+### Closed (absorbed)
+
+- **#204 — Cache-cost guardrail hook.** Codex strategic-pass-2 review confirmed: the cache-miss pattern surfaces directly in `costly_tokens` (the metric `#220`'s `hooks/token-spike-check.sh` tracks). #204 is absorbed by #220 + the v1.63.0 regression test + docs. No new hook needed — the existing one already covers it.
+
+### Files
+
+- `tests/test-token-spike.sh` (+2 tests, 16 total)
+- `CLAUDE_CODE_SDLC_WIZARD.md` (Cache-Cost Surprises subsection in Token Efficiency)
+- `ROADMAP.md` (#204 marked absorbed v1.63.0)
+- `CHANGELOG.md`, `SDLC.md`, `skills/update/SKILL.md`, `package.json`, `.claude-plugin/plugin.json` + `marketplace.json` (1.62.0 → 1.63.0)
+
 ## [1.62.0] - 2026-04-30
 
 ### Fixed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -498,7 +498,7 @@ CC 2.1.118 introduced `type: "mcp_tool"` for hooks — a hook can now directly i
 
 **Decision criteria applied** (any one rules out MCP):
 
-1. **Portability** — bash hooks port to the **shipped** Codex sibling (`~/codex-sdlc-wizard`) and to a **planned** OpenCode sibling (ROADMAP #91, not yet shipped) without rewrite. MCP hooks are CC-specific. Cross-host portability is an XDLC requirement.
+1. **Portability** — bash hooks port to the **shipped** sibling wizards (`codex-sdlc-wizard` for Codex CLI, `claude-gdlc-wizard` for the Game Development Life Cycle variant) and to a **planned** OpenCode sibling (ROADMAP #91, not yet shipped) without rewrite. MCP hooks are CC-specific. Cross-host / cross-domain portability is an XDLC requirement.
 2. **Fail-closed gating** — hooks that block an action (exit 2 from PreCompact) need a fail-closed contract: any error in the hook MUST keep the block in place. CC docs ([code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks)) confirm `mcp_tool` hooks CAN gate via `decision: "block"` JSON output, but **MCP server errors are non-blocking by design** — if the MCP server is down/slow/buggy, the action proceeds. That breaks the fail-closed contract. Bash exit 2 fails closed.
 3. **Local-only state** — hooks that read/write `~/.cache/sdlc-wizard/` or `.reviews/handoff.json` don't surface state across tool boundaries. MCP adds a wire format without consumers.
 
@@ -2974,7 +2974,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.62.0 -->
+<!-- SDLC Wizard Version: 1.64.0 -->
 <!-- Setup Date: [DATE] -->
 <!-- Completed Steps: step-0.1, step-0.2, step-0.4, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: [PRs or Solo] -->
@@ -3657,6 +3657,20 @@ claude_args: "--max-budget-usd 5.00 --max-turns 30"
 
 For organization-wide cost tracking, enable `CLAUDE_CODE_ENABLE_TELEMETRY=1`. This exports per-request `cost_usd`, `input_tokens`, `output_tokens` to any OTLP-compatible backend (Datadog, Honeycomb, Prometheus).
 
+### Cache-Cost Surprises
+
+Anthropic prompt-cache reads bill at ~10% of normal input rate ($1.50/M vs $15/M on Opus). When cache hits drop unexpectedly, the same workload silently costs **10–20×** more — a pattern HN has documented multiple times. Two common triggers:
+
+1. **Mid-session edits to `CLAUDE.md`, `SDLC.md`, project settings, or any file the cached prefix references.** The cache key includes the project context; editing context invalidates the prefix and forces re-upload (`cache_creation` spikes, `cache_read` collapses).
+2. **Upstream caching bugs.** Anthropic's [2026-04-23 post-mortem](https://www.anthropic.com/engineering/april-23-postmortem) documented one bug that "continuously dropped thinking blocks from subsequent requests" — invisible until the invoice arrived.
+
+**Detection:** the wizard's `hooks/token-spike-check.sh` (ROADMAP #220, on-by-default for projects with a `.metrics/` directory) tracks per-session `costly_tokens = input + cache_creation + output` (excluding `cache_read`) and warns at `>2σ` over a rolling baseline. The cache-miss pattern (cache_read collapses → cache_creation spikes) shows up in `costly_tokens` directly. Test coverage in `tests/test-token-spike.sh:test_cache_miss_pattern_triggers_spike_warning` proves the absorption.
+
+**Practices to avoid silent cache-cost blowups:**
+- Avoid editing `CLAUDE.md`/`SDLC.md`/project settings mid-session when cache stability matters. If you must, accept the next request will re-upload the prefix.
+- Run `/usage` (or `/cost`) after long sessions to spot anomalies before they accumulate.
+- Inspect `.metrics/token-history.jsonl` directly when you suspect a regression — fields are documented at the top of `tests/e2e/token-analytics.sh`.
+
 ---
 
 ## CI/CD Gotchas
@@ -4039,7 +4053,7 @@ Walk through updates? (y/n)
 Store wizard state in `SDLC.md` as metadata comments (invisible to readers, parseable by Claude):
 
 ```markdown
-<!-- SDLC Wizard Version: 1.62.0 -->
+<!-- SDLC Wizard Version: 1.64.0 -->
 <!-- Setup Date: 2026-01-24 -->
 <!-- Completed Steps: step-0.1, step-0.2, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: PRs -->

package/README.md

@@ -257,6 +257,18 @@ This isn't the only Claude Code SDLC tool. Here's an honest comparison:
 | [CHANGELOG.md](CHANGELOG.md) | Version history, what changed and when |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute, evaluation methodology |
 
+## XDLC Ecosystem (Sibling Projects)
+
+This wizard is one of three published siblings. Same enforcement philosophy, different agent / domain:
+
+| Package | Agent / Domain | What It Does |
+|---------|----------------|--------------|
+| [`agentic-sdlc-wizard`](https://www.npmjs.com/package/agentic-sdlc-wizard) ([repo](https://github.com/BaseInfinity/claude-sdlc-wizard)) | Claude Code / SDLC | This repo. Plan → TDD → self-review for code, with hooks + skills + CI scoring |
+| [`codex-sdlc-wizard`](https://www.npmjs.com/package/codex-sdlc-wizard) ([repo](https://github.com/BaseInfinity/codex-sdlc-wizard)) | OpenAI Codex / SDLC | Same SDLC enforcement, ported to Codex CLI (writes `.codex/` + `AGENTS.md`) |
+| [`claude-gdlc-wizard`](https://www.npmjs.com/package/claude-gdlc-wizard) ([repo](https://github.com/BaseInfinity/claude-gdlc-wizard)) | Claude Code / GDLC | Game Development Life Cycle — persona-driven playtest cycles, triangulated findings, ratchet-only-tightens |
+
+All three are part of the broader [XDLC ecosystem](https://github.com/BaseInfinity/xdlc) — generalized lifecycle enforcement across agents and domains.
+
 ## Community
 
 <div align="center">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "cli/bin/sdlc-wizard.js"

package/skills/update/SKILL.md

@@ -93,9 +93,11 @@ Parse CHANGELOG entries between the user's installed version and latest. Present
 
 ```
 Installed: 1.42.0
-Latest:    1.62.0
+Latest:    1.64.0
 
 What changed:
+- [1.64.0] XDLC ecosystem cross-references — README, wizard doc, and ROADMAP now cross-reference all three sibling packages (`agentic-sdlc-wizard`, `codex-sdlc-wizard`, `claude-gdlc-wizard`). New "Ecosystem (Sibling Projects)" section in README. 3 new doc-consistency tests prevent drift.
+- [1.63.0] cache-cost observability closeout (#204 absorbed by #220) — `tests/test-token-spike.sh` gains explicit cache-miss regression test + negative-control test. SDLC skill + wizard doc gain "Cache-Cost Surprises" sections covering 10-20× silent cost blowups (mid-session CLAUDE.md edits, idle pruning, upstream cache bugs) and detection via `hooks/token-spike-check.sh`'s `costly_tokens` metric.
 - [1.62.0] roadmap hygiene + #211 backfill — closes paperwork-stale rows (#207, #211 historical, #215, #217, #78, #79, #80, #219). Backfilled 5 corrupted `score-history.jsonl` rows from `max_score:10` → `max_score:11` (UI scenarios with design_system criterion). Codex strategic review confirmed scope.
 - [1.61.0] calibration scenarios for #96 Phase 3 PR 2 — `tests/e2e/scenarios/calibration-careful-read.md` (parsePrice with 5 edge-case formats) tests whether self-review catches missed requirements. Score delta between SDLC and naive agents on this scenario is a calibration signal for `lift-proof.sh`
 - [1.60.0] wizard-installation lift-proof harness (#96 Phase 3 PR 1) — `tests/e2e/lift-proof.sh` runs same scenario on bare vs wizard-installed fixture, emits score delta. Closes the "does the wizard work?" question. Honestly zero-API (sim + eval on Max)