agentic-sdlc-wizard 1.44.1 → 1.45.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.44.1",
+      "version": "1.45.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.45.0] - 2026-04-27
+
+### Added
+
+- **PreCompact path (c) — SHA-ancestry self-heal** (closes #257). Consumer reported PreCompact blocking `/compact` even when the cited Codex review WAS actually CERTIFIED — the user just forgot to bump `handoff.json status` from `PENDING_RECHECK` → `CERTIFIED`. Existing self-heals don't cover this solo-developer pattern: path (a) needs `pr_number`, path (b) needs `mtime > 14d`. New path (c) heals when: handoff is `PENDING_*` with no `pr_number`, every SHA cited in `fixes_applied[]` is reachable from HEAD (`git merge-base --is-ancestor`), AND `.reviews/latest-review.md` contains `CERTIFIED` without `NOT CERTIFIED`. Path (b) still runs if (c) abstains (no SHAs / no review file).
+  - **Robust extraction**: awk extracts the `fixes_applied[]` block via bracket-depth + escape-aware string-literal tracking. `]` inside string literals (e.g. `"[x] FIXED..."` markdown checkboxes, `"...\"]"` escaped-quote-bracket) does NOT terminate the array prematurely.
+  - **UUID resilience**: strips 8-4-4-4-12 hex UUIDs before SHA extraction so ticket IDs in fixes_applied entries (Linear, Jira, mission UUIDs) don't false-block the heal.
+  - **Phantom SHA gate**: every cited SHA must pass `git merge-base --is-ancestor` against HEAD. Phantom SHAs (typos, references to other repos) correctly fail and block the heal.
+  - 9 new test-hooks tests (positive heal, phantom blocks, NOT CERTIFIED blocks, missing review.md blocks, partial coverage blocks, fall-through to stale, markdown-checkbox bracket, UUID alongside real SHA, escaped-quote bracket). Codex round 3 CERTIFIED 10/10 (rounds 1-2 surfaced bracket-extraction edge cases — markdown `[x]`, escaped quotes — and UUID false-block; all fixed).
+
+### Files
+
+- `hooks/precompact-seam-check.sh` — new path (c) block with depth-counted + escape-aware awk extraction, sed UUID strip, ancestry check
+- `tests/test-hooks.sh` — `_precompact_init_repo_with_commit` helper + 9 new path (c) tests
+
 ## [1.44.1] - 2026-04-27
 
 ### Fixed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -2717,6 +2717,53 @@ Options:
 
 ---
 
+### Browser Tooling Policy
+
+Three different jobs, three different tools. Conflating them is the source of recurring agent failures — `Playwright MCP` for an auth-heavy registrar dashboard wastes a session, browser-use for a deterministic regression test gives flaky CI.
+
+| Tool | Job | Profile model | When to pick |
+|------|-----|---------------|--------------|
+| **Playwright tests** | Deterministic regression suite, CI/release gate | Isolated by design — each test gets a clean browser context per [Playwright docs](https://playwright.dev/docs/browser-contexts) | Asserting expected user flows; running on every PR; gating deploy |
+| **Playwright MCP** | Live browser debugging, visual QA, DOM inspection | Default mode uses a **persistent Playwright-managed profile** at `ms-playwright/mcp-{channel}-{workspace-hash}` ([docs](https://playwright.dev/docs/getting-started-mcp#user-profile)) — NOT the user's regular Chrome profile. Other modes: `--isolated` (ephemeral context per session), `--user-data-dir=PATH` (caller-supplied dir), CDP attach (`--cdp-endpoint`), extension mode (attach to user's running browser tab) | One-off "look at this page" / "click this button and tell me what happens"; visual verification mid-session |
+| **Real-browser tooling** (browser-use, CDP-attach, Chrome profile) | Authenticated, profile-dependent, stateful operator flows | **When configured for real-browser mode** (e.g., browser-use `Browser.from_system_chrome()` or CLI `--profile`/`connect`), uses the user's actual Chrome profile (cookies, extensions, logged-in sessions). Default browser-use CLI runs headless Chromium — opt into the real-profile mode explicitly | Registrar dashboards (Porkbun, GoDaddy), DNS setup, cloud-provider consoles, wallet-adjacent Web3 flows, logged-in admin panels — anywhere preserving cookies/profile/extensions matters more than clean isolation |
+
+**The core insight:** Playwright tests' isolation is a *feature*, not a bug. Playwright MCP's persistent-managed-profile default is also a feature — it preserves session continuity across debug interactions in a SINGLE agent. The collision case is concurrent agents (#251) sharing the same managed profile. Real-browser tooling is the right call only when the task IS the user's authenticated session, and only when explicitly configured to attach to that profile.
+
+#### When to recommend real-browser tooling (#225)
+
+Trigger examples — if the task description includes any of these, suggest real-browser tooling (browser-use or CDP-attach) over Playwright MCP:
+
+- Registrar dashboards (domain purchase, DNS records, nameserver changes)
+- DNS setup / DNSLink / custom-domain configuration
+- Cloud/provider dashboards (AWS console, Cloudflare, Vercel, registrars)
+- Wallet-adjacent Web3 flows (token approvals, contract interactions in a logged-in MetaMask)
+- Logged-in admin panels (Stripe, Vercel, GitHub admin pages requiring 2FA-cached session)
+- Anywhere preserving cookies/profile/extensions matters more than clean isolation
+
+These all share a property: the agent's job IS the authenticated session. A clean automation browser is the wrong model.
+
+#### Playwright MCP profile-lock policy (#251)
+
+`Playwright MCP`'s default mode reuses a single persistent managed profile (`ms-playwright/mcp-{channel}-{workspace-hash}`) across stdio sessions — which is the right call for single-agent debugging because it preserves session continuity across calls, but breaks down when **multiple agents or MCP clients run concurrently** (two CC sessions, one CC + one Codex, etc.). Concurrent stdio sessions collide on the same Chrome user-data directory and corrupt each other's session state.
+
+**Upstream Playwright rejected default-isolated as the global default.** See [microsoft/playwright#40419](https://github.com/microsoft/playwright/issues/40419) and the discussion on [microsoft/playwright#40420](https://github.com/microsoft/playwright/pull/40420) — maintainer feedback: *"That's unfortunately very breaking."* Changing the default would silently break every existing single-agent setup that relies on the persistent managed profile.
+
+**Wizard policy (per-user, opt-in at the wizard layer, not upstream):**
+
+- **Single-agent / single MCP client (default):** Use Playwright MCP's default persistent-managed-profile mode. No special config required.
+- **Concurrent agents / multiple MCP clients:** Pick one of these per client to avoid profile-lock collisions: (a) `--isolated` (ephemeral context per session, no persistence), (b) `--user-data-dir=$TMPDIR/playwright-mcp-$AGENT_ID` (caller-supplied dir, isolated per agent), or (c) `--cdp-endpoint` to attach each agent to a separately-launched browser. None of these require an upstream breaking change.
+- **Real-browser / profile-dependent flows:** Don't use Playwright MCP at all — use real-browser tooling explicitly configured to attach to the user's profile (e.g., `browser-use` with `Browser.from_system_chrome()` or CLI `--profile`). The task is the session, not isolated automation.
+
+This rule is per-workflow, not global. Setup wizard does NOT auto-configure isolated profiles — adoption is explicit, gated on the user signaling concurrent-agent intent.
+
+#### Anti-patterns
+
+- **Using Playwright MCP for registrar dashboards** — its persistent managed profile is NOT your real Chrome profile, so your registrar's logged-in session/2FA cookies aren't there. You'll be re-logging in on every interaction. Use real-browser tooling configured for your real Chrome profile instead.
+- **Using profile-coupled / stateful browser tooling for deterministic CI tests** — when browser-use (or any tool) is configured to use a real Chrome profile, cached state, extension chrome, and stale cookies pollute the test. Use Playwright tests with isolated browser contexts for CI.
+- **Setting Playwright MCP `--isolated` globally as a default** — breaks single-agent flows that rely on the persistent managed profile for session continuity across debug interactions. Upstream Playwright rejected this for the same reason. Make it explicit per-workflow when concurrent agents are running.
+
+---
+
 ## Step 8: Create CLAUDE.md
 
 Create `CLAUDE.md` in your project root. This is your project-specific configuration:
@@ -2920,7 +2967,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.44.1 -->
+<!-- SDLC Wizard Version: 1.45.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] -->
@@ -3985,7 +4032,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.44.1 -->
+<!-- SDLC Wizard Version: 1.45.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/hooks/precompact-seam-check.sh

@@ -33,10 +33,16 @@ HOLD_REASONS=""
 # Check 1: Codex review mid-cycle
 # Self-heal paths (ordered by preference):
 #   (a) #209: handoff has pr_number + gh reports PR MERGED → implicit CERTIFIED (silent)
-#   (b) #229: handoff has no pr_number but mtime > SDLC_HANDOFF_STALE_DAYS days
-#       → implicit CERTIFIED with WARN (the handoff predates #209 or was never
-#       PR-linked; blocking forever over a forgotten artifact is worse UX than
-#       the bug we're preventing). Default threshold: 14 days.
+#   (c) #257: handoff has no pr_number BUT every SHA cited in fixes_applied[]
+#       is in HEAD's ancestry AND .reviews/latest-review.md contains CERTIFIED
+#       (without "NOT CERTIFIED") → implicit CERTIFIED (silent). Catches the
+#       solo-developer pattern: write fixes, commit them, run targeted
+#       recheck, see CERTIFIED in latest-review.md, ship — and forget to
+#       update handoff.json status. The visible signals (commits landed +
+#       review file) already say "done" so blocking is high false-positive.
+#   (b) #229: handoff has no pr_number, no SHA-ancestry heal, but mtime >
+#       SDLC_HANDOFF_STALE_DAYS days → implicit CERTIFIED with WARN
+#       (forgotten artifact; blocking forever is worse UX). Default: 14 days.
 HANDOFF="$ROOT/.reviews/handoff.json"
 # Validate SDLC_HANDOFF_STALE_DAYS as non-negative integer. Anything else
 # (empty, "foo", "-3", "10.5") silently falls back to 14 — we don't want a
@@ -62,8 +68,77 @@ if [ -f "$HANDOFF" ]; then
                     [ "$PR_STATE" = "MERGED" ] && HEALED=1
                 fi
             else
+                # Path (c) #257: SHA-ancestry self-heal. Look for git SHAs cited
+                # in fixes_applied[]; if every cited SHA is reachable from HEAD
+                # AND .reviews/latest-review.md says CERTIFIED, the review IS
+                # closed, the user just forgot to bump status. Silent heal.
+                REVIEW_MD="$ROOT/.reviews/latest-review.md"
+                if [ -f "$REVIEW_MD" ] \
+                    && grep -qE '\bCERTIFIED\b' "$REVIEW_MD" 2>/dev/null \
+                    && ! grep -qE '\bNOT CERTIFIED\b' "$REVIEW_MD" 2>/dev/null; then
+                    # Extract the fixes_applied[] block via bracket-depth
+                    # tracking — naive `/\]/` matching breaks on `]` inside
+                    # string literals (e.g. "[x] FIXED in <sha>" markdown
+                    # checkboxes), which would let phantom SHAs after the
+                    # broken-early bracket leak past path (c) and false-heal.
+                    # Codex P1 round 1.
+                    FIXES_BLOCK=$(awk '
+                        BEGIN { in_block = 0; depth = 0; started = 0 }
+                        /"fixes_applied"/ { in_block = 1 }
+                        in_block {
+                            print
+                            in_string = 0
+                            escaped = 0
+                            for (i = 1; i <= length($0); i++) {
+                                c = substr($0, i, 1)
+                                # Honor JSON backslash escapes: \" inside a
+                                # string is a literal quote, NOT a string
+                                # terminator. Without this, a fixes_applied
+                                # entry containing `\"]` falsely flips the
+                                # in_string flag and exits the array early —
+                                # letting later phantom SHAs leak past path
+                                # (c) and false-heal (Codex round 2 P1).
+                                if (escaped) { escaped = 0; continue }
+                                if (c == "\\") { escaped = 1; continue }
+                                if (c == "\"") { in_string = !in_string; continue }
+                                if (in_string) continue
+                                if (c == "[") { depth++; started = 1 }
+                                else if (c == "]") { depth-- }
+                            }
+                            if (started && depth <= 0) in_block = 0
+                        }
+                    ' "$HANDOFF" 2>/dev/null)
+                    if [ -n "$FIXES_BLOCK" ] && [ -d "$ROOT/.git" ]; then
+                        # Strip UUIDs (8-4-4-4-12 hex pattern) BEFORE extracting
+                        # SHA candidates. UUIDs have a fixed shape; their hex
+                        # segments would otherwise match \b[0-9a-f]{7,40}\b and
+                        # fail the ancestry check, false-blocking certified
+                        # reviews that cite UUIDs in fixes_applied (mission
+                        # UUIDs, Linear/Jira ticket IDs, etc.). Codex P2 round 1.
+                        # POSIX-compatible: no `\b` (BSD sed doesn't support it).
+                        # The hyphenated 8-4-4-4-12 shape is specific enough
+                        # that false-stripping a real SHA is implausible.
+                        CLEANED=$(echo "$FIXES_BLOCK" | sed -E 's/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}//g')
+                        SHAS=$(echo "$CLEANED" | grep -oE '\b[0-9a-f]{7,40}\b' | sort -u)
+                        if [ -n "$SHAS" ]; then
+                            # Every cited SHA must be reachable from HEAD —
+                            # phantom SHAs (e.g. typos, references to other
+                            # repos) correctly fail ancestry and block the heal.
+                            ALL_IN_HEAD=1
+                            for sha in $SHAS; do
+                                if ! git -C "$ROOT" merge-base --is-ancestor "$sha" HEAD 2>/dev/null; then
+                                    ALL_IN_HEAD=0
+                                    break
+                                fi
+                            done
+                            [ "$ALL_IN_HEAD" -eq 1 ] && HEALED=1
+                        fi
+                    fi
+                fi
                 # Path (b): stale-handoff auto-expire (#229). Only when no pr_number
-                # — we must not short-circuit PR-linked reviews.
+                # AND path (c) didn't already heal. We must not short-circuit
+                # PR-linked reviews.
+            if [ "$HEALED" -ne 1 ]; then
                 # Try GNU stat first (Linux: `-c %Y` gives mtime, BSD stat errors out
                 # so `||` fires). Then BSD stat (macOS: `-f %m` gives mtime). The
                 # reverse order fails on Linux because `stat -f` on GNU means
@@ -83,6 +158,7 @@ if [ -f "$HANDOFF" ]; then
                         ;;
                 esac
             fi
+            fi
             if [ "$HEALED" -ne 1 ]; then
                 HOLD_REASONS="${HOLD_REASONS}  - Codex review is ${STATUS}. Round-1 evidence lives in this context — compacting now loses what round-2 needs to re-verify.
     Resolve: wait for CERTIFIED (or escalate) before /compact."$'\n'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.44.1",
+  "version": "1.45.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

@@ -131,9 +131,10 @@ Parse all CHANGELOG entries between the user's installed version and the latest.
 
 ```
 Installed: 1.24.0
-Latest:    1.44.1
+Latest:    1.45.0
 
 What changed:
+- [1.45.0] PreCompact path (c) — SHA-ancestry self-heal — closes #257. Solo-developer pattern: write fixes, commit them, run targeted Codex recheck, see CERTIFIED in `.reviews/latest-review.md`, ship the feature. Forgetting to bump `handoff.json status` from `PENDING_RECHECK` → `CERTIFIED` is realistic — the file is buried and the visible signals (commits + review file) already say "done". PreCompact hook now self-heals silently when: (a) handoff is `PENDING_*` with no `pr_number`, (b) every SHA cited in `fixes_applied[]` is reachable from HEAD via `git merge-base --is-ancestor`, AND (c) `.reviews/latest-review.md` contains CERTIFIED without `NOT CERTIFIED`. Bracket extraction is escape-aware (depth counter + JSON `\\\"` handling) so `]` inside string literals doesn't terminate the array early. UUIDs (8-4-4-4-12 hex) stripped before SHA extraction so ticket IDs in fixes_applied don't false-block the heal. 9 new tests, Codex round 3 CERTIFIED 10/10.
 - [1.44.1] Autocompact compound-misconfig detection — closes #207. Consumer reported autocompact firing at 12% context on a fresh opus[1m] session because they set BOTH `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` AND `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` (a natural misreading of the "or"-joined override cell). The two compound: 30% × 400K = 120K trigger ≈ 12% of 1M. Three-pronged fix: (a) wizard doc clarifies alternatives with a `> ⚠ Do NOT set both` callout that shows the compound math; (b) `instructions-loaded-check.sh` (InstructionsLoaded hook) detects when both env vars are set in `.claude/settings.json`, computes the effective trigger, and warns with the math; (c) shipped `skills/sdlc/SKILL.md` was still calling opus[1m] the "default" (stale post-#198) AND repeating the same ambiguous wording — both fixed. 4 new hook tests + 3 new doc-consistency tests + size-cap fixture extended. Codex round 2 CERTIFIED 9/10.
 - [1.44.0] Install-path & cache hygiene — closes #254, #239, #238 filed by consumer codeguesser after upgrading 1.32.0 → 1.42.1. (1) `cli/init.js` FILES list now ships `hooks/_find-sdlc-root.sh` — the helper sourced by all 5 hooks was missing from npm install path, so every session emitted `_find-sdlc-root.sh: No such file or directory` + `dedupe_plugin_or_project: command not found` and the SDLC walk-up logic was silently dead. (2) `init --force` now invalidates `~/.cache/sdlc-wizard/latest-version` so post-upgrade hooks re-fetch fresh values from npm instead of serving the pre-upgrade cache for 24h (which produced reverse "1.42.1 → 1.41.1" nudges). (3) instructions-loaded-check.sh now uses semver-direction comparison via new `semver_lt` function: nudge only fires when installed < latest, equality is silent, reverse direction is silent. Cache sanity-check rejects poisoned values (cached "latest" < installed → force refetch). (4) When `npm view` fails AND cache empty, hook now surfaces a one-line warning instead of going silent. (5) Dual-channel install nudge gains an opt-in silence sentinel — set via `mkdir -p $SDLC_WIZARD_CACHE_DIR && touch $SDLC_WIZARD_CACHE_DIR/dual-channel-acknowledged` (printed inside the nudge itself for discoverability). 8 new tests across test-cli.sh + test-hooks.sh, Codex CERTIFIED 10/10 round 2.
 - [1.43.0] Token-spike anomaly detection — ROADMAP #220 closure. New `hooks/token-spike-check.sh` (SessionStart, opt-in via `.metrics/`) ingests CC transcript usage (`input_tokens` / `output_tokens` / `cache_creation_input_tokens` / `cache_read_input_tokens`) into `.metrics/token-history.jsonl`, then warns when the last session's `costly_tokens` (input + cache_creation + output, excluding the cheap cache_read tier) exceeds median + 2σ over a rolling baseline. Catches silent CC-side caching regressions (per Anthropic's 2026-04-23 post-mortem) before they surface on the invoice. Uses MAD-based spread for the median metric so a single baseline outlier doesn't mask the next spike. 14 quality tests in `tests/test-token-spike.sh` (incl. malicious-transcript privacy probe, flat-baseline floor, median-vs-mean contrast, concurrent-ingest mkdir lock).