summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJesse Vincent <jesse@primeradiant.com>2026-10-21 17:00:49 -0400
committerGitHub <noreply@github.com>2026-10-21 14:00:49 -0700
commit2ce8aa15d05bd57213e6f746f953aafb7ded7a8b (patch)
tree5e3a3c9af45c3474506fb62a3ce664bd03a2cdc4
parentb739a8af570e10a95898f2bdf6cec97467fa6c12 (diff)
Release v7.0.1: brainstorming retune, skills that better survive compaction, contribution templates (#2581)v7.0.1
* feat(sdd): align templates and codex reference with resume-based fix rounds * feat(sdd): lifecycle restructure with resume-based fix loop, five-round breaker, and rationalization table * docs(using-superpowers): drop dangling subagent-support anchor (#2010) The prune in e7ddc25e removed the `## Subagent support` section from antigravity-tools.md but left the inline cross-reference to it in the dispatch table, so `[Subagent support](#subagent-support)` resolves to nothing. An agent following the pointer to learn the difference between the `self` and `research` subagent types lands nowhere. Drop the dangling parenthetical. The guidance it pointed at survives in the same table cell -- `self` for full-capability work, `research` for read-only -- so no content is lost and the row still answers the question the removed section answered. gemini-tools.md carries the same cross-reference but retains its `## Subagent support` heading, so its link is valid and is left alone. * fix(systematic-debugging): match find -path ./ prefix in find-polluter.sh (#2011) find . emits ./-prefixed paths, so -path "src/**/*.test.ts" matched nothing; wc -l on empty stdin then lied as "Found 1". Fixes #2008. Co-authored-by: arimu1 <19286898+arimu1@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com> * fix(systematic-debugging): find-polluter accepts ./-prefixed patterns and matches top-level tests Follow-up to #2011 (which fixed the ./-prefix mismatch for the documented pattern form): strip a leading ./ from the caller's pattern instead of double-prefixing it into a never-matching ././ form, and also match the pattern with '**/' collapsed, since find -path cannot match '**/' against zero directory levels and silently skipped files directly under the base directory (src/top.test.ts vs src/**/*.test.ts). Adds a deterministic test suite for the script with a stubbed npm. * fix(finishing): check in with human partner when worktree removal hits untracked files git worktree remove refuses when the tree holds modified or untracked files, and the skill gave no guidance for that refusal — the natural agent response was --force, permanently destroying files that exist nowhere else (uncommitted plans, notes, scratch work). Reported twice from real sessions (#2016's plan loss, #1223's dirty-tree ambiguity). Step 6 now treats the refusal as a stop-and-ask moment: show the untracked files, offer commit / relocate / delete, and only remove the worktree after the human partner chooses. Adds a matching rationalization row so --force-as-cleanup is named as the failure it is. * feat(hermes): Hermes Agent harness support, rebased to a Hermes-only diff Rebase of PR #1922 onto current dev: the ~14 files of v6.1.0-era codex/release drift are dropped, the porting-guide edits (stale against the post-prune rewrite, no Hermes content) are dropped, and the Hermes surface is kept intact: .hermes-plugin/ (on_session_start bootstrap injection), tests/hermes/ (20 tests, passing), docs/README.hermes.md, references/hermes-tools.md, the Platform Adaptation row, README section, and Python ignores. Known open items from review, unchanged by this rebase: the injection mechanism uses ctx.inject_message from on_session_start, which the official plugin guide does not document (pre_llm_call returning {"context": ...} is the sanctioned path), skills are not registered via ctx.register_skill, and the acceptance transcript predates the fix. Co-authored-by: kumarabd <kumarabd@users.noreply.github.com> * fix(hermes): working bootstrap injection via pre_llm_call + native skill registration Empirical findings from the quorum eval bring-up (superpowers-evals docs/experiments/2026-07-23-hermes-target-bringup.md): - ctx.inject_message exists but returns False when called from on_session_start — nothing reaches the model. The documented path, a pre_llm_call hook returning {"context": ...} on is_first_turn, verifiably delivers (probe model echoed an injected codeword). - ctx.register_skill requires a pathlib.Path; passing a str raises AttributeError inside hermes, which silently disables the entire plugin (no log line anywhere). This also means any exception in register() is invisible — keep register() failure-proof. - Registered skills are namespaced by plugin name: models invoke skill_view("superpowers:brainstorming") and receive the stock SKILL.md — verified live on GLM 5.2, both install layouts. The plugin now: resolves skills/ for both the git-clone layout (.hermes-plugin/ and skills/ as siblings) and a flattened install, raising loudly when neither matches; registers every stock skill with Hermes' native loader (no per-harness skill copies); injects the using-superpowers bootstrap via pre_llm_call on the first turn; and sources the tool mapping from references/hermes-tools.md instead of duplicating it. Injected context is transient (API-call time only, never persisted in the session export) — verification of injection must be behavioral. * test(hermes): realign suite with the pre_llm_call mechanism; slim docs to the README section The 20-test suite still exercised the dead on_session_start/inject_message mechanism (17 failures against the rewritten plugin). Rewritten for the real contract: pre_llm_call registration + first-turn-only context return, register_skill receiving pathlib.Path (the conftest mock now raises on str, mirroring hermes' AttributeError that silently disables a plugin), both install layouts resolving skills, loud failure when skills are missing, tool mapping sourced verbatim from hermes-tools.md, and a bootstrap-size guard against hermes' 10k-char context spill threshold. 19 tests, passing. Install docs collapse into the README section per maintainer direction: docs/README.hermes.md and .hermes-plugin/INSTALL.md are gone; the README carries the two-line install plus the compaction caveat. plugin.yaml version aligned to 6.1.1. * Release v6.2.0: SDD plan-scoped workspace and resume-based fix loop, skills compression sweep, Windows SessionStart fix (#2026) Release notes for everything on dev since v6.1.1, plus the version bump to 6.2.0 across all seven declared manifest files (bump-version.sh, audit clean). Tagging and marketplace publication happen after the dev -> main merge. * docs: remove the "We're Hiring" section from the README The community engineer role has a candidate on trial, so the posting no longer needs to be at the top of the README. * feat(brainstorming): three-path router — ceremony scales, approval never does Spike / bounded / architectural classification said out loud, one-way upgrade ratchet, approval gate on every path. The measured pathology: the absolute hard-gate wording forced bounded tasks into the full two-document ritual 5/5 while a no-guidance control differentiated paths natively. * fix(sdd): implementers never dispatch subagents Depth-2 worker-spawned reviewers were 9/9 same-task duplicate reviews across four corpora in the codex-efficiency eval campaign. * fix(brainstorming): bounded-path approval is a hard stop Live ceremony battery: bounded reps produced zero doc ritual (the measured win) but 2/3 implemented before any approval turn; the bounded path now states the stop explicitly. * fix(codex): correct multi-agent guidance against Codex source Five claims contradicted by the Codex CLI source (V2 has no close_agent; followup_task always reaches a child; role files attach via agent_type; full-history forks accept model/effort; V2 spawn allowlist). Citations: superpowers-autoresearch docs/2026-07-29-codex-multiagent-v2-capabilities.md. * fix(sdd): reviewers never dispatch subagents either The first fix-cycle battery moved the depth-2 leak from implementers (9/9 baseline -> 0/6) to a final reviewer that spawned two sub-reviewers; the contract now reaches every dispatched role. * fix(brainstorming): bounded means existing code in this repo, not a familiar app genre Triggering battery: Claude Code classified a brand-new project bounded 3/3 by reading 'existing, understood flow' as genre familiarity — once while explicitly noting the repo was empty. Gemini routed the same prompt architectural 3/3. * fix(codex): event-driven waiting instead of short polls 60-78% of wait_agent calls timed out across every measured corpus; waits are event subscriptions, so one long wait replaces dozens of polls at identical wake latency. * fix(sdd): controllers wait long or not at all Docs-only wait guidance in the platform reference changed nothing (65.1% vs 67.1% baseline wait-timeout rate); the discipline now lives in the controller loop the session actually re-reads. * fix(sdd,codex): bounded wait stretches with reconciliation Round 2 proved the long-wait mechanism (65.1%->0.0% timeouts) but 20-38 min silent waits starved graders and let 1/51 children vanish; bounded 5-10 min stretches with a status line and list_agents reconcile keep the efficiency and restore observability. * fix(codex): explicit model+effort on every spawn, config backstop Depth-2 child-issued spawns omitted model 2/2 at CLI 0.146; model without reasoning_effort resets effort to the model default. * docs: codex-efficiency fix-cycle spec and plan (campaign record) * fix(sdd): rule and continue — non-catastrophic conflicts get ledgered rulings, not blocking questions A donated session sat dormant 8h48m waiting for a plan-conflict answer that cost ~zero tokens to decide. Wrong-ruling rework is bounded; stalls are not. This encodes the never-stall doctrine: plan conflicts, ambiguities, and cap exceptions get a controller ruling recorded in the ledger and work proceeds; only irreversible/destructive actions, security-sensitive actions, out-of-worktree side effects (merge/push/ publish), and totally-broken plans remain hard stops. Rulings surface in the Finish report instead of as mid-run questions. Evals: 3/3 no-stall vs control 3/3 stall-at-preflight on a seeded-conflict SDD plan; catastrophic guard 5/5 (every rep reaching a seeded DROP TABLE step refused it); re-validated 3/3 after rebase onto the current fix-PR text; composes cleanly with the evidence-bearing preflight treatment. Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * fix(sdd): batch small same-shape tasks into one dispatch Plans sometimes enumerate many tiny, same-shape edits (one-line fixes, constant changes, a field added across files) as separate tasks. The current loop dispatches a fresh implementer plus review per task, so a 12-micro-task plan costs ~24 subagent seats for what one subagent could do in a single pass. In controlled evals on a micro-task plan, batching cut cost 73% and dispatches 87% with better completion than control; on a 5-non-trivial-task plan the rule correctly never batched (dispatch counts and completion identical to control). Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * fix(sdd): preflight emits its pairwise checks as a ledger table and rules on what it surfaces The pre-Task-1 conflict scan currently permits 'the scan is clean' with no evidence the scan happened — mined sessions show controllers skipping straight to dispatch and plan conflicts surfacing mid-execution as blocking questions. Requiring the scan to emit one row per task pair sharing a file/interface and one row per task's self-consistency turns the claim into an artifact; in controlled evals the table appeared 3/3 with conflicts surfaced pre-dispatch, and the mechanism held 3/3 when composed with the never-stall ruling change (#2077). Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * fix(planning): the spec travels with the plan — Spec: header pointer + SDD reads it at setup In controlled evals, an identical seeded-incoherence plan yielded 0-1/5 correct conflict resolutions when executed specless (controllers ruled the conflicts 'internally explained') and 4-5/5 with the spec merely present and named — even with no other skill-text changes. Cross-task coherence turns out to be adjudicable only against ground truth above the plan; this change makes that ground truth travel with the plan. Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * fix(sdd): one Ruling: token everywhere, exhaustive finish roll-up The breaker's two ledger formats wrote lowercase 'ruling' (parked findings, load-bearing adjudications), so the Finish section's collect-every-`Ruling:`-line step missed exactly the rulings made under the most pressure. Field evidence from an independent eval rep: a breaker-cap run adjudicated correctly, wrote everything to the plan-scoped ledger, deleted the workspace at finish, and left no durable trace of the adjudication. Capitalize the two breaker formats to the canonical token, and make the finish roll-up explicitly exhaustive across preflight, parked, and breaker rulings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(sdd): batch reviews check the diff against the brief's file list Batching moves N edits under one review, which changes the review's failure profile: an implementer that silently skips one file of twelve produces a diff full of correct, uniform edits — nothing conspicuous is missing, and no seat in the pipeline was assigned to notice. The single combined review is the only net for a dropped edit, but the reviewer template never told it to count. The batch brief already lists every file with its change, so the reviewer reconciles the diff against that list file by file; a listed file with no hunk is a Missing finding regardless of how clean the rest of the batch looks. Conditional on a multi-file brief, so single-task reviews are unchanged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(sdd): task reviewers re-read illegible evidence instead of re-running to regenerate it Interrogation of reviewers who bypassed test-evidence leases showed a convergent driver: when the report or receipt looked truncated or couldn't be located, re-running the suite felt cheaper than re-reading — evidence got regenerated instead of read. This paragraph names that moment: re-read at the stated path, report a genuine gap to the controller, and never re-run to regenerate what wasn't read. Battery: 0/31 reviewer re-runs across 4 treatment reps vs 7/~59 reviewers in 5/8 control reps on the same scenario and classifier. Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * Moves Community up, and adds ToC. * chore(hermes): align plugin version with dev Update the Hermes plugin manifest from 6.1.1 to 6.2.0 so PR #2025 matches the current release version at the tip of origin/dev.\n\nThis intentionally does not change the version bump tooling. The existing release script supports JSON manifests only; YAML support will be handled separately on its own branch. * fix(writing-skills): run graphviz without a shell in render-graphs.js The `dot` availability check shelled out to `which dot`, which is not a command on Windows, so render-graphs.js reported graphviz as missing on Windows even when it was installed. Replace it with a direct `dot -V` probe via execFileSync. Also switch the SVG render call from execSync to execFileSync('dot', ['-Tsvg']). Behavior is identical on macOS/Linux — the diagram source was already passed via stdin, never interpolated into the command — but running the binary directly removes the shell entirely. * test(writing-skills): cover render-graphs execution * fix(finishing): name the actual files in the refusal prompt `git status --porcelain` collapses a wholly-untracked directory to a single `?? docs/` line. In the shape of the incident this step exists for (#2016 — an uncommitted plan document under an untracked `docs/` tree), the file list we show the human partner therefore names no file at all: $ git -C "$WORKTREE_PATH" status --porcelain ?? docs/ $ git -C "$WORKTREE_PATH" status --porcelain -uall ?? docs/superpowers/plans/2026-08-04-csv-export-rollout.md Both forms produce identical (empty) output on a clean worktree, so this adds no over-trigger surface. Found while running this PR's behavioral micro-tests. Every treatment agent dug past `?? docs/` unprompted and named the document, so the step did work — but on the agent's own initiative rather than because the text asked for it. That initiative is not reliable one tier down: Claude Haiku 4.5 on the control arm failed for exactly this shape, asking a question that never named the file and then deciding for the human when they deferred. Nothing in the prior wording stopped a treatment agent from relaying `?? docs/` verbatim and satisfying the letter of the instruction. Re-ran the treatment cells against this amended text — Opus pass (refusal fired, named the file), Haiku 4.5 pass (named the file) — no regression. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs: design Hermes version-bump wiring Document the agreed follow-up to PR #2025 on a branch based on its merged dev commit. The design registers the Hermes YAML manifest, keeps jq for existing JSON files, and uses Mike Farah yq v4 for a narrow top-level YAML field rather than adding a Bash parser.\n\nDefine focused failure behavior and behavioral tests while explicitly excluding nested YAML, Hermes runtime changes, and unrelated release-script refactors. This captures Drew's request to keep the implementation small and avoid process or abstraction overhead. * docs: reduce Hermes version-bump design Incorporate the adversarial design review without turning the Hermes wiring follow-up into a general release-script refactor. Keep the existing jq path, add Mike Farah yq v4 only for .yaml, and retain one read-only preflight to prevent deterministic partial bumps.\n\nReduce the test contract to three behavioral cases and explicitly defer .yml support, nested YAML, rollback machinery, audit/status redesign, exhaustive failure matrices, and the separately discovered JSON-expression issue. This follows Drew's direction to avoid ceremony and overengineering. * docs: plan Hermes version-bump wiring Record Drew's approved reduced design after the second staff review. Limit preflight to the mutating bump path, cover audit's independent read path, and require byte-for-byte proof that deterministic YAML failures cannot partially update earlier JSON manifests. Provide one TDD implementation task for the Hermes registry entry, jq/yq dispatch, focused preflight, and three behavioral checks. Explicitly defer rollback, audit-status changes, nested YAML, runtime changes, and broader release-tool refactoring. * fix(release): wire Hermes into version bumps Register the Hermes YAML manifest alongside the existing JSON manifests. Route manifest reads and writes by extension through jq or Mike Farah yq v4, with field names and values passed as data. Preflight every present manifest before the mutating bump loop so a deterministic YAML read failure cannot leave earlier JSON manifests partially updated. Cover check, audit, bump, registry wiring, and byte-for-byte no-partial-write behavior with one focused fixture test. * feat(opencode): add V2 (opencode2) plugin compatibility Add dual V1/V2 support to the OpenCode plugin. The same source file now works on both OpenCode V1 (opencode) and V2 (opencode2) without version detection at runtime. V2 changes: - Add default export { id, server, setup } for V2 PluginSupervisor - setup() registers skills via ctx.skill.transform() (V2 native API) - setup() injects bootstrap via ctx.session.hook('context') (V2 equivalent of V1's experimental.chat.messages.transform) - config hook guards against V2 array-format skills to avoid conflicts Both APIs confirmed active at runtime via diagnostics in the V2 beta. No external dependencies added — pure JavaScript throughout. Docs updated with V2 install instructions, OPENCODE_CONFIG_DIR side-by-side setup, and accurate How It Works section for both versions. * docs: add Grok Build CLI to README.md * feat: add Devin CLI support Devin CLI's `devin plugins install obra/superpowers` fails today because the repo has no `.devin-plugin/plugin.json` manifest. Add the manifest (skills are auto-discovered from the co-located skills/ directory), a Devin tool mapping linked from using-superpowers' Platform Adaptation section, a README install section, version tracking in .version-bump.json, a Codex-sync exclude for the new dotdir, and a CI-safe test mirroring the kimi/antigravity test style. Bootstrap rides Devin's native skill surfacing: every installed skill's name + description is injected into the system prompt at session start with a standing instruction to invoke matching skills via the native skill tool. Acceptance test ("Let's make a react todo list") passes in a clean session: using-superpowers and brainstorming auto-trigger before any code is written. * Drop devin-tools.md — not needed for correct operation Re-ran the clean-session acceptance test with the mapping file and the SKILL.md Platform Adaptation pointer removed: using-superpowers and brainstorming still auto-trigger first, and the full workflow chain (writing-plans, executing-plans, TDD, verification) resolves every action to Devin's native tools. Devin CLI's own system prompt already documents its tools (skill invocation, subagent profiles, todo tracking, question prompts), so the mapping was redundant. Test now validates the manifest only. * docs: streamline README getting started navigation Remove the redundant Quickstart entry and section now that the README has a table of contents. Rename the Installation label in the table of contents to Getting Started while retaining the existing installation anchor and section heading. * docs: keep Hermes in installation navigation Add Hermes Agent to the installation entries in the table of contents. The removed Quickstart section was the README's only direct link to that existing installation section, so preserving the link avoids a navigation regression. * feat(tdd): the project's suite defines green, not just your test file At the Verify GREEN moment, redefine "other tests still pass": run the project's test command even when the task named only one test file — a scope statement bounds the deliverable, not the verification — and any failure seen goes in the report by name. In a pre-registered 24-rep battery on an adjacent-breakage probe, controls ran the wider suite in 1/12 sessions; with this text, 8/12 (sonnet 4/4, kimi 3/4, glm 1/4), and every session that saw the failure reported it. Claude-Session: https://claude.ai/code/session_0185AJr98gHx5EmwqNeft4Sy * docs: release notes for v6.3.0 * chore: bump version to 6.3.0 * Update to Prime Radiant Community Code of Conduct. (#2122) * docs: add Qwen Code install instructions to README Rebased from PR #2108 onto the reworked README. Differences from the PR: the Hermes TOC entry and Quickstart-line changes are obsolete (the v6.3.0 README rework already added the former and removed the latter), and the Hermes post-compaction caveat stays: .hermes-plugin injects the bootstrap only on is_first_turn, so the caveat is still accurate. Install/update commands and the acceptance transcript are from PR #2108 (@arittr, tested interactively on Qwen Code). Co-authored-by: Drew Ritter <arittr@users.noreply.github.com> * fix(requesting-code-review): anchor the multi-commit BASE_SHA alternative to the merge base The '# or origin/main' alternative fed a moving ref into the reviewer's two-dot diff: once origin/main advances past the branch point, main's new files appear as phantom deletions the reviewer can't distinguish from real ones. Reproduced during triage (2026-08-12): a scratch repo with main advanced one commit shows 'main-new.txt | 1 -' in the branch's diff. git merge-base origin/main HEAD anchors the range to the branch point, matching how sdd's review-package already computes BASE. Reported in #2118 (wan-huiyan). Fixes #2118. * fix(sdd): invoke sdd-workspace via bash so helpers survive stripped exec bits Codex marketplace users hit 'Permission denied' running SDD helpers: some extractors (Python zipfile) discard Unix mode attributes when unpacking the package, so task-brief's and review-package's direct exec of their sibling sdd-workspace fails. Our packaging preserves 0755 (git archive | tar -xpf, asserted by the existing packaging test) — the bits are lost on the consumer side, which no packaging change can reach. Invoking the sibling via "${BASH:-bash}" makes the exec bit irrelevant. TDD: new regression case copies the helpers, chmod -x, runs task-brief via bash — RED with the reported rc=126 Permission denied, GREEN after. Reported in #2040 (michaelholcomb-creator). Fixes #2040. * fix(sdd): reject empty or non-descendant BASE..HEAD ranges in review-package When an SDD implementer commits to the wrong branch (#2050), the BASE..HEAD range handed to review-package is either empty or not rooted at BASE. Both cases previously produced a review package silently — an empty one lets the reviewer approve "clean" work that isn't there. Add two mechanical guards after BASE/HEAD validation, exiting 3 (vs 2 for usage errors) so callers can distinguish range problems: - git merge-base --is-ancestor BASE HEAD, else "HEAD is not a descendant of BASE" - git rev-list --count BASE..HEAD > 0, else "empty commit range" Guard shape credits the analysis in closed PR #2082 by @stantheman0128. Fixes #2050 * fix(opencode): adapt to V2 skill draft API removal (#2106) OpenCode V2 removed SkillDraft.source() in 1113adfd5e (#41622): the skill service now stores values only, and filesystem scanning moved to the config side. The plugin's draft.source({type:'directory'}) call threw 'draft.source is not a function', which killed the entire V2 plugin activation generation. Because V2 gates model.list on PluginSupervisor.flush (23b0688a7f, #41783), that failure left flush pending forever and the TUI showed no providers or models ('Model catalog initialization timed out', /api/model 503). Register each skills/<name>/SKILL.md as a native Skill.Info object via draft.add({id, name, description, location, content}) instead, matching the {list, add, update, remove} draft API and the pattern used by V2's built-in skill plugin. Wrap skill registration, hook registration, and the context hook callback in try/catch so a future V2 API change degrades to a logged error instead of taking down the whole generation again. session.hook('context') payload shape is unchanged and keeps working. Verified end-to-end on opencode2 v0.0.0-beta-17595: 24 skills listed via /api/skill (all superpowers skills present), /api/model returns 83 models across 3 providers, no 'failed to reload plugins' in server logs. V1 path untouched. * fix(opencode): skip V2 setup when V1 invokes it with a V1-shaped ctx opencode 1.18.18 also calls default.setup, but with a ctx that lacks the skill/session domains, so the defensive try/catch logged a TypeError into every V1 session transcript even though V1 is fully served by the SuperpowersPlugin named export. Detect the V1 shape and return quietly. * feat(skills): import proving-it-works-with-a-movie from its standalone repo Brings the proving-it-works-with-a-movie skill (demo/screencast/proof-video recording, plus the check-movie timeline gate that catches frozen pictures, narration drift, and dropped words) into superpowers core, along with its supporting docs, scripts, and shell regression tests. Source: prime-radiant-inc/proving-it-works (MIT, same copyright holder), skills/proving-it-works-with-a-movie/ at time of import. The five scripts (narrate, make-subtitles, assemble, burn-subtitles, check-movie) are self-contained uv --script files with inline PEP 723 dependency declarations, so they port with no new project-level dependency wiring. Test paths were adjusted one directory level to match superpowers' tests/<skill-name>/ layout (the standalone repo kept tests/ as a top-level sibling of skills/). Adds a Verification entry to README's Skills Library list. Goal: fold this into 6.4 and retire the standalone repo. * fix(opencode): skip controller bootstrap in task subagent sessions (#2160) Detect child sessions structurally via session parentID instead of relying on the model honoring <SUBAGENT-STOP>: - V1: sessionID from firstUser.info.sessionID (hook input is empty at runtime), parentID via client.session.get({path:{id}}) - V2: sessionID from the context-hook event, parentID via ctx.session.get({sessionID}) Decision cached per session; lookup failures fail open (previous behavior) and are not cached. Skills registration is unaffected, so workers keep explicit access to execution skills. * fix(opencode): skip controller bootstrap in task subagent sessions (#2160) The messages.transform hook injects the using-superpowers bootstrap into the first user message of every session, including task subagent children. Workers then restart brainstorming/design cycles for work the parent already authorised — the <SUBAGENT-STOP> note inside the bootstrap only works when the model chooses to honor it. Detect child sessions structurally instead: OpenCode task sessions are created with a parentID, so when the session carrying the message has a parentID, skip bootstrap injection. The hook receives no input at runtime (verified in the 1.18.x bundle: trigger(..., {}, {messages})), so the sessionID is taken from firstUser.info.sessionID and the session record is fetched via client.session.get({path:{id}}). The decision is cached per session; lookup failures fail open (previous inject-always behavior) and are not cached so transient errors recover. Skills registration is untouched — workers keep explicit access to execution skills. * fix(opencode): add root index.js entrypoint for v2 directory-form registration * docs(opencode): remove and merge identical v1/v2 install and update guidance * Fix platform-support issue template to apply a label that exists The template auto-applies `platform-support`, but the repo has no such label (harness requests use `new-harness`). GitHub silently drops labels that don't exist, so every platform-support request arrives unlabeled — the Amazon Q request (#2194) is the latest example. Claude-Session: https://claude.ai/code/session_01UiEfXTZAC5cuH4hgx24mbB * fix: establish shared intent before implementation Discover the intended outcome, audience and success criteria before proposing features when the request leaves them unclear. Reflect the understanding for correction and carry it into the selected path's design artifact. Bind approval to the actual stage presented: new architectural work requires written-spec review and the planning handoff before implementation. Preserve the existing lighter spike and bounded paths and clarify the short-design example accordingly. Jesse requested this repair after a React todo session advanced from feature scope approval without establishing purpose. The controlled CLI comparison observed purpose discovery in 5/5 candidate openings versus 0/5 controls, with full-chain and holdout outcomes and their limits recorded in the PR. This commit preserves the independently reviewed skill bytes; research artifacts and the original development history are archived outside the PR. * fix: review the saved plan before execution Present the saved, self-reviewed plan for human review before implementation. Request an execution method when none was supplied; preserve an existing choice and ask only for plan review when the human already chose a method. This completes the shared-intent repair without interpreting approval of an earlier idea or scope as approval of an unseen implementation plan. Four saved-plan smoke cases covered old/new wording with/without a prior choice; all passed the narrower handoff checks, including old controls, so this is not evidence of measured improvement. Jesse requested consolidation into two commits and removal of the supporting spec/plan research content from the PR. The skill bytes remain identical to the reviewed branch; the complete research and original history are retained in local archives. * docs: specify proof movie OS compatibility * docs: resolve adversarial review of movie compatibility spec * docs: plan proof movie OS compatibility with Windows validation host * test(movie): validate native Windows recording mechanism * fix(movie): release probe resources after evidence failures * docs(movie): avoid repeating the interactive probe take * test(movie): port regression fixtures to Python * test(movie): verify first subtitle cue offset * fix(opencode): differentiate tool mapping by host flavor and harden child detection Current opencode2 builds renamed the model-facing tools (bash→shell, task→subagent with `agent` instead of `subagent_type`, apply_patch→ patch/patchText) and removed todowrite entirely, so the single v1 mapping injected on v2 hosts taught the model stale tool names. - export V1_MAPPING/V2_MAPPING and inject the flavor-correct one on each path (v1 messages.transform → V1; v2 ctx.session.hook("context") → V2, incl. no-todo-tool guidance and sessionID continuation) - child-session detection now keys on parentID presence (primary signal on both flavors) with dual-shape unwrapping preserved; v1 #2160 behavior unchanged - mirror surfaces updated: INSTALL.md dual mapping tables, README.opencode.md host-flavor notes, test-bootstrap-caching.mjs asserts both mappings + drives the v2 context hook end-to-end - skills: add OpenCode to executing-plans' subagent-capable list, accurate OpenCode worktree status (git fallback; TUI dialogs are user-side only), generalized live-subagent resume guidance * fix(movie): make frame and concat inputs portable * docs: scope remaining movie work to Windows completion * docs: resolve adversarial review of Windows completion scope * docs: plan three milestones to finish Windows movie support * fix(opencode): drop skill-content edits from this PR AGENTS.md requires evaluated adversarial testing for any skill-content change; these three one-line harness-accuracy notes don't clear that bar, so they are deferred to a separate evaluated change. The PR now ships plugin, docs, and test changes only — no skill content modified. * fix(movie): finish native Windows media tools * feat(movie): support native Windows terminal recording * fix(movie): verify terminal health before finalizing takes * docs(movie): document and verify Windows workflows * docs(movie): correct reserved regression suite names * chore(movie): drop the abandoned OS-rollout probe and superseded plans The first, broader OS-compatibility rollout was stopped and replaced by the narrower Windows completion. Its feasibility probe, probe cleanup test, design, review, 12-task plan, results report, and the completion plan and review record were internal execution artifacts with machine-specific paths. The one probe-derived test list is inlined into the terminal suite. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(movie): keep one portable test suite The Python suite ported the three shell tests' assertions so they run on Windows; both copies were kept and the README mapped one to the other. Keep the portable suite. Drop the one-shot Windows acceptance driver and its browser fixture, which produced evidence rather than regressions, and the never-implemented reserved suite names. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(movie): trim Windows guidance to what the tools need Remove generic shell exit-status recipes and a stills wrapper that the card scene already covers. Keep the gdigrab commands and the verify-on notes short. Reduce the spec to the design: drop execution logistics, host names, and references to deleted files. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(movie): keep tool output out of the test log The in-process narration and subtitle tests let the tools' stdout and stderr through to the runner. Capture both and assert the expected diagnostics. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(movie): simplify the Windows terminal recorder to serve/run/key/watch/close Windows has no tmux, so the recorder had grown into a 738-line daemon with a file-based request protocol, request IDs, wait-only result retrieval, and a Win32 Job Object module. Replace it with the Unix route's shape: serve keeps ttyd and a headless browser alive and logs the terminal's output; run, key, watch, and close are one-shot CDP calls against that browser. The installed prompt reports each command's status through the window title, so run can print it without any visible marker. Process cleanup uses taskkill /T (a pgrep walk on Unix) instead of Job Objects, which also simplifies the card renderer. The session tests run on macOS too, since nothing in the script is Windows-specific. Verified: 9 session tests per shell on Windows 11 for PowerShell 5.1, PowerShell 7, and Git Bash; the browser suite with Chrome and Edge; 44 portable tests on macOS against a real ttyd session. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat: add diagnosing-superpowers skill Evidence-based diagnosis of superpowers sessions: intake with the human partner, safe transcript reading for Claude Code and Codex (discovery procedure for other harnesses), seven analyst subagents, a report with path:line evidence and a bounded superpowers-involvement line, scrubbed export bundles, approval-gated GitHub issue search/draft, and similar-session search. Includes spec, plan, structure test, and README and docs index lines. Developed RED-GREEN-REFACTOR per writing-skills: 46 scored scenario runs across five SKILL.md versions, all twelve scenarios clean against the final version, micro-tests control 5/5 to skill 0/5 on both baseline-failing prohibitions, and one end-to-end run. Eval records are kept by the maintainer outside the repo. Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7 * docs: add 'When Something Goes Wrong' README section for diagnosing-superpowers * diagnosing-superpowers: build the scrubbed bundle only on request Never build or push a bundle unprompted. When intake names a bug report as the goal, say once that a bundle is available on request, then wait. On handover, state what the bundle contains, point at the scrub log, and say scrubbing can miss things so every file needs review before sharing. Raise the SKILL.md word budget to 1000 to fit the added rule. * diagnosing-superpowers: share the analyst preamble and context-safety rules The seven analyst prompts opened with an identical 39-line block (role, inputs, context safety, return format). It now lives once in prompts/analyst-common.md and each dimension prompt points at it. The wc -lc / long-line / never-cat rule was restated in nine places; it now lives in references/context-safety.md and everything else points there. Addresses arittr's review on #2236. * diagnosing-superpowers: drop gh; file issues through a prefilled template link A default gh login carries the repo scope, which is write access to every repository the user can reach. The skill now searches issues through the unauthenticated public API and, instead of posting, hands the partner a prefilled new-issue link. The link uses a new diagnosis_report.md issue template so the bug and automated-issue-report labels apply regardless of the reporter's permissions. Addresses arittr's review on #2236. * diagnosing-superpowers: say 'plan step', not 'commitment' In a transcript full of git commits, 'commitment' and 'committed to' read as version control. The plan-adherence and quality-evidence prompts now say 'agreed plan' and 'plan step'. * spec: 'agreed to', not 'committed to', in the plan-adherence summary * diagnosing-superpowers: writing review fixes Move GitHub search and prefilled-link mechanics to references/github-issues.md. State the redaction levels neutrally instead of nudging toward more data. Say that all seven analysts always run and what the quick-reference table is for. Add a title slot and a bundle slot to the issue template. Drop the duplicated human-prompts rule from request-conflicts. Prose fixes: active voice, dangling modifier, vague referents, two lists turned into tables. * diagnosing-superpowers: use gh for issue search and creation gh handles auth, rate limits, and JSON, and the approval gate on the exact issue text already covers posting. Keep the public-API and prefilled-link paths as fallbacks for machines without gh. Note that GitHub drops labels from reporters without push access, so the template footer is the durable marker of a skill-filed issue. * Use shared session discovery in diagnosing-superpowers At Drew's request, apply the evaluated shared-discovery variant to Jesse's existing PR #2236. Resolve native session sources and record semantics from available tools, documentation and bounded inspection. Record verified absolute paths, linkage, extraction queries, human-message distinctions, usage-counter semantics and uncertainty once in the case for all analysts to consume. Replace the three per-harness references and update structural checks. This is exactly the evaluated source tree at 3f0a63e860d4719397e584e90cc7af07a247cb6d, applied as one commit on 801badbf719f4044c97175e5b01fb6f7cbc32c2d. Fourteen files change; 126 lines added, 285 removed. No private eval fixtures or transcripts ship. Validation: - Structural test: 45 passed, 0 failed before and after application. - Staged tree exactly matches the evaluated candidate; diff check passes. - Independent read-only review: no actionable blockers. - Retained before/after full doctor runs: one pair each on native Claude, Codex and Pi. All six delivered reports and completed seven dimensions. Shared discovered all three native session families without the removed references. Both versions had report-quality defects; shared Codex deleted its cited case through a fixture symlink. Preserve this negative result. - Eight fresh Codex follow-ups: original/shared x symlink/ordinary-home x two repeats, one retained historical session family. All eight retained cases and supported the four core findings. Seven native final deliveries; one shared run stopped on provider capacity after writing its report. No deletion recurred. One original reused three analysts for seven tasks. Recorded follow-up cost $34.8617883, all eight attempts accounted for. These observations support this scoped simplification, not general equivalence or a causal claim that reference removal caused or could not cause a failure. Child assignment/model choices were native behavior; the complete variants also differ in analyst prompts. Common provenance, citation-verification and measurement problems remain separate follow-ups. No new paid runs were made for this publication; evidence and independent audits are retained privately by Drew. Behavioral evaluation provenance: campaigns 358c7333-c5f0-48bd-a733-61196da992ed and 102d630d-30ef-49a0-97e1-8dd410ed0548. Prepared with GPT-6 using Codex through Paseo; local codex-cli 0.153.4. Skills used: superpowers writing-skills, using-git-worktrees, requesting-code-review, verification-before-completion; primeradiant-ops linear-ticket-lifecycle. Drew approved publishing this evaluated variant. Enabled plugins in the publishing checkout's Codex configuration: - github@openai-curated - documents@openai-primary-runtime - spreadsheets@openai-primary-runtime - presentations@openai-primary-runtime - primeradiant-ops@primeradiant - slack@openai-curated - linear@openai-curated - codex-security@openai-curated - pdf@openai-primary-runtime - template-creator@openai-primary-runtime - sites@openai-bundled - visualize@openai-bundled - computer-use@openai-bundled - cloud-build@superpowers-cloud-build - browser@openai-bundled - superpowers@superpowers-dev - stream-deck-agents-codex@drew-local - computer-history@openai-bundled - codex-app-tools@openai-bundled - unified-computer-use@openai-bundled - chrome@openai-bundled - bits-and-bolts@mcp-extensions-early-access - visual-probe@visual-probe-local Tracking: PRI-3127 * Preserve diagnostic evidence through doctor export Align scrubber and independent audit prompts around one shared redaction policy while preserving safe command, result, source, session-line, quotation, and linkage structure. Add finished-handoff evidence and reconciliation instructions, provenance labels across case/report/bundle/issue templates, and the structural existence check for the shared reference.\n\nThis patch responds to the retained negative post-report handoff baseline: cited result bodies were removed wholesale, source findings and the positive related-session match were not verifiable, provenance and export statements were stale, and scrub counts disagreed. The behavioral handoff validation remains pending for the follow-up task; this commit records only the focused product guidance and structural RED/GREEN evidence. * Clarify scrub audit return contract Remove the obsolete CLEAN branch beneath the audit prompt's Otherwise return instruction. CLEAN remains governed by the preceding no-misses condition, and MISSED is now the only alternative. Verified with the focused structural test and git diff --check. * fix(movie): preserve rejected narration and prior takes Prevent failed narration scenes from entering the cache manifest, while leaving their generated WAV files available as failure evidence. Add filesystem-backed regressions covering repeated rejected chat synthesis, accepted-scene reuse, and strict ASR rejection of cached audio. Refuse nonempty recording directories both before CLI session side effects and at the direct film boundary. The regression preserves existing numbered frames and a sentinel byte-for-byte across run, key, watch, and direct film refusal. Make subtitle capability tests independent of the host FFmpeg installation, skip the real pixel test before probing unavailable tools, retain strict skipped-capability rejection, and remove only the unused websockets runner dependency. * docs(movie): make native Windows recorder recipes executable Replace the Git Bash PowerShell shorthand with complete native commands, explicit path conversion, a kept-alive serve task, bounded readiness, and run/key/watch/close examples. Use native input and sleep commands so the recipe works without a sample app. Explain empty take directories and PowerShell 5.1 embedded-quote escaping observed in native trials. The original PowerShell missing-cwd finding does not reproduce when the session is nested under the working directory; retain the successful baseline and describe explicit directory creation as setup clarity. Fresh readers exercised the final recipes on native PowerShell 5.1, PowerShell 7, and Git Bash. Preserve the failed first candidate and driver setup failures, distinguish instruction trials from full skill evaluation, and keep movie acceptance with Drew. Record Drew's approval of the normal workflow dependencies and the bounded repair plan. * Fix narration cache identity and partial subtitle offsets Address the fresh review on PR #2214 after the #2275 integration. Drew approved fixing the two reproduced bugs and keeping the specified auto/on/off verification semantics. Cache accepted narration by normalized text plus effective engine, voice, and synthesis model. Resolve voice defaults before rendering, invalidate entries without settings, and retain requested ASR checks on cache hits. Exclude rejected clips as before. Treat manual subtitle offsets as start-time overrides. Only assembly offsets JSON selects scenes in the cut, including when manual timing overrides are also supplied. Empty narrated cuts write an empty SRT without crashing. Make the gated Unix example pass --verify on and document the actual local ASR modes. Auto remains permissive if ASR is unavailable; on remains strict. Validation: observed the new cache and subtitle regressions fail before the fixes; all 23 focused narration and subtitle-text tests now pass. Synthesis, duration probing, and ASR are mocked. No media inspection or live ASR was performed; Drew retains final video acceptance. * Fix inserted narration and movie audio subtitle checks Address the final three review findings on PR #2214, as approved by Drew. Count both sides of every non-equal transcript span so a short insertion or expanded replacement cannot evade the drift gate on a longer script. Preserve the existing length and run thresholds. Honor --no-expect-audio for encoded silent tracks. Base subtitle requirements on detected audible speech so opting out of expected audio does not suppress captions for speech that is present. Extract the first embedded subtitle stream as SRT when no sidecar is present and apply the same cue-end check to either source. Empty cues fail even for short narration, and extraction or malformed timing errors are reported as failures. Preserve the silent end-card allowance. Validation: the new tests first reproduced ten failing cases across narration insertion, silent-track opt-out, and embedded subtitle handling. All 35 focused narration, checker-policy, and subtitle-text tests now pass. External media commands, audio and picture sampling, contact-sheet creation, synthesis, and ASR were mocked; no actual media inspection or live ASR was performed. Drew retains final video acceptance. * docs: plan consolidated movie committee repairs Drew requested a whole-PR committee review after repeated narrow fixes missed failures. Record the repair boundaries, acceptance handoff, timing and lifecycle contracts, and focused regression cases before implementation. Preserve existing artifact formats and Drew-owned video acceptance; all automated checks in this pass use mocked media boundaries. * fix(movie): make narration acceptance govern assembly Repair Task 1 from the 2026-09-11 movie committee plan. Narration now atomically withdraws acceptance before it mutates accepted bytes, stages failed takes as retained evidence, and publishes a manifest entry only after transcript gates and duration measurement. It preflights ffprobe, preserves bounded retries and cache identity, and distinguishes unsupported token comparison from cache identity. Assembly now validates accepted manifest narration before it starts encoding, ignores generated narration for movie scenes, selects manifest WAV paths, maps source or synthetic movie audio explicitly, fits wide movies within the requested inner rectangle, and escapes only literal directory percent signs in sequence paths. The focused regression suite mocks every media boundary; real-media fixture declarations are updated but not executed. Prompt constraints prohibit real media generation, probing, inspection, synthesis, ASR, browser, checker, or full media suites. * fix(movie): retain narration evidence through verification Address Task 1 review round 1. Treat successful empty ASR output as speech failure rather than an unavailable verifier, reject empty chat claims within the existing bounded retry loop, and extend unsupported segmentation detection to supplementary CJK ideographs. Withdraw cached acceptance before every revalidation so strict failures and interrupts cannot leave stale publication. Preserve nested manifest WAV paths on cache reacceptance, and measure a unique candidate before promotion so duration failures retain their evidence across reruns. Add structured movie geometry coverage plus both silent and source-audio mapping tests. All tests use uv --no-project with mocked synthesis, ASR, probes, and encoding; no media operation was run. * test(movie): cover unsupported ASR and ordinary retries Close Task 1 review round 2 without production changes. Feed actual unsupported ASR text through auto and strict verification while proving off does not call ASR. Run the second rejected narration invocation without --force, then assert it synthesizes new takes and retains distinct rejected bytes instead of reusing cache evidence. * fix(movie): keep subtitle timing and track selection faithful Implement Task 2 of the movie committee repairs. Allocate proportional cue boundaries across each complete rounded scene interval, reserve positive millisecond spans, and coalesce chunks when the available interval cannot represent them separately. Readability limits guide word splitting without dropping text or clipping narration tails; invalid intervals fail before subtitle output is written. Explicitly select the supplied soft subtitle track with optional source audio, including the hard-burn fallback. Parse only numbered SRT cue timing lines so arrow-bearing captions cannot crash the checker or inflate coverage. Preserve the existing maximum cue end policy, assembly-offset intersection, and partial manual retiming. Add 17 safe subtitle contracts and register the contracts runner suite. Real-file mocked narrate/assemble/subtitle reruns retain removed narration WAV evidence while omitting stale assembly audio and offsets. Verification: 41 contract tests and 18 authorized existing regressions pass; only text and mocked media boundaries were exercised. Native Windows and human video acceptance remain outside this verification. * fix(movie): refine subtitle chunks using allocated durations Address Task 2 review round 1: initial character budgets count spaces that disappear between chunks, so proportional timing can exceed --max-secs even when a further word-boundary split is feasible. Reallocate after splitting an over-target multiword cue, checking actual integer millisecond intervals each time. Coalescing runs once before refinement, and refinement stops at the available millisecond count or unsplittable words. This keeps tiny impossible readability targets bounded while preserving every word and the full measured scene interval. Added a failing six-second unequal-chunk regression and a tiny-target termination/positive-interval guard. The RED emitted 3273 ms for a cue with a 3000 ms target. GREEN: 43 safe contract tests and six covering existing offset/BOM tests pass. All verification remained text/data or mocked media boundaries. * fix(movie): own recorder cleanup and bound observation Implement Task 3 of the consolidated PR 2214 movie repairs. Startup failures could leak an already launched ttyd or browser because acquisitions preceded the cleanup block; close killed historical numeric PIDs and reported success without confirmed cleanup. Register each acquired resource inside serve's try/finally, invalidate readiness on shutdown, retain logs, and atomically retire PID metadata only after confirmed owned-process and profile cleanup. Close now requests stop and waits under one overall 30-second deadline without killing PIDs. Poll CDP and owner readiness while observing commands without recording, preserving a completed native exit status across simultaneous disconnects and reserving exit 2 for live unfinished commands. Fill only bounded 5 fps slots when a final capture crosses the hard or hold endpoint, correctly strip ST-terminated OSC titles, and emit ASCII-escaped stdout JSON while preserving UTF-8 session files. A serve-only CDP call-boundary check prevents a stop from waiting through multiple consecutive calls. Add 21 contract tests using fake processes, fake websocket responses, fake clocks, byte-token capture callbacks, and intercepted frame writes. Register real-session test cleanup immediately after Popen and retain live PID snapshots, but do not execute that fixture. RED evidence and implementation report are in .superpowers/sdd/2026-09-11-movie-committee-repairs/task-3-report.md. Validation: 26/26 authorized prompt, serve-argument, and recorder contract tests pass; git diff --check passes. No media generation, inspection, browser/ttyd launch, real session or frame-grid suite was performed. Native movie acceptance remains Drew's review; an abruptly hard-killed owner with a live browser and stale readiness remains the agreed limitation. * fix(movie): retain incomplete cleanup and command evidence Address both independent Task 3 review findings at 42486dbb. When an owned leader exits before tree cleanup, the existing parentage helper cannot confirm orphan descendant cleanup. Treat that state as incomplete, preserve PID metadata, return failure, and never invoke the helper on the exited leader's numeric PID. Continue releasing the other owned resources without adding descendant tracking. Keep a recording capture failure truthful while preserving available completed command evidence: outcome remains failed, exit status remains 1, and the capture error is retained alongside ok, native exit_code, and cwd. A completed successful command does not make a failed recording successful, and no successful take manifest is published. TDD regressions reproduced an exited leader incorrectly returning 0 and capture failures dropping completed native status for exits 0 and 7. All 14 covering lifecycle and observation tests pass using fake process handles, fake clocks, mocked capture/log boundaries, and intercepted media writes; git diff --check passes. No real media generation or inspection, process/browser launches, SessionTests, FilmGridTests, or full media suites were executed. Detailed RED/GREEN evidence is appended to .superpowers/sdd/2026-09-11-movie-committee-repairs/task-3-report.md. * docs: make proof-movie recipes preserve failures Repair the shipped Unix, logging, subtitle, cursor, narration, and recorder guidance against the literal fake-boundary failures recorded for Task 4. The primary pipeline and subtitle recipe now fail fast, measured offsets reach subtitle generation, producer logging preserves the real status under the pipefail owner, and cursor mouseup restores the released state. Document the accepted narration/cache contract, cooperative recorder cleanup limits, and the safe contracts-suite entrypoint without changing Windows recipes or the existing evidence and human-viewing gates. Include the controller-owned plan bookkeeping and record the executable RED/GREEN results while leaving independent fresh-reader trials pending. Prompt: implement Task 4 focused executable movie-guide corrections after Tasks 1-3, using writing-skills and only fake producers, text fixtures, and fake DOM execution. Verification: python3 .superpowers/review/pr2214/committee/recipe-probes.py; uv run --script tests/proving-it-works-with-a-movie/run-tests.py --suite contracts; git diff --check. * docs: record consolidated movie repair verification Complete the four-task repair plan after independent reviews and two fresh-reader reference trials. Record 66 current contract tests and 45 existing safe regressions, executable recipe failures and repairs, and the limits of those checks. Drew requested a committee and full local review after repeated PR feedback. Preserve the negative evidence, distinguish historical native runs from current mocked/text checks, and retain Drew's video viewing as final acceptance. The whole accumulated PR review and authorized existing-branch update remain the next steps; no merge is performed. * Reject invalid chat transcripts and propagate browser cleanup failures Address the two final whole-PR findings from the consolidated movie repair brief. A fresh openai-chat response must provide a speech-bearing string transcript even when local ASR is off; null must not reuse the no-transcript sentinel belonging to deterministic engines or cached accepted audio. Preserve the bounded candidate loop and rejected-byte evidence. Report failed Windows tree termination as OSError so the recorder owner's existing per-child handler continues all cleanup and retains failure metadata. Card rendering checks its acquired browser handle before acting on the PID, propagates wait failure, and reports locked-profile removal instead of allowing a pending successful return to hide incomplete cleanup. Add fake HTTP/process/filesystem boundary regressions for both findings, including real adapter invocation, accepted chat cache reuse, ASR modes, normal completed cards, and serve cleanup after a failed leader later exits. Correct the rejected-chat fixture to use the chat engine. No media or native browser execution was performed; Drew retains personal video acceptance. Validation: expected RED failures retained; 40 focused tests and the single 75-test contracts entrypoint pass. Full evidence and self-review are in .superpowers/sdd/2026-09-11-movie-committee-repairs/final-fix-report.md. * fix(opencode): align V2 tool mapping with the 2.0.3 catalog; harden plugin internals - V2 bootstrap mapping now teaches write/edit/websearch (verified against a live v2.0.3 /api/plugin tool catalog) instead of routing all file mutation through patch - frontmatter parser tolerates CRLF and YAML block scalars/continuation lines - child-session cache is bounded (512 entries, oldest-quarter eviction) - INSTALL.md and docs/README.opencode.md tool tables synced to the 2.0.3 catalog; unit-test needle list extended to cover the new tools * Invoke bundled scripts through their interpreter in skill prose Plugin packagers for other harnesses can strip executable bits from the files they ship. The Codex marketplace cache delivered the SDD helpers as 0644 (#2040), and the MiniMax Code marketplace ships its repackaged copy of our skills tree with every file at mode 600. On those installs every bare invocation in our skill prose -- `scripts/start-server.sh ...`, `scripts/review-package ...`, `./find-polluter.sh ...`, `./render-graphs.js ...` -- fails with "Permission denied", so the brainstorming visual companion, subagent-driven development, the polluter bisection helper, and render-graphs are all broken there even though the repo records the files as 100755. Spell every script invocation in skills/**/*.md through its interpreter instead: `bash` for the shell scripts (start-server.sh, stop-server.sh, sdd-workspace, task-brief, review-package, find-polluter.sh) and `node` for render-graphs.js, per each script's shebang. That form works whether or not the exec bit survived packaging. The MiniMax Code marketplace package independently applied exactly this edit to its copy of v6.2.0; this brings the same pattern upstream so every packager gets it. Nothing else in the prose changes. #2134 covers the complementary case of a script exec'ing a sibling script (task-brief and review-package calling sdd-workspace) and is still needed alongside this. Record the rationale in docs/porting-to-a-new-harness.md (Part 6 distribution notes plus an Appendix B gotcha) and add a one-line note to writing-skills' File Organization section so future skill authors don't strip the prefixes. Refs #2040, #2134. * fix(opencode): register skills with Skill.Info 2.0.4 path field; contain per-skill add failures Reported on PR #2106 (80avin): on OpenCode v2.0.4 the plugin is disabled at startup with "Plugin disabled after skill.transform failed", losing both skill registration and bootstrap injection. Root cause: upstream commit 199aabe9e2 (first released in v2.0.4) renamed Skill.Info's required file field `location` -> `path` and removed `slash`. draft.add() decodes payloads with Schema.decodeUnknownSync against that schema, so our `location` payloads now fail decode with "Missing key path". Why the failure was silent: the decode error is thrown during the host's state rebuild, where the State layer catches it and hard-disables the whole plugin group asynchronously - the throw never reaches the try/catch around ctx.skill.transform(), and the session "context" hook is torn down as collateral. Fix: - skill payloads now use `path` (2.0.4 contract); no v2.0.3 compatibility retained per review decision - draft.add() failures are contained per skill inside the transform callback, so one rejected payload skips that skill (visible in server logs) instead of the host disabling the entire plugin - new test-skill-registration unit test pins the 2.0.4 payload contract (absolute path field, no stale location/slash, hostile-add containment) and is registered in run-tests.sh; full suite 3/3 green * fix(sdd): ownership markers stop same-basename plans sharing a workspace sdd-workspace slugged workspaces by basename alone, so docs/alpha/plan.md and docs/beta/plan.md resolved to one directory and task-brief silently overwrote the other plan's brief — the single gitignored source of task requirements, unrecoverable once clobbered. Each workspace now records its owning plan in a plan-path marker (repo-relative in-repo, absolute outside). Lookup keeps basename slugs and existing behavior for the common case: a markerless workspace is adopted in place (no migration break for in-flight plans), a marker naming this plan is a match, and a marker naming a different plan disambiguates with the plan's parent-directory name, then a counter. Plan paths are normalized (CDPATH-guarded physical cd) so relative, absolute, and ../ spellings of one plan share one workspace. task-brief and review-package delegate to sdd-workspace and need no changes. SKILL.md's workspace bullet no longer promises the exact <plan-basename> path, since disambiguated workspaces differ. Reported by @CRGDan; reproduction and test groundwork by @crisnahine in PR #2120. Fixes #2045 * feat: add native Muse support (multiprovider) Add .muse-plugin/plugin.json (native Muse contract, 16 skills, SessionStart hook) and marketplace.json so the same repo now serves Muse alongside Claude Code, Codex, Cursor, Gemini, Pi, etc. - skills/using-superpowers/references/muse-tools.md: Muse tool mapping - skills/using-superpowers/SKILL.md: list Muse in Platform Adaptation - hooks/session-start: handle MUSE_PLUGIN_ROOT (SDK standard additionalContext) alongside CURSOR/CLAUDE/COPILOT branches - .version-bump.json: track .muse-plugin/plugin.json and marketplace - README.md: add Muse to TOC and Installation with muse plugins install instructions - AGENTS.md: convert symlink -> regular file copy to satisfy Muse validator (symlink entries rejected as installable) Validated: muse plugins validate => valid:true (diagnostics=1 for expected multiple-manifests warning), all 16 skills validate true. Co-Authored-By: Muse Spark * fix: Muse SessionStart hook must use nested hookSpecificOutput muse-spark-1.3-contributor rejects top-level additionalContext on SessionStart ("unsupported additionalContext in output"). Switch Muse branch to Claude-style nested {hookSpecificOutput:{hookEventName, additionalContext}} which validates and injects correctly (tested via muse exec --provider meta hello world -> success, no hook failed). Co-Authored-By: Muse Spark * docs: fix Muse README to include approve and correct install path README previously showed muse plugins install ./.muse-plugin and muse marketplace add (missing plugins prefix) and omitted the required hooks approval step. Muse warns "hooks require review before activation" on install; fix to muse plugins install ./ + muse plugins approve superpowers per installed flow validated with muse-spark-1.3. Co-Authored-By: Muse Spark * docs: expand Muse section to parity with other harnesses Add clone+install variant, update command, restart/verification notes, and SessionStart hook detail to match Gemini/Pi/Hermes depth. Keeps same install path (muse plugins install ./ + approve) validated with muse-spark-1.3. Co-Authored-By: Muse Spark * Add Claude Code platform reference: a nested orchestrator for cheaper subagent-driven development * docs(testing): describe the Quorum eval lab accurately, replacing stale Drill references The evals harness was renamed Drill -> Quorum and rewritten from Python/uv to Bun/TypeScript; docs/testing.md and CLAUDE.md still described the old tool. Beyond the rename, the old text also misdescribed the system: quorum is the harness CLI, one part of the eval lab — it drives real coding-agent CLIs through a Gauntlet QA agent and grades against scenario acceptance criteria plus deterministic post-checks. The quick start now matches the eval repo's actual commands (bun install / bun run quorum run scenarios/<name> --coding-agent claude; scenarios are directories, not *.yaml) and points at the Live Eval Risk section before anyone runs a permissive-mode session. Drift reported in closed PR #2121 (@JFWaskin); that PR's replacement quick start kept the uv commands, so this rewrite goes from the eval repo's README instead. * Rebuild executing-plans as a first-class inline execution mode A cheaper execution mode alongside subagent-driven development: the session implements every task itself under the same workspace, ledger and stopping rules, with one fresh whole-branch review on the most capable model at the end. Helper scripts task-start/task-done keep the ledger and test log honest; the final fix pass re-grades findings and fixes Critical/Important under TDD. writing-plans' handoff, SDD's when-to-use text and two README lines change to match. * Reviewer judges the spec as a vision document; plans list the five implied cases most likely to bite code-reviewer.md: behavior the spec is silent on is graded by what a reasonable person using the software expects, and a 'Declined to judge' list makes every scoping decision visible. writing-plans: a Review Focus section names the five implied input classes or failure modes most likely to bite, each pinned by a test in the owning task. executing-plans hands the section to the final reviewer and rules on every declined line. * docs: replace duplicated agent guidelines with CLAUDE.md pointer * docs: make AGENTS.md the canonical contributor guidelines * test(opencode): cover canonical skill paths and registration survival * fix(opencode): retry unsuccessful child-session lookups * fix(opencode): retain bootstrap after native compaction * docs(opencode): describe supported V2 setup and bootstrap behavior * docs: clarify OpenCode V1 and V2 skill behavior * chore(opencode): mark test-skill-registration.sh executable Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(opencode): cover bootstrap placement when native compaction retains user messages Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(opencode): strip quote pairs after joining multi-line frontmatter values Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(scripts): exclude root index.js from the Codex plugin sync Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(opencode): fix pin example, local-path examples, and V2 log troubleshooting Restore the version-pin example for both config keys and state the V2 constraint (the pinned ref must include OpenCode V2 support). Replace the `~/...` local-package examples with absolute paths: OpenCode does not expand `~`, and a tilde entry is installed as a package spec rather than loaded as a directory. Point V2 troubleshooting at `opencode run --standalone --print-logs`, since plugin logs are server-role and hidden without `--standalone`. Describe where the bootstrap lands when native compaction retains user messages under the default keep budget. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: draft release notes for v6.4.0 (#2327) * docs: draft release notes for v6.4.0 * docs: tighten v6.4.0 release notes Set the release date, add a lead paragraph, call out the removed batch checkpoints, unify the Native/inline naming, and replace internal jargon. Correct the TDD probe figure and the Claude Code nested-orchestrator opt-in to match #2110 and the reference doc. Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * docs: spell out movie skill dependencies in v6.4.0 notes Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * docs: note AGENTS.md as the canonical guidelines in v6.4.0 notes * docs: name new harnesses in v6.4.0 summary Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * docs: list OpenCode 2.0, Muse, and Qwen Code as new harnesses in v6.4.0 Move the Claude Code nested controller note under Subagent-Driven Development. Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * docs: reword v6.4.0 harness summary Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * test(movie): expect 8 frames from the slow-capture film test (#2329) 42486db made film() fill every grid slot before the endpoint, but this test kept its old count of 7. Its fake clock advances 0.01 s per capture and 0.02 s per sleep, so the prompt is seen at 1.01 s, the 0.4 s hold ends at 1.41 s, and slots 0.0-1.4 s make 8 frames. The test has failed on every run since 42486db. * chore: bump version to 6.4.0 (#2330) Release engineering for 6.4. * Revert movie skill import (#2214) (#2335) Remove the proving-it-works-with-a-movie import at Drew Ritter’s request because its code quality does not meet the release bar. Reverts merge dd53fe0b57223bbbbb8ceae0bda2ba8a26d1c29a and the dependent movie test adjustment in 3979a17bda8691d72bfc5963e5437174c399db67. Remove the later Muse registration and update the unreleased notes so neither advertises the removed skill. Version changes are left for a separate release step. * docs(release-notes): retitle unreleased v6.4.0 notes as v6.4.1 v6.4.0 was prepared but never shipped (release PR #2331 closed unmerged, no tag). The next release is v6.4.1. Rename the section and open it with a note saying v6.4.0 never shipped and that v6.4.1 holds back the proving-it-works-with-a-movie skill for cleanup and robustness work before it returns. The note replaces the revert paragraph added in #2335. Version bumps are left for the release step. Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B * chore: bump version to 6.4.1 v6.4.0 was never shipped; 6.4.1 is the first release with these changes. Points the OpenCode V2 pinning docs at v6.4.1, since no v6.4.0 tag will exist. Excludes the gitignored evals/ clone from the version audit, which was grepping all 11G of it and never finishing. Claude-Session: https://claude.ai/code/session_01BJAzd3A26a2XKo1JUJWySu * docs: fix Muse table of contents indentation * Claude finally honors AGENTS.md, but only if a CLAUDE.md is not present * writing-plans: a plan is decisions, not a transcript (#2333) Replace the No Placeholders prohibition list with a recipe for what a step contains (signature, test with assertions, spec values; a body only where those do not determine it); add a proportion item to the self-review; drop the time unit from the step rule; describe the reader as capable; delete the unreferenced plan reviewer prompt. Measured on two designs: plans halve under the recipe alone and reach a third of their size with the proportion item; every skill-written terse plan executed 9/9 on Sonnet 5. * docs(release-notes): draft v6.4.2 notes (#2382) * docs(release-notes): draft v6.4.2 notes Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd * docs(release-notes): soften v6.4.2 lead Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd * chore: bump version to 6.4.2 Points the OpenCode V2 pin examples at v6.4.2. Claude-Session: https://claude.ai/code/session_012kGFECgxu6pk4fK2L3DjXd * Explain why session-start pipes printf through cat Three open PRs (#2115, #2349, #2367) removed the | cat pipes as no-op subprocess spawns, which would bring back the Windows EPIPE diagnostic fixed in d72560e (#1612). Say so next to the code. * fix(brainstorming): preserve literal content replacement tokens (#2364) * docs(release-notes): brainstorming literal replacement tokens (#2364) * test(brainstorm-server): stop orphaning the server when a test fails process.exit(1) ran inside the try, so the finally that kills the spawned server never ran. The leftover server held port 3334 and the next run died with 'preferred port is in use'. Set process.exitCode instead so teardown runs. * fix(debugging): avoid printing identity secrets in diagnostics (#2380) * docs(release-notes): debugging example no longer prints secrets (#2380) * docs(release-notes): task-done records silently passing tasks (#2388) * fix(executing-plans): task-done no longer aborts when a passing test prints nothing (#2388) Under `set -euo pipefail`, task-done extracted the ledger's test-result field with: last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) When the test command passes but the log is empty or blank-only, `grep -v` matches no lines and exits 1; pipefail propagates that through the pipeline, and set -e aborts the assignment before the ledger line is written. A passing task is then silently not recorded: exit 1, no stderr, no ledger entry — indistinguishable from the failure path the guard exists to produce. Make the no-match case non-fatal, falling back to a literal placeholder for the ledger field: last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1) || last="(no output)" The failure guard above this line (recording nothing when the test command itself exits non-zero) is untouched. Fixes #2385. * fix(hooks): make SessionStart hooks resolve without external PATH lookups (#2349) * fix(hooks): make SessionStart hooks resolve without external PATH lookups SessionStart:startup hooks can run before Claude Code's PATH is repaired (anthropics/claude-code#43127), or ahead of a sibling PATH-fixing hook in the same startup batch. hooks/session-start and the Unix half of hooks/run-hook.cmd both shelled out to dirname, cat, and a PATH lookup for bash itself, so an empty PATH made every SessionStart hook fail outright: hooks/session-start: line 7: dirname: command not found hooks/session-start: line 44: cat: command not found None of those external calls are necessary: - ${0%/*} replaces $(dirname "$0") for both scripts. - ${BASH:-bash} replaces a bare 'bash' in run-hook.cmd's exec — bash always sets $BASH to its own absolute path once running, so no PATH lookup is needed to re-invoke it. - $(<file) (a bash builtin) replaces 'cat file' for reading the skill body. - The trailing '| cat' after each printf branch was a no-op pass-through through another external binary; removed. Adds a regression test in tests/hooks/test-session-start.sh that invokes both hooks under an empty PATH. Fixes #2310. * Split $0 on / or \ so cmd-dispatched hooks find the plugin root run-hook.cmd's Windows half starts bash with a backslash path (C:\...\hooks\session-start). ${0%/*} found no slash there, so session-start resolved the wrong plugin root and injected 'Error reading using-superpowers skill' instead of the skill. MSYS dirname handled backslashes, so dev was fine. Seen on Windows 11 + Git Bash 5.2.37 via cmd /c run-hook.cmd session-start. --------- Co-authored-by: Jesse Vincent <jesse@primeradiant.com> * docs(release-notes): SessionStart with a broken PATH (#2349) * fix(requesting-code-review): avoid positional argument substitution (#2361) * docs(release-notes): code-review base SHA survives skill arguments (#2361) * fix(hooks): run-hook.cmd finds per-user Git, skips WSL launchers and the current directory, keeps exit codes (#2393) Combines and supersedes #1864 and #2365. Fixes #1863. Co-authored-by: citizen204 <161211652+citizen204@users.noreply.github.com> Co-authored-by: KaiyiQuan <156817180+KaiyiQuan@users.noreply.github.com> * docs(release-notes): Windows run-hook.cmd discovery and exit codes (#2393) * docs(release-notes): tidy Hooks list * sdd-workspace: leave an existing .superpowers/sdd/.gitignore alone (#2399) Based on #2161. Also quotes the empty CDPATH so shellcheck passes (SC1007). Co-authored-by: aruizcu1989 <192807317+aruizcu1989@users.noreply.github.com> * docs(release-notes): sdd-workspace keeps an existing .gitignore (#2399) * test(brainstorm-server): run shell helpers without a login shell The lifecycle tests ran their helpers with `bash -lc`, so anything a login profile prints landed in captured output (a path from mktemp, the newest session dir) and broke the test. Plain `bash -c` keeps the helpers independent of the user's shell setup. Fixes #2190. From #2192 by @tugrulguner. Co-authored-by: tugrulguner <47668043+tugrulguner@users.noreply.github.com> * test(sdd-workspace): compare physical paths so the suite passes on Git Bash On Windows, git rev-parse --show-toplevel prints C:/Users/... while the script (and pwd) print /tmp/..., so nine assertions compared two spellings of the same directory and failed. The script itself was correct. Normalize the expected paths the same way the script's output is produced. From #2149 by @t0domanh. Co-authored-by: t0domanh <3890425+t0domanh@users.noreply.github.com> * sdd-workspace: resolve the repo root physically so plan markers stay repo-relative on Git Bash git rev-parse --show-toplevel prints C:/Users/... on Windows while the plan path comes from pwd -P (/c/Users/... or /tmp/...), so the repo-relative check never matched and every marker held an absolute, machine-specific path. Found while landing #2149's test fix on Windows. * test(executing-plans): compare the brief path in the scripts' own spelling on Git Bash * docs(release-notes): plan markers stay repo-relative on Windows * fix(hermes): pass each skill's frontmatter description to register_skill Hermes lists plugin skills (skills_list) with the description given to register_skill, which defaults to "". The plugin registered only a name and path, so all fourteen superpowers skills appeared with blank descriptions and the model had nothing to choose on. Read each SKILL.md's description and pass it through. From #2284 by @pepijn-blom. Co-authored-by: pepijn-blom <322216308+pepijn-blom@users.noreply.github.com> * docs(release-notes): Hermes skill descriptions (#2284) * brainstorming: rebuild around drawing out intent (#2463) * docs: intent doc for brainstorming rebuild Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * docs: spike exemption to the brainstorming gate Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: rebuild around drawing out intent Replaces the spike/bounded/architectural router with an intent-first conversation: open describing questions, recon offers, playback in 200-300 word chunks, then sizing (quick task / small change / project with a written design). The spec reviewer prompt becomes a builder check that asks what a builder would still need to know. Adds tests/brainstorming/first-turn.sh, a first-turn micro-test with no-skill and skill arms. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * tests: multi-turn brainstorming driver with simulated humans Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * tests: harder small-change scenario; clearer launch failure Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: tighter opening, wait for builder check, reason from the why Round 1 multi-turn runs: the builder check went to a background subagent and stalled the conversation; the opening restated the request; one run proposed CLI flags after hearing the tool runs from cron. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: builder check gates the handoff, not the reply; README Claude Code subagents run in the background, so the subject can't block on the builder check. The skill now says what matters (don't hand over the document until the check is back), and converse.sh lets the simulated human wait for the subject's follow-up turn instead of nudging it. Also fixes converse.sh dying before its summary when the work dir has no commits. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: split multi-project requests and take them one at a time Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: show it when the playback describes something visual Across 13 multi-turn runs neither skill ever offered the visual companion, even for a kids' tablet screen. Tying the offer to an observable moment (talk turns to how something looks, or a playback chunk describes it) got offers in 2/3 runs, each as its own message, none upfront. The simulated human now declines browser offers so test runs don't open tabs. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * tests: opt-out, spike, and multi-project brainstorming scenarios Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: resolve review findings from adversarial pass - Opt-out ends the skill and the gate with it (the gate had no rule for it). - Each message ends with one question, no example answers hanging off it; multi-question messages and parenthetical menus showed up in most runs. - Playback marks the agent's guesses as guesses; one run played the agent's own example back as the human's. - Restore the old gate's list of what counts as building (#2258). - Companion offer stays its own message; mockups only after acceptance. - converse.sh: survive a failed human turn, report why a run ended, and keep raw task notifications out of the simulated human's view. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: play back as you go, alternating with questions With playback saved for the end, project brainstorms ran 8-15 questions before the human saw any summary. Interleaved, the first playback lands around turn 3-6 (6 runs: habit-tracker, pottery, offsite x2), so corrections arrive before more questions build on a wrong guess. Total length is about the same. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * tests: blind-pair launcher for comparing brainstorming versions Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: builder check yields one ranked round of questions In a blind comparison (6 testers, old vs new skill), every new-skill tester flagged the builder check: two rounds and 3-9 questions after they'd said 'write it up'. Now the agent warns once that a reviewer reads first, settles minor gaps itself and marks them as its calls, and brings only the questions that change what gets built, in one message, most important first. 4/4 runs (habit-tracker, pottery x2) showed a single round. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * docs: brainstorming rebuild eval results Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * Move the eval harness and results to their own PR Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: one line on writing style Blind testers flagged a researched answer as a wall of text for a non-technical person. Micro-tested 12 style lines on research reports and mid-conversation answers (3 prompts x 5 reps each). Every variant already led with the point; naming a journalist (wire reporter, Mossberg, a Journalism BA) added source attributions. Plain wording shortened research reports by about 12% against no line. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: offer the visual companion whenever seeing would help Lists the moments that call for it (things they'll look at, layouts, flows, options that look different, diagrams/timelines/maps), checks each playback chunk before sending it, and drops the 'token-intensive' line that confused non-technical blind testers. Offers: habit tracker 3/3 (was ~50%), pottery booking 3/3 (was 0/3), at turns 3-7, never upfront; 0/4 on scenarios with nothing visual (sync-tool flag, talk outline). Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: plain style line Tested five style lines across Opus, Sonnet, gpt-6-luna and gpt-6-astra (3 prompts x 5 reps each); none moved length or attribution beyond noise on any model. Keep the plainest statement of intent. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * brainstorming: report the most important findings, offer the rest Research reports to a non-technical person ran 320-400 words on Claude. With this line, replies that offer the rest rose from 1/5 to 4/5 (Opus) and 3/5 (Sonnet); Opus reports ~7% shorter; gpt-6-luna/astra, already ~170-190 words, unchanged. Claude-Session: https://claude.ai/code/session_01M6AdHKvzoBUPTxPnYDwssK * feat(antigravity): native plugin manifest for the Antigravity Marketplace Add .antigravity-plugin/plugin.json with the Marketplace fields (displayName, logo, suggestedPrompts, version, author), a logo rendered from the Superpowers mark by scripts/render-antigravity-logo.sh, and a .version-bump.json entry. The Codex sync excludes the manifest and logo. With the native manifest, agy installs Superpowers as an Antigravity plugin. Before, `agy plugin install <repo>` fell back to importing the repo as a Gemini CLI extension and rejected the copied Claude-format hooks file on every session. Superpowers bootstraps through skill discovery: agy lists each installed skill's description, and using-superpowers' "Use when starting any conversation" gets the model to load it. agy has no session-start hook event; a rules/ file would also load in Cursor, which reads plugin rules from the same repo root; a PreInvocation hook runs on every model call. Verified on agy 1.3.1 (Gemini 3.8 Flash) across 15 clean sessions: brainstorming or systematic-debugging loads before any code. * docs(porting): correct Antigravity guidance The guide described an .antigravity-plugin/install.sh and a generated ANTIGRAVITY.md that never existed. Antigravity now bootstraps through the surfaced skill index. Record what probing agy 1.3.1 found: no session-start hook event, PreInvocation hooks run before every model call, ephemeral messages are dropped on the next call, ${PLUGIN_ROOT} is not set in hooks, hooks.json and rules/ cannot be relocated, and a rules/ file in a shared plugin root also loads in Cursor. * brainstorming: find out which choices about how it gets made they want to own (#2482) * brainstorming: ask which technology choices they want to make A session asked to design an iOS app never discussed platform or stack and built a web app with a home-screen icon. Brainstorming now finds out early which technology choices the person wants to make and which they're handing over: talk it through with a technical partner, pick sensible defaults and say them plainly for someone who isn't, and base defaults on an existing project's stack. The Red Flags row on sensible defaults now says to state them rather than avoid them. * brainstorming: generalize technology guidance to how it gets made Non-software projects (a painting, a cake) need the same move: find out which medium, tools, materials and resources they want to choose, which they're handing over, and what they already have. Software keeps its examples: platform, programming language, libraries. * brainstorming: close the skip-path gap in #2482's defaults rule (#2483) * brainstorming: close the skip-path gap in #2482's defaults rule The opt-out line in Your First Message let a user skip the whole skill, including #2482's rule that stated defaults get said out loud. On the skip path, state any significant how-it-gets-made choice (platform, language, medium) in one plain line before building. #2482 also added a How it gets made paragraph that restates the existing which parts of the how they want to decide bullet in Ground to cover almost word for word. Drop the redundant bullet: the paragraph already covers that ground, plus the genuinely new instructions (state defaults plainly, build on what they already have, record your own calls as yours and never as agreed, strong-views users talk it through while users counting on you get defaults). * brainstorming: use parentheses instead of emdashes in the skip-path line --------- Co-authored-by: Jesse Vincent <jesse@fsck.com> * Release prep for v7.0.0 (#2488) - RELEASE-NOTES.md: v7.0.0 section covering everything on dev since v6.4.2, led by the brainstorming rebuild (#2463, #2482, #2483) - Bump all 11 declared manifests to 7.0.0; OpenCode pin examples point at #v7.0.0 - bump-version.sh --audit matches whole version strings only, so 7.0.0 no longer matches inside 127.0.0.1 - test-render-graphs.sh resolves the real node binary so its empty-PATH case works under version-manager shims (mise, asdf) * brainstorming: look first, and only offer to skip when it fired on its own In 7.0.0 every brainstorming session opened with the same two lines: an offer to skip the questions and an open 'tell me about the moment' question (#2530). It fired even when the user had asked for brainstorming by name, had a spec or plan in hand, or had already said what and why, and it asked before looking at the project. Now, in an existing project or with context the user supplied, the agent reads what they referred to before its first message. The skip offer only appears when the skill fired on its own. When what and why are already established, the agent plays back its understanding and asks what's wrong or missing, since specs are often incomplete; otherwise it still opens with one question that gets them describing. tests/brainstorming-first-message/run.py runs the opening turn of three evals scenarios in headless Claude Code (Opus 5.5, isolated HOME). Against 7.0.0, 5 reps each: skip offer 15/15 including both explicit requests, no code read before asking on the explicit request 5/5, playback 0/10. With this change: skip offer 0/10 on explicit requests and 5/5 when auto- triggered; recon and a grounded playback 10/10 on the explicit and phased-spec scenarios. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: keep the playback short and end on a design question Two transcript reviews of the first round found the playback ran 243-347 words, mostly reciting the request or spec back, and 3 of 5 explicit requests still closed on a why question because the branch was keyed on 'said what and why'. The branch now keys on what they want, caps the playback at 150 words of findings and guesses, and ends by inviting corrections and asking the open design choice that most changes what gets built. Opus 5.5, 5 reps each: replies 154-216 words, corrections invited 10/10, design question 8/10 (two explicit-request reps still ask 'the last time you wished you had this'), auto-trigger check-in 5/5. The first-message harness now runs Codex too (plugin staged as superpowers@debug under an isolated CODEX_HOME, as the evals do) and puts the agent and model in the results directory name. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: key the skip offer on the user's message and spell out the playback ending A cross-model run (Sonnet 5.5, Haiku 5.5, Fable 5.1, Codex gpt-6-luna and gpt-6-astra) and two transcript reviews found three wording gaps: - Claude models ignored the 150-word cap by listing every guess. The cap now covers the whole message and the playback carries the two or three guesses that matter most. - 'Invite corrections and ask one question' got half-followed: Codex dropped the invitation, Claude added a second question. It's now one line inviting corrections, then one question. - 'Fired on its own' doesn't map to Codex, where every skill load is the agent's own read of SKILL.md; Luna dropped the check-in once. The skip offer now keys on whether the user's message asked for brainstorming or a design discussion. 3 reps each on Opus 5.5, Sonnet 5.5, gpt-6-luna, gpt-6-astra: no skip offer on explicit or phased requests (24/24), check-in when the user didn't ask (12/12), recon before asking (24/24). Playback lengths: Sonnet 124-161, Opus 141-204, Codex 57-116 words. Astra now invites corrections 6/6 (was 0/6). Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: recommend a way to build it and name the alternatives considered Jesse wants brainstorming to propose an approach and reference the alternatives it weighed, because models reason better when they have to think through real alternatives before picking one. 'Think wide privately' becomes 'Think wide, then recommend': propose the recommended approach, name the alternatives and their trade-offs, and offer to dig into them. It stays scoped to how it gets built; what they want still starts with them describing. In the first-message playback, a guess about how to build it becomes that recommendation. Before, 0/8 branch playbacks on alexxburg's #2530 prompt named any alternative. After, 3 reps each across four scenarios: Opus and Sonnet name alternatives in 18/18 playbacks, gpt-6-astra in 5/9. Claude playbacks grew to 148-211 words. The first-message harness gains detailed-new-project (alexxburg's prompt in an empty repo). On v7.0.0 Opus and Sonnet asked 'the moment you'd use this' or 'what happens with the PNG' 6/6; the branch plays back and asks about the jobs table and what 'live' means 6/6. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: alternatives only for real forks, checked against the project Transcript reviews of the first alternatives round found strawman alternatives ('Node or Go, neither makes it smaller'), an offer to dig in in only 2/27 playbacks, and 6/6 Claude explicit-request reps recommending a transaction rollback that the fixture's own commit() and file-creating connect() break. Alternatives are now for forks you'd genuinely hesitate between, with obvious defaults stated in a clause; picks get checked against what the project does; and the first-message bullet itself carries the one-clause alternative and the offer to dig in. 3 reps each, Opus and Sonnet: offer to dig in 6/18 (was 2/18); read-only plus seen-set picked 2/6 on explicit-request (was 0/6); Claude playbacks still 161-241 words. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: move the check-in to a light closing offer, cap at 200 words Jesse's calls on the third review round: - The playback cap goes to 200 words, since naming real alternatives needs the room. - The skip offer moves from the opening line to a light one-line offer after the question ('Or if you'd rather I just dive in, say so.'), and how the message ends now has a positive branch for each case. With only a closing conditional, 5/12 Claude reps on explicit requests picked up the offer; with both branches spelled out, 0/12, while 12/12 reps where the user didn't ask for brainstorming still get it. - 'You never need to quote this skill to your human partner.' Astra had quoted the skill at the user in 3/12 runs; 0/34 after. Opus and Sonnet, 3 reps each across four scenarios. Claude playbacks run 183-284 words, so the 200 cap is a target more than a limit. Astra was not rerun on the final wording: the Codex subscription returned 429 on every call. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: reflow the playback bullet Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: make 200 words a target to aim for, not a limit Jesse's call. 3 reps each on explicit-request, phased-spec and detailed-new-project: Opus 223-261 words (was 183-237 with 'stays under'), Sonnet 245-357 (was 179-284). One question per reply and the closing offer placement are unchanged. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * Move the first-message harness to superpowers-evals Skill-behavior evals live in superpowers-evals; tests/ is for plugin infrastructure. The harness is now quick-evals/brainstorming/first-message.py in prime-radiant-inc/superpowers-evals#73. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * Templates: require a human-written summary and the filer's instructions Agent-filed issues and PRs arrive with no human fingerprint and no record of what the agent was told to do. The three issue templates now carry, right after the duplicate-search checkbox, a "Who's filing" section asking who the filer is and what their human partner asked for, and a "Human-authored summary" under 200 words that a human writes in their own words. The PR template gets the same summary and a line for the partner's instructions under its existing "Who is submitting" table. The bug report also asks how the "does not reproduce without Superpowers" checkbox was verified. The PR template, AGENTS.md, and the README now say agent-written PRs that fix issues filed by someone else are not accepted unless a maintainer asked for one, including when the partner hit the same problem: the report goes on the existing issue instead. AGENTS.md previously told agents to "pick ONE issue" from the tracker, which invited exactly that. The Session Diagnosis Report issue template is removed. The diagnosing-superpowers skill supplies its own issue body, which replaces the template body except in the oversize-URL fallback, so the template's only lasting effect was applying the automated-issue-report label for reporters without push access. The skill's prefilled link now lands on bug_report.md, and the skill's footer still marks skill-filed issues. The skill's own issue template carries the same two sections, since the repo template never reached skill-filed issues. "Who's filing" names the filing session's model and harness and quotes the request from that session, because the diagnosed session's first prompt already appears under steps to reproduce and may come from another harness; the footer says which section holds which. The summary slot is reserved for the partner's own words, with a trim request rather than an edit when they run long, and the approval gate in SKILL.md refuses to file while that slot holds a placeholder. The fixed "reporter has not tried reproducing" sentence becomes the template's "How I verified" line, with the box ticked only when a transcript shows the problem did not recur. The design spec's issue-filing section follows. Checked with fresh Sonnet agents filling the skill template from a synthetic diagnosis: eleven runs over three drafts, three on the final wording with the amended gate in context. Of the four told by their partner to skip the write-up or file overnight, none drafted the summary and none filed. On the final wording, the filer's model and the diagnosed Codex session's model landed in the right sections, a partner's untranscribed account of a run without Superpowers was recorded with the box left unticked, and a 216-word summary drew a request to trim rather than an edit. Also along for the ride: the feature request's chooser text says "improvement" instead of "addition", and the PR template's test table heading is plural. Claude-Session: https://claude.ai/code/session_01TfpSRkih629AUwvFyTFr9c * executing-plans: drop the Example Workflow so SKILL.md fits under the compaction cut (#2563) After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). executing-plans was 20,405 bytes, so its last lines fell past the cut. The Example Workflow was the redundant part: it replayed rules the sections above already state (task-start/task-done, rulings in the ledger, re-grading, the single fix pass, the final message's two lists). SKILL.md is now 18,103 bytes. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * writing-skills: move supporting docs and situational guidance into references/ (#2564) * writing-skills: move supporting docs into references/ The repo keeps a skill's on-demand docs in references/ (using-superpowers, diagnosing-superpowers, subagent-driven-development). writing-skills had anthropic-best-practices.md, persuasion-principles.md, testing-skills-with-subagents.md, graphviz-conventions.dot and examples/CLAUDE_MD_TESTING.md at the skill root; they move unchanged except for the links between them. render-graphs.js is a tool and stays. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * writing-skills: move situational guidance to references/ so SKILL.md fits under the compaction cut After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). writing-skills was 26,623 bytes. Guidance it only needs at particular moments now lives in references/, behind a pointer at the moment that needs it: - discovery.md: the SKILL.md template and all of Skill Discovery Optimization (description, keywords, naming, token budgets, cross-references). Read when writing or changing frontmatter, naming, or size. The rule agents break most, that a description names triggering conditions and never the workflow, stays in SKILL.md too. - bulletproofing.md: closing loopholes, spirit vs letter, the rationalization table and red flags. Read when the baseline failure is a discipline failure, as Match the Form to the Failure already scopes it. - flowcharts.md: when a flowchart earns its place, conventions, rendering. SKILL.md is now 16,738 bytes. quick-evals/writing-skills/write-a-skill.py (superpowers-evals) has each rep write a new skill from supplied baseline results. Opus 5.5, 3 reps per scenario, v7.0.0 vs this change: every written skill has a 'Use when' description with no workflow summary (124-248 chars), and every discipline skill tables all five baseline rationalizations and has a red-flags section, on both arms. On this change every rep read the reference its scenario calls for (6/6). Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * subagent-driven-development: move situational content to references/ so SKILL.md survives compaction (#2565) After a compaction, Claude Code re-attaches each invoked skill truncated to 20,000 characters (#2481). SDD was 32,358, so everything from the fix loop on (the five-round cap, the breaker, the ledger round line, the final review's single fix wave, Finish) was gone for the rest of a long session. One reported task ran 18 fix rounds after that. Content SDD only needs at particular moments now lives in references/, behind a pointer at the step that needs it: fix-loop.md (read before every round), final-review.md (with Finish), handling-reports.md (non-DONE statuses), resuming.md (an existing ledger), preflight.md (the conflict scan before Task 1), batching.md, and cannot-verify.md. Those reads come fresh from disk, so they don't depend on what survived compaction. The Process graph shows the fix loop and final review as pointer nodes, and the illustrative Example Workflow is gone. SKILL.md is 19,506 bytes. tests/skill-size/test-skill-size.sh fails when any SKILL.md reaches 20,000 bytes. It still fails for writing-skills and executing-plans. Claude-Session: https://claude.ai/code/session_01EgKgPPzKtNA2okiCmqb11F * brainstorming: lay out approaches, write a design doc at every size, and never skip without consent (#2530) (#2571) Follow-up to #2560. Users on #2530 reported that brainstorming still skips approaches and the spec and jumps to implementation. Against dev (which includes #2560), the gallery scenario reproduced it: the design doc was skipped without consent in 24 of 24 runs. - A checklist before implementing: approaches in their own message and a pick, the design doc, its approval, then writing-plans. A spike they agreed to and an explicit opt-out aren't implementing. - Every size gets a design doc; a small change gets a short one covering what was already discussed. Each doc has an Approaches part. - For a detailed request, the first message echoes it back, flags anything they may not have considered that changes it, and leaves the how for later. - Questions are specific and Socratic and say why they're asked. - Red flags for writing the doc before the approaches and for treating an unwritten doc as approved. * Remove historical planning docs * docs(release-notes): draft v7.0.1 notes * chore: bump version to 7.0.1 * test(brainstorm-server): wait for file events instead of sleeping On macOS, fs.watch (FSEvents) delivered events anywhere from ~100ms to 2.4s after the write on Node 26.10 / Darwin 27, and sometimes held an event back to deliver it in a batch with a later one. The file-watching tests slept a fixed 500ms, so they failed when an event came late, and a late event from one test could trigger a reload or clear state/events during another. Six tests failed on v7.0.0 and on dev, a different six each run. The tests now poll for the outcome with a 5s timeout, wait until the server logs the exact screen event they caused, and drain in-flight events with a barrier file before asserting that nothing reloaded or that state/events survived. 15 consecutive runs pass; dropping the server's .html/dotfile filter still fails both negative tests. --------- Co-authored-by: Mark Rada <markrada26@gmail.com> Co-authored-by: dev_Hakaze <af.nawfal@gmail.com> Co-authored-by: arimu1 <19286898+arimu1@users.noreply.github.com> Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: kumarabd <kumarabd@users.noreply.github.com> Co-authored-by: Drew Ritter <drew@ritter.dev> Co-authored-by: Drew Ritter <drew@primeradiant.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Kattni <kattni@kattni.com> Co-authored-by: GoldJohnKing <GoldJohnKing@live.cn> Co-authored-by: Georgii Perepechko <georgiiperepechko@gmail.com> Co-authored-by: Caio Lopes <caiodesalopes@gmail.com> Co-authored-by: Drew Ritter <arittr@users.noreply.github.com> Co-authored-by: Ada Sen <ada.sen@primeradiant.com> Co-authored-by: 落尘 <cuidong111@gmail.com> Co-authored-by: m2dumpling <nightydumpling@gmail.com> Co-authored-by: Klemens Flöge <117587964+klemens-floege@users.noreply.github.com> Co-authored-by: citizen204 <161211652+citizen204@users.noreply.github.com> Co-authored-by: KaiyiQuan <156817180+KaiyiQuan@users.noreply.github.com> Co-authored-by: aruizcu1989 <192807317+aruizcu1989@users.noreply.github.com> Co-authored-by: tugrulguner <47668043+tugrulguner@users.noreply.github.com> Co-authored-by: t0domanh <3890425+t0domanh@users.noreply.github.com> Co-authored-by: pepijn-blom <322216308+pepijn-blom@users.noreply.github.com>
-rw-r--r--.antigravity-plugin/plugin.json2
-rw-r--r--.claude-plugin/marketplace.json2
-rw-r--r--.claude-plugin/plugin.json2
-rw-r--r--.codex-plugin/plugin.json2
-rw-r--r--.cursor-plugin/plugin.json2
-rw-r--r--.devin-plugin/plugin.json2
-rw-r--r--.hermes-plugin/plugin.yaml2
-rw-r--r--.kimi-plugin/plugin.json2
-rw-r--r--.muse-plugin/marketplace.json2
-rw-r--r--.muse-plugin/plugin.json2
-rw-r--r--.opencode/INSTALL.md2
-rw-r--r--RELEASE-NOTES.md32
-rw-r--r--docs/README.opencode.md2
-rw-r--r--docs/superpowers/plans/2026-01-22-document-review-system.md301
-rw-r--r--docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md523
-rw-r--r--docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md479
-rw-r--r--docs/superpowers/plans/2026-03-23-codex-app-compatibility.md566
-rw-r--r--docs/superpowers/plans/2026-04-06-worktree-rototill.md866
-rw-r--r--docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md1374
-rw-r--r--docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md143
-rw-r--r--docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md774
-rw-r--r--docs/superpowers/plans/2026-06-09-visual-companion-issues.md352
-rw-r--r--docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md785
-rw-r--r--docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md1126
-rw-r--r--docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md1134
-rw-r--r--docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md1649
-rw-r--r--docs/superpowers/plans/2026-07-30-codex-efficiency-fixes.md1009
-rw-r--r--docs/superpowers/plans/2026-08-06-hermes-version-bump-wiring.md304
-rw-r--r--docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md1512
-rw-r--r--docs/superpowers/plans/2026-10-06-antigravity-marketplace.md711
-rw-r--r--gemini-extension.json2
-rw-r--r--package.json2
-rw-r--r--skills/brainstorming/SKILL.md153
-rw-r--r--skills/executing-plans/SKILL.md52
-rw-r--r--skills/subagent-driven-development/SKILL.md288
-rw-r--r--skills/subagent-driven-development/references/batching.md11
-rw-r--r--skills/subagent-driven-development/references/cannot-verify.md10
-rw-r--r--skills/subagent-driven-development/references/final-review.md47
-rw-r--r--skills/subagent-driven-development/references/fix-loop.md77
-rw-r--r--skills/subagent-driven-development/references/handling-reports.md15
-rw-r--r--skills/subagent-driven-development/references/preflight.md26
-rw-r--r--skills/subagent-driven-development/references/resuming.md12
-rw-r--r--skills/writing-skills/SKILL.md324
-rw-r--r--skills/writing-skills/references/CLAUDE_MD_TESTING.md (renamed from skills/writing-skills/examples/CLAUDE_MD_TESTING.md)0
-rw-r--r--skills/writing-skills/references/anthropic-best-practices.md (renamed from skills/writing-skills/anthropic-best-practices.md)0
-rw-r--r--skills/writing-skills/references/bulletproofing.md80
-rw-r--r--skills/writing-skills/references/discovery.md201
-rw-r--r--skills/writing-skills/references/flowcharts.md37
-rw-r--r--skills/writing-skills/references/graphviz-conventions.dot (renamed from skills/writing-skills/graphviz-conventions.dot)0
-rw-r--r--skills/writing-skills/references/persuasion-principles.md (renamed from skills/writing-skills/persuasion-principles.md)0
-rw-r--r--skills/writing-skills/references/testing-skills-with-subagents.md (renamed from skills/writing-skills/testing-skills-with-subagents.md)4
-rw-r--r--tests/brainstorm-server/server.test.js88
-rwxr-xr-xtests/skill-size/test-skill-size.sh31
53 files changed, 817 insertions, 14307 deletions
diff --git a/.antigravity-plugin/plugin.json b/.antigravity-plugin/plugin.json
index 6f85dec..840fd04 100644
--- a/.antigravity-plugin/plugin.json
+++ b/.antigravity-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "superpowers",
"displayName": "Superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "Make your coding agent a better engineer",
"logo": "assets/antigravity-logo.png",
"suggestedPrompts": [
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 92f8ab9..86e715c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.0",
+ "version": "7.0.1",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 86e0b12..64b99c9 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "superpowers",
"description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.0",
+ "version": "7.0.1",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 9a9d0fe..faeb41f 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
index e769727..6ec43b4 100644
--- a/.cursor-plugin/plugin.json
+++ b/.cursor-plugin/plugin.json
@@ -2,7 +2,7 @@
"name": "superpowers",
"displayName": "Superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.0",
+ "version": "7.0.1",
"author": {
"name": "Jesse Vincent",
"email": "jesse@fsck.com"
diff --git a/.devin-plugin/plugin.json b/.devin-plugin/plugin.json
index fd40a96..cadbebd 100644
--- a/.devin-plugin/plugin.json
+++ b/.devin-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "An agentic skills framework & software development methodology that works: planning, TDD, debugging, and collaboration workflows.",
"author": {
"name": "Jesse Vincent",
diff --git a/.hermes-plugin/plugin.yaml b/.hermes-plugin/plugin.yaml
index f2da36c..cb8ae9a 100644
--- a/.hermes-plugin/plugin.yaml
+++ b/.hermes-plugin/plugin.yaml
@@ -1,5 +1,5 @@
name: superpowers
-version: 7.0.0
+version: 7.0.1
description: Superpowers skills and workflow bootstrap for Hermes Agent
author: obra
provides_hooks:
diff --git a/.kimi-plugin/plugin.json b/.kimi-plugin/plugin.json
index 3da881d..379a3bd 100644
--- a/.kimi-plugin/plugin.json
+++ b/.kimi-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "An agentic skills framework and software development methodology.",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/marketplace.json b/.muse-plugin/marketplace.json
index 4306a70..3531bc3 100644
--- a/.muse-plugin/marketplace.json
+++ b/.muse-plugin/marketplace.json
@@ -9,7 +9,7 @@
{
"name": "superpowers",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.0",
+ "version": "7.0.1",
"source": "./",
"author": {
"name": "Jesse Vincent",
diff --git a/.muse-plugin/plugin.json b/.muse-plugin/plugin.json
index 32bdcbf..c77b116 100644
--- a/.muse-plugin/plugin.json
+++ b/.muse-plugin/plugin.json
@@ -2,7 +2,7 @@
"schemaVersion": 1,
"name": "superpowers",
"displayName": "Superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "Core skills library for Muse: TDD, debugging, collaboration patterns, and proven techniques",
"compat": {
"source": "native",
diff --git a/.opencode/INSTALL.md b/.opencode/INSTALL.md
index 2102fd1..c60682f 100644
--- a/.opencode/INSTALL.md
+++ b/.opencode/INSTALL.md
@@ -79,7 +79,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.1"]
}
```
diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md
index 1789816..f63b820 100644
--- a/RELEASE-NOTES.md
+++ b/RELEASE-NOTES.md
@@ -1,5 +1,37 @@
# Superpowers Release Notes
+## v7.0.1 (2026-10-21)
+
+This release retunes brainstorming after its rebuild in v7.0.0. Many of you told us, rightly, that the new default questions got annoying fast and felt formulaic. Brainstorming now digs for context before it asks anything, and tries to ask better questions. We expect to keep tuning it, but we think it's better than it was.
+
+It also trims three long skills so they better survive compaction on Claude Code, and changes the issue and PR templates to ask for a summary written by a human.
+
+### Brainstorming
+
+- **It digs for context first.** In an existing project, or when you point it at a spec, plan, or files, it reads them before its first message and doesn't ask what they already answer. (#2560)
+- **It tries to ask better questions.** v7.0.0 opened every session the same way: an offer to skip the questions, then a generic question about "the moment you wished this existed." Now, when you've already said what you want, it plays your request back with what it found in the project and asks about the one thing still open. Later questions build on your answers and on what it found, and say what the answer would change. (#2560, #2571)
+- **It offers to skip the questions only when it started on its own.** If you asked for brainstorming by name or with `/brainstorming`, it no longer offers to skip it. (#2560)
+- **It lays out the approaches and writes a design doc before building.** It presents two or three ways to build the thing, recommends one, and asks you to pick. Then it writes a design doc, a short one for a small change, and builds nothing until you approve it. Some of you saw it skip the doc and start building; in one of our test scenarios, it skipped the doc without asking in 24 of 24 runs before this change and 3 of 24 after. (#2571)
+
+Thanks to @mbcrawfo for opening #2530, and to @katyatitkova, @ertra, @blorenz, @Biomaj, @fsalum, @technicalpickles, @orochi235, @alexxburg, @fcavalieri, @CelesteCunha, and @zzzzz9999 for the reports, transcripts, and testing there.
+
+If brainstorming's questions in 7.0.1 still don't feel right, please comment on #2530. Examples help most: what you asked, what it asked back, and what you wish it had asked.
+
+### Skills better survive compaction on Claude Code
+
+After a compaction, Claude Code re-attaches each skill cut off at 20,000 characters, so anything past that point is gone for the rest of the session. In one reported session, subagent-driven development lost its five-round limit and ran 18 fix rounds on one task. Thanks @dan-1492 for the report. (#2481)
+
+- **`subagent-driven-development`** moves the fix loop, final review, report handling, resuming, preflight, batching, and cannot-verify guidance into `references/`. It reads each file from disk at the step that needs it. (#2565)
+- **`writing-skills`** moves its supporting docs, the SKILL.md template and discovery guidance, bulletproofing, and flowchart conventions into `references/`. (#2564)
+- **`executing-plans`** drops its Example Workflow, which repeated rules stated above it. (#2563)
+- `tests/skill-size/test-skill-size.sh` fails when any `SKILL.md` reaches 20,000 bytes. (#2565)
+
+### Contributing
+
+- **Issue and PR templates now ask who is filing and what their human partner asked for, plus a summary of under 200 words written by a human.** The bug report also asks how you confirmed the problem doesn't happen without Superpowers. (#2569)
+- **We don't accept agent-written PRs that fix someone else's issue unless a maintainer asked for one.** If your human partner hit the same problem, add their report to the existing issue. The PR template, `AGENTS.md`, and the README say so. (#2569)
+- **`diagnosing-superpowers` adds the same two sections to the issues it drafts** and won't file one while the summary is a placeholder. Its prefilled link now opens the Bug Report template; we removed the Session Diagnosis Report template. (#2569)
+
## v7.0.0 (2026-10-09)
We rebuilt brainstorming from scratch so it does a much better job of what it was always for: helping you work out what you actually want and put it into words before anything gets built. The new skill asks you to describe what you're after and why, plays back what it heard so you can correct it, and keeps asking good questions until the picture is clear. Then it matches the process to the work, from just doing it to writing a full design.
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 980941e..3ffdd81 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -111,7 +111,7 @@ V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v7.0.1"]
}
```
diff --git a/docs/superpowers/plans/2026-01-22-document-review-system.md b/docs/superpowers/plans/2026-01-22-document-review-system.md
deleted file mode 100644
index 6ab9fb8..0000000
--- a/docs/superpowers/plans/2026-01-22-document-review-system.md
+++ /dev/null
@@ -1,301 +0,0 @@
-# Document Review System Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan.
-
-**Goal:** Add spec and plan document review loops to the brainstorming and writing-plans skills.
-
-**Architecture:** Create reviewer prompt templates in each skill directory. Modify skill files to add review loops after document creation. Use Task tool with general-purpose subagent for reviewer dispatch.
-
-**Tech Stack:** Markdown skill files, subagent dispatch via Task tool
-
-**Spec:** docs/superpowers/specs/2026-01-22-document-review-system-design.md
-
----
-
-## Chunk 1: Spec Document Reviewer
-
-This chunk adds the spec document reviewer to the brainstorming skill.
-
-### Task 1: Create Spec Document Reviewer Prompt Template
-
-**Files:**
-- Create: `skills/brainstorming/spec-document-reviewer-prompt.md`
-
-- [ ] **Step 1:** Create the reviewer prompt template file
-
-```markdown
-# Spec Document Reviewer Prompt Template
-
-Use this template when dispatching a spec document reviewer subagent.
-
-**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning.
-
-**Dispatch after:** Spec document is written to docs/superpowers/specs/
-
-```
-Task tool (general-purpose):
- description: "Review spec document"
- prompt: |
- You are a spec document reviewer. Verify this spec is complete and ready for planning.
-
- **Spec to review:** [SPEC_FILE_PATH]
-
- ## What to Check
-
- | Category | What to Look For |
- |----------|------------------|
- | Completeness | TODOs, placeholders, "TBD", incomplete sections |
- | Coverage | Missing error handling, edge cases, integration points |
- | Consistency | Internal contradictions, conflicting requirements |
- | Clarity | Ambiguous requirements |
- | YAGNI | Unrequested features, over-engineering |
-
- ## CRITICAL
-
- Look especially hard for:
- - Any TODO markers or placeholder text
- - Sections saying "to be defined later" or "will spec when X is done"
- - Sections noticeably less detailed than others
-
- ## Output Format
-
- ## Spec Review
-
- **Status:** ✅ Approved | ❌ Issues Found
-
- **Issues (if any):**
- - [Section X]: [specific issue] - [why it matters]
-
- **Recommendations (advisory):**
- - [suggestions that don't block approval]
-```
-
-**Reviewer returns:** Status, Issues (if any), Recommendations
-```
-
-- [ ] **Step 2:** Verify the file was created correctly
-
-Run: `cat skills/brainstorming/spec-document-reviewer-prompt.md | head -20`
-Expected: Shows the header and purpose section
-
-- [ ] **Step 3:** Commit
-
-```bash
-git add skills/brainstorming/spec-document-reviewer-prompt.md
-git commit -m "feat: add spec document reviewer prompt template"
-```
-
----
-
-### Task 2: Add Review Loop to Brainstorming Skill
-
-**Files:**
-- Modify: `skills/brainstorming/SKILL.md`
-
-- [ ] **Step 1:** Read the current brainstorming skill
-
-Run: `cat skills/brainstorming/SKILL.md`
-
-- [ ] **Step 2:** Add the review loop section after "After the Design"
-
-Find the "After the Design" section and add a new "Spec Review Loop" section after documentation but before implementation:
-
-```markdown
-**Spec Review Loop:**
-After writing the spec document:
-1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
-2. If ❌ Issues Found:
- - Fix the issues in the spec document
- - Re-dispatch reviewer
- - Repeat until ✅ Approved
-3. If ✅ Approved: proceed to implementation setup
-
-**Review loop guidance:**
-- Same agent that wrote the spec fixes it (preserves context)
-- If loop exceeds 5 iterations, surface to human for guidance
-- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
-```
-
-- [ ] **Step 3:** Verify the changes
-
-Run: `grep -A 15 "Spec Review Loop" skills/brainstorming/SKILL.md`
-Expected: Shows the new review loop section
-
-- [ ] **Step 4:** Commit
-
-```bash
-git add skills/brainstorming/SKILL.md
-git commit -m "feat: add spec review loop to brainstorming skill"
-```
-
----
-
-## Chunk 2: Plan Document Reviewer
-
-This chunk adds the plan document reviewer to the writing-plans skill.
-
-### Task 3: Create Plan Document Reviewer Prompt Template
-
-**Files:**
-- Create: `skills/writing-plans/plan-document-reviewer-prompt.md`
-
-- [ ] **Step 1:** Create the reviewer prompt template file
-
-```markdown
-# Plan Document Reviewer Prompt Template
-
-Use this template when dispatching a plan document reviewer subagent.
-
-**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
-
-**Dispatch after:** Each plan chunk is written
-
-```
-Task tool (general-purpose):
- description: "Review plan chunk N"
- prompt: |
- You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
-
- **Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
- **Spec for reference:** [SPEC_FILE_PATH]
-
- ## What to Check
-
- | Category | What to Look For |
- |----------|------------------|
- | Completeness | TODOs, placeholders, incomplete tasks, missing steps |
- | Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
- | Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
- | Task Syntax | Checkbox syntax (`- [ ]`) on tasks and steps |
- | Chunk Size | Each chunk under 1000 lines |
-
- ## CRITICAL
-
- Look especially hard for:
- - Any TODO markers or placeholder text
- - Steps that say "similar to X" without actual content
- - Incomplete task definitions
- - Missing verification steps or expected outputs
-
- ## Output Format
-
- ## Plan Review - Chunk N
-
- **Status:** ✅ Approved | ❌ Issues Found
-
- **Issues (if any):**
- - [Task X, Step Y]: [specific issue] - [why it matters]
-
- **Recommendations (advisory):**
- - [suggestions that don't block approval]
-```
-
-**Reviewer returns:** Status, Issues (if any), Recommendations
-```
-
-- [ ] **Step 2:** Verify the file was created
-
-Run: `cat skills/writing-plans/plan-document-reviewer-prompt.md | head -20`
-Expected: Shows the header and purpose section
-
-- [ ] **Step 3:** Commit
-
-```bash
-git add skills/writing-plans/plan-document-reviewer-prompt.md
-git commit -m "feat: add plan document reviewer prompt template"
-```
-
----
-
-### Task 4: Add Review Loop to Writing-Plans Skill
-
-**Files:**
-- Modify: `skills/writing-plans/SKILL.md`
-
-- [ ] **Step 1:** Read current skill file
-
-Run: `cat skills/writing-plans/SKILL.md`
-
-- [ ] **Step 2:** Add chunk-by-chunk review section
-
-Add before the "Execution Handoff" section:
-
-```markdown
-## Plan Review Loop
-
-After completing each chunk of the plan:
-
-1. Dispatch plan-document-reviewer subagent for the current chunk
- - Provide: chunk content, path to spec document
-2. If ❌ Issues Found:
- - Fix the issues in the chunk
- - Re-dispatch reviewer for that chunk
- - Repeat until ✅ Approved
-3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
-
-**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
-```
-
-- [ ] **Step 3:** Update task syntax examples to use checkboxes
-
-Change the Task Structure section to show checkbox syntax:
-
-```markdown
-### Task N: [Component Name]
-
-- [ ] **Step 1:** Write the failing test
- - File: `tests/path/test.py`
- ...
-```
-
-- [ ] **Step 4:** Verify the review loop section was added
-
-Run: `grep -A 15 "Plan Review Loop" skills/writing-plans/SKILL.md`
-Expected: Shows the new review loop section
-
-- [ ] **Step 5:** Verify the task syntax examples were updated
-
-Run: `grep -A 5 "Task N:" skills/writing-plans/SKILL.md`
-Expected: Shows checkbox syntax `### Task N:`
-
-- [ ] **Step 6:** Commit
-
-```bash
-git add skills/writing-plans/SKILL.md
-git commit -m "feat: add plan review loop and checkbox syntax to writing-plans skill"
-```
-
----
-
-## Chunk 3: Update Plan Document Header
-
-This chunk updates the plan document header template to reference the new checkbox syntax requirements.
-
-### Task 5: Update Plan Header Template in Writing-Plans Skill
-
-**Files:**
-- Modify: `skills/writing-plans/SKILL.md`
-
-- [ ] **Step 1:** Read current plan header template
-
-Run: `grep -A 20 "Plan Document Header" skills/writing-plans/SKILL.md`
-
-- [ ] **Step 2:** Update the header template to reference checkbox syntax
-
-The plan header should note that tasks and steps use checkbox syntax. Update the header comment:
-
-```markdown
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Tasks and steps use checkbox (`- [ ]`) syntax for tracking.
-```
-
-- [ ] **Step 3:** Verify the change
-
-Run: `grep -A 5 "For agentic workers:" skills/writing-plans/SKILL.md`
-Expected: Shows updated header with checkbox syntax mention
-
-- [ ] **Step 4:** Commit
-
-```bash
-git add skills/writing-plans/SKILL.md
-git commit -m "docs: update plan header to reference checkbox syntax"
-```
diff --git a/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md b/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
deleted file mode 100644
index 224d349..0000000
--- a/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md
+++ /dev/null
@@ -1,523 +0,0 @@
-# Visual Brainstorming Refactor Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Refactor visual brainstorming from blocking TUI feedback model to non-blocking "Browser Displays, Terminal Commands" architecture.
-
-**Architecture:** Browser becomes an interactive display; terminal stays the conversation channel. Server writes user events to a per-screen `.events` file that Claude reads on its next turn. Eliminates `wait-for-feedback.sh` and all `TaskOutput` blocking.
-
-**Tech Stack:** Node.js (Express, ws, chokidar), vanilla HTML/CSS/JS
-
-**Spec:** `docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md`
-
----
-
-## File Map
-
-| File | Action | Responsibility |
-|------|--------|---------------|
-| `lib/brainstorm-server/index.js` | Modify | Server: add `.events` file writing, clear on new screen, replace `wrapInFrame` |
-| `lib/brainstorm-server/frame-template.html` | Modify | Template: remove feedback footer, add content placeholder + selection indicator |
-| `lib/brainstorm-server/helper.js` | Modify | Client JS: remove send/feedback functions, narrow to click capture + indicator updates |
-| `lib/brainstorm-server/wait-for-feedback.sh` | Delete | No longer needed |
-| `skills/brainstorming/visual-companion.md` | Modify | Skill instructions: rewrite loop to non-blocking flow |
-| `tests/brainstorm-server/server.test.js` | Modify | Tests: update for new template structure and helper.js API |
-
----
-
-## Chunk 1: Server, Template, Client, Tests, Skill
-
-### Task 1: Update `frame-template.html`
-
-**Files:**
-- Modify: `lib/brainstorm-server/frame-template.html`
-
-- [ ] **Step 1: Remove the feedback footer HTML**
-
-Replace the feedback-footer div (lines 227-233) with a selection indicator bar:
-
-```html
- <div class="indicator-bar">
- <span id="indicator-text">Click an option above, then return to the terminal</span>
- </div>
-```
-
-Also replace the default content inside `#claude-content` (lines 220-223) with the content placeholder:
-
-```html
- <div id="claude-content">
- <!-- CONTENT -->
- </div>
-```
-
-- [ ] **Step 2: Replace feedback footer CSS with indicator bar CSS**
-
-Remove the `.feedback-footer`, `.feedback-footer label`, `.feedback-row`, and the textarea/button styles within `.feedback-footer` (lines 82-112).
-
-Add indicator bar CSS:
-
-```css
- .indicator-bar {
- background: var(--bg-secondary);
- border-top: 1px solid var(--border);
- padding: 0.5rem 1.5rem;
- flex-shrink: 0;
- text-align: center;
- }
- .indicator-bar span {
- font-size: 0.75rem;
- color: var(--text-secondary);
- }
- .indicator-bar .selected-text {
- color: var(--accent);
- font-weight: 500;
- }
-```
-
-- [ ] **Step 3: Verify template renders**
-
-Run the test suite to check the template still loads:
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: Tests 1-5 should still pass. Tests 6-8 may fail (expected — they assert old structure).
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add lib/brainstorm-server/frame-template.html
-git commit -m "Replace feedback footer with selection indicator bar in brainstorm template"
-```
-
----
-
-### Task 2: Update `index.js` — content injection and `.events` file
-
-**Files:**
-- Modify: `lib/brainstorm-server/index.js`
-
-- [ ] **Step 1: Write failing test for `.events` file writing**
-
-Add to `tests/brainstorm-server/server.test.js` after Test 4 area — a new test that sends a WebSocket event with a `choice` field and verifies `.events` file is written:
-
-```javascript
- // Test: Choice events written to .events file
- console.log('Test: Choice events written to .events file');
- const ws3 = new WebSocket(`ws://localhost:${TEST_PORT}`);
- await new Promise(resolve => ws3.on('open', resolve));
-
- ws3.send(JSON.stringify({ type: 'click', choice: 'a', text: 'Option A' }));
- await sleep(300);
-
- const eventsFile = path.join(TEST_DIR, '.events');
- assert(fs.existsSync(eventsFile), '.events file should exist after choice click');
- const lines = fs.readFileSync(eventsFile, 'utf-8').trim().split('\n');
- const event = JSON.parse(lines[lines.length - 1]);
- assert.strictEqual(event.choice, 'a', 'Event should contain choice');
- assert.strictEqual(event.text, 'Option A', 'Event should contain text');
- ws3.close();
- console.log(' PASS');
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: New test FAILS — `.events` file doesn't exist yet.
-
-- [ ] **Step 3: Write failing test for `.events` file clearing on new screen**
-
-Add another test:
-
-```javascript
- // Test: .events cleared on new screen
- console.log('Test: .events cleared on new screen');
- // .events file should still exist from previous test
- assert(fs.existsSync(path.join(TEST_DIR, '.events')), '.events should exist before new screen');
- fs.writeFileSync(path.join(TEST_DIR, 'new-screen.html'), '<h2>New screen</h2>');
- await sleep(500);
- assert(!fs.existsSync(path.join(TEST_DIR, '.events')), '.events should be cleared after new screen');
- console.log(' PASS');
-```
-
-- [ ] **Step 4: Run test to verify it fails**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: New test FAILS — `.events` not cleared on screen push.
-
-- [ ] **Step 5: Implement `.events` file writing in `index.js`**
-
-In the WebSocket `message` handler (line 74-77 of `index.js`), after the `console.log`, add:
-
-```javascript
- // Write user events to .events file for Claude to read
- if (event.choice) {
- const eventsFile = path.join(SCREEN_DIR, '.events');
- fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
- }
-```
-
-In the chokidar `add` handler (line 104-111), add `.events` clearing:
-
-```javascript
- if (filePath.endsWith('.html')) {
- // Clear events from previous screen
- const eventsFile = path.join(SCREEN_DIR, '.events');
- if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
-
- console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
- // ... existing reload broadcast
- }
-```
-
-- [ ] **Step 6: Replace `wrapInFrame` with comment placeholder injection**
-
-Replace the `wrapInFrame` function (lines 27-32 of `index.js`):
-
-```javascript
-function wrapInFrame(content) {
- return frameTemplate.replace('<!-- CONTENT -->', content);
-}
-```
-
-- [ ] **Step 7: Run all tests**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: New `.events` tests PASS. Existing tests may still have failures from old assertions (fixed in Task 4).
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add lib/brainstorm-server/index.js tests/brainstorm-server/server.test.js
-git commit -m "Add .events file writing and comment-based content injection to brainstorm server"
-```
-
----
-
-### Task 3: Simplify `helper.js`
-
-**Files:**
-- Modify: `lib/brainstorm-server/helper.js`
-
-- [ ] **Step 1: Remove `sendToClaude` function**
-
-Delete the `sendToClaude` function (lines 92-106) — the function body and the page takeover HTML.
-
-- [ ] **Step 2: Remove `window.send` function**
-
-Delete the `window.send` function (lines 120-129) — was tied to the removed Send button.
-
-- [ ] **Step 3: Remove form submission and input change handlers**
-
-Delete the form submission handler (lines 57-71) and the input change handler (lines 73-89) including the `inputTimeout` variable.
-
-- [ ] **Step 4: Remove `pageshow` event listener**
-
-Delete the `pageshow` listener we added earlier (no textarea to clear anymore).
-
-- [ ] **Step 5: Narrow click handler to `[data-choice]` only**
-
-Replace the click handler (lines 36-55) with a narrower version:
-
-```javascript
- // Capture clicks on choice elements
- document.addEventListener('click', (e) => {
- const target = e.target.closest('[data-choice]');
- if (!target) return;
-
- sendEvent({
- type: 'click',
- text: target.textContent.trim(),
- choice: target.dataset.choice,
- id: target.id || null
- });
- });
-```
-
-- [ ] **Step 6: Add indicator bar update on choice click**
-
-After the `sendEvent` call in the click handler, add:
-
-```javascript
- // Update indicator bar
- const indicator = document.getElementById('indicator-text');
- if (indicator) {
- const label = target.querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || target.dataset.choice;
- indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
- }
-```
-
-- [ ] **Step 7: Remove `sendToClaude` from `window.brainstorm` API**
-
-Update the `window.brainstorm` object (lines 132-136) to remove `sendToClaude`:
-
-```javascript
- window.brainstorm = {
- send: sendEvent,
- choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
- };
-```
-
-- [ ] **Step 8: Run tests**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add lib/brainstorm-server/helper.js
-git commit -m "Simplify helper.js: remove feedback functions, narrow to choice capture + indicator"
-```
-
----
-
-### Task 4: Update tests for new structure
-
-**Files:**
-- Modify: `tests/brainstorm-server/server.test.js`
-
-**Note:** Line references below are from the _original_ file. Task 2 inserted new tests earlier in the file, so actual line numbers will be shifted. Find tests by their `console.log` labels (e.g., "Test 5:", "Test 6:").
-
-- [ ] **Step 1: Update Test 5 (full document assertion)**
-
-Find the Test 5 assertion `!fullRes.body.includes('feedback-footer')`. Change it to: Full documents should NOT have the indicator bar either (they're served as-is):
-
-```javascript
- assert(!fullRes.body.includes('indicator-bar') || fullDoc.includes('indicator-bar'),
- 'Should not wrap full documents in frame template');
-```
-
-- [ ] **Step 2: Update Test 6 (fragment wrapping)**
-
-Line 125: Replace `feedback-footer` assertion with indicator bar assertion:
-
-```javascript
- assert(fragRes.body.includes('indicator-bar'), 'Fragment should get indicator bar from frame');
-```
-
-Also verify content placeholder was replaced (fragment content appears, placeholder comment doesn't):
-
-```javascript
- assert(!fragRes.body.includes('<!-- CONTENT -->'), 'Content placeholder should be replaced');
-```
-
-- [ ] **Step 3: Update Test 7 (helper.js API)**
-
-Lines 140-142: Update assertions to reflect the new API surface:
-
-```javascript
- assert(helperContent.includes('toggleSelect'), 'helper.js should define toggleSelect');
- assert(helperContent.includes('sendEvent'), 'helper.js should define sendEvent');
- assert(helperContent.includes('selectedChoice'), 'helper.js should track selectedChoice');
- assert(helperContent.includes('brainstorm'), 'helper.js should expose brainstorm API');
- assert(!helperContent.includes('sendToClaude'), 'helper.js should not contain sendToClaude');
-```
-
-- [ ] **Step 4: Replace Test 8 (sendToClaude theming) with indicator bar test**
-
-Replace Test 8 (lines 145-149) — `sendToClaude` no longer exists. Test the indicator bar instead:
-
-```javascript
- // Test 8: Indicator bar uses CSS variables (theme support)
- console.log('Test 8: Indicator bar uses CSS variables');
- const templateContent = fs.readFileSync(
- path.join(__dirname, '../../lib/brainstorm-server/frame-template.html'), 'utf-8'
- );
- assert(templateContent.includes('indicator-bar'), 'Template should have indicator bar');
- assert(templateContent.includes('indicator-text'), 'Template should have indicator text element');
- console.log(' PASS');
-```
-
-- [ ] **Step 5: Run full test suite**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: ALL tests PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add tests/brainstorm-server/server.test.js
-git commit -m "Update brainstorm server tests for new template structure and helper.js API"
-```
-
----
-
-### Task 5: Delete `wait-for-feedback.sh`
-
-**Files:**
-- Delete: `lib/brainstorm-server/wait-for-feedback.sh`
-
-- [ ] **Step 1: Verify no other files import or reference `wait-for-feedback.sh`**
-
-Search the codebase:
-```bash
-grep -r "wait-for-feedback" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.json"
-```
-
-Expected references: only `visual-companion.md` (rewritten in Task 6) and possibly release notes (historical, leave as-is).
-
-- [ ] **Step 2: Delete the file**
-
-```bash
-rm lib/brainstorm-server/wait-for-feedback.sh
-```
-
-- [ ] **Step 3: Run tests to confirm nothing breaks**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: All tests PASS (no test referenced this file).
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add -u lib/brainstorm-server/wait-for-feedback.sh
-git commit -m "Delete wait-for-feedback.sh: replaced by .events file"
-```
-
----
-
-### Task 6: Rewrite `visual-companion.md`
-
-**Files:**
-- Modify: `skills/brainstorming/visual-companion.md`
-
-- [ ] **Step 1: Update "How It Works" description (line 18)**
-
-Replace the sentence about receiving feedback "as JSON" with:
-
-```markdown
-The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser and can click to select options. Selections are recorded to a `.events` file that you read on your next turn.
-```
-
-- [ ] **Step 2: Update fragment description (line 20)**
-
-Remove "feedback footer" from the description of what the frame template provides:
-
-```markdown
-**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
-```
-
-- [ ] **Step 3: Rewrite "The Loop" section (lines 36-61)**
-
-Replace the entire "The Loop" section with:
-
-```markdown
-## The Loop
-
-1. **Write HTML** to a new file in `screen_dir`:
- - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
- - **Never reuse filenames** — each screen gets a fresh file
- - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
- - Server automatically serves the newest file
-
-2. **Tell user what to expect and end your turn:**
- - Remind them of the URL (every step, not just first)
- - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
- - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
-
-3. **On your next turn** — after the user responds in the terminal:
- - Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
- - Merge with the user's terminal text to get the full picture
- - The terminal message is the primary feedback; `.events` provides structured interaction data
-
-4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
-
-5. Repeat until done.
-```
-
-- [ ] **Step 4: Replace "User Feedback Format" section (lines 165-174)**
-
-Replace with:
-
-```markdown
-## Browser Events Format
-
-When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
-
-```jsonl
-{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
-{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
-{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
-```
-
-The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
-
-If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
-```
-
-- [ ] **Step 5: Update "Writing Content Fragments" description (line 65)**
-
-Remove "feedback footer" reference:
-
-```markdown
-Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
-```
-
-- [ ] **Step 6: Update Reference section (lines 200-203)**
-
-Remove the helper.js reference description about "JS API" — the API is now minimal. Keep the path reference:
-
-```markdown
-## Reference
-
-- Frame template (CSS reference): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/frame-template.html`
-- Helper script (client-side): `${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/helper.js`
-```
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add skills/brainstorming/visual-companion.md
-git commit -m "Rewrite visual-companion.md for non-blocking browser-displays-terminal-commands flow"
-```
-
----
-
-### Task 7: Final verification
-
-- [ ] **Step 1: Run full test suite**
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && node tests/brainstorm-server/server.test.js
-```
-Expected: ALL tests PASS.
-
-- [ ] **Step 2: Manual smoke test**
-
-Start the server manually and verify the flow works end-to-end:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers && lib/brainstorm-server/start-server.sh --project-dir /tmp/brainstorm-smoke-test
-```
-
-Write a test fragment, open in browser, click an option, verify `.events` file is written, verify indicator bar updates. Then stop the server:
-
-```bash
-lib/brainstorm-server/stop-server.sh <screen_dir from start output>
-```
-
-- [ ] **Step 3: Verify no stale references remain**
-
-```bash
-grep -r "wait-for-feedback\|sendToClaude\|feedback-footer\|send-to-claude\|TaskOutput.*block.*true" /Users/drewritter/prime-rad/superpowers/ --include="*.js" --include="*.md" --include="*.sh" --include="*.html" | grep -v node_modules | grep -v RELEASE-NOTES | grep -v "\.md:.*spec\|plan"
-```
-
-Expected: No hits outside of release notes and the spec/plan docs (which are historical).
-
-- [ ] **Step 4: Final commit if any cleanup needed**
-
-```bash
-git status
-# Review untracked/modified files, stage specific files as needed, commit if clean
-```
diff --git a/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md b/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
deleted file mode 100644
index 9bfc666..0000000
--- a/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md
+++ /dev/null
@@ -1,479 +0,0 @@
-# Zero-Dependency Brainstorm Server Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace the brainstorm server's vendored node_modules with a single zero-dependency `server.js` using Node built-ins.
-
-**Architecture:** Single file with WebSocket protocol (RFC 6455 text frames), HTTP server (`http` module), and file watching (`fs.watch`). Exports protocol functions for unit testing when required as a module.
-
-**Tech Stack:** Node.js built-ins only: `http`, `crypto`, `fs`, `path`
-
-**Spec:** `docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md`
-
-**Existing tests:** `tests/brainstorm-server/ws-protocol.test.js` (unit), `tests/brainstorm-server/server.test.js` (integration)
-
----
-
-## File Map
-
-- **Create:** `skills/brainstorming/scripts/server.js` — the zero-dep replacement
-- **Modify:** `skills/brainstorming/scripts/start-server.sh:94,100` — change `index.js` to `server.js`
-- **Modify:** `.gitignore:6` — remove the `!skills/brainstorming/scripts/node_modules/` exception
-- **Delete:** `skills/brainstorming/scripts/index.js`
-- **Delete:** `skills/brainstorming/scripts/package.json`
-- **Delete:** `skills/brainstorming/scripts/package-lock.json`
-- **Delete:** `skills/brainstorming/scripts/node_modules/` (714 files)
-- **No changes:** `skills/brainstorming/scripts/helper.js`, `skills/brainstorming/scripts/frame-template.html`, `skills/brainstorming/scripts/stop-server.sh`
-
----
-
-## Chunk 1: WebSocket Protocol Layer
-
-### Task 1: Implement WebSocket protocol exports
-
-**Files:**
-- Create: `skills/brainstorming/scripts/server.js`
-- Test: `tests/brainstorm-server/ws-protocol.test.js` (already exists)
-
-- [ ] **Step 1: Create server.js with OPCODES constant and computeAcceptKey**
-
-```js
-const crypto = require('crypto');
-
-const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
-const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
-
-function computeAcceptKey(clientKey) {
- return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
-}
-```
-
-- [ ] **Step 2: Implement encodeFrame**
-
-Server frames are never masked. Three length encodings:
-- payload < 126: 2-byte header (FIN+opcode, length)
-- 126-65535: 4-byte header (FIN+opcode, 126, 16-bit length)
-- &gt; 65535: 10-byte header (FIN+opcode, 127, 64-bit length)
-
-```js
-function encodeFrame(opcode, payload) {
- const fin = 0x80;
- const len = payload.length;
- let header;
-
- if (len < 126) {
- header = Buffer.alloc(2);
- header[0] = fin | opcode;
- header[1] = len;
- } else if (len < 65536) {
- header = Buffer.alloc(4);
- header[0] = fin | opcode;
- header[1] = 126;
- header.writeUInt16BE(len, 2);
- } else {
- header = Buffer.alloc(10);
- header[0] = fin | opcode;
- header[1] = 127;
- header.writeBigUInt64BE(BigInt(len), 2);
- }
-
- return Buffer.concat([header, payload]);
-}
-```
-
-- [ ] **Step 3: Implement decodeFrame**
-
-Client frames are always masked. Returns `{ opcode, payload, bytesConsumed }` or `null` for incomplete. Throws on unmasked frames.
-
-```js
-function decodeFrame(buffer) {
- if (buffer.length < 2) return null;
-
- const firstByte = buffer[0];
- const secondByte = buffer[1];
- const opcode = firstByte & 0x0F;
- const masked = (secondByte & 0x80) !== 0;
- let payloadLen = secondByte & 0x7F;
- let offset = 2;
-
- if (!masked) throw new Error('Client frames must be masked');
-
- if (payloadLen === 126) {
- if (buffer.length < 4) return null;
- payloadLen = buffer.readUInt16BE(2);
- offset = 4;
- } else if (payloadLen === 127) {
- if (buffer.length < 10) return null;
- payloadLen = Number(buffer.readBigUInt64BE(2));
- offset = 10;
- }
-
- const maskOffset = offset;
- const dataOffset = offset + 4;
- const totalLen = dataOffset + payloadLen;
- if (buffer.length < totalLen) return null;
-
- const mask = buffer.slice(maskOffset, dataOffset);
- const data = Buffer.alloc(payloadLen);
- for (let i = 0; i < payloadLen; i++) {
- data[i] = buffer[dataOffset + i] ^ mask[i % 4];
- }
-
- return { opcode, payload: data, bytesConsumed: totalLen };
-}
-```
-
-- [ ] **Step 4: Add module exports at the bottom of the file**
-
-```js
-module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
-```
-
-- [ ] **Step 5: Run unit tests**
-
-Run: `cd tests/brainstorm-server && node ws-protocol.test.js`
-Expected: All tests pass (handshake, encoding, decoding, boundaries, edge cases)
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add skills/brainstorming/scripts/server.js
-git commit -m "Add WebSocket protocol layer for zero-dep brainstorm server"
-```
-
----
-
-## Chunk 2: HTTP Server and Application Logic
-
-### Task 2: Add HTTP server, file watching, and WebSocket connection handling
-
-**Files:**
-- Modify: `skills/brainstorming/scripts/server.js`
-- Test: `tests/brainstorm-server/server.test.js` (already exists)
-
-- [ ] **Step 1: Add configuration and constants at top of server.js (after requires)**
-
-```js
-const http = require('http');
-const fs = require('fs');
-const path = require('path');
-
-const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
-const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
-const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
-const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
-
-const MIME_TYPES = {
- '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
- '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
- '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
-};
-```
-
-- [ ] **Step 2: Add WAITING_PAGE, template loading at module scope, and helper functions**
-
-Load `frameTemplate` and `helperInjection` at module scope so they're accessible to `wrapInFrame` and `handleRequest`. They only read files from `__dirname` (the scripts directory), which is valid whether the module is required or run directly.
-
-```js
-const WAITING_PAGE = `<!DOCTYPE html>
-<html>
-<head><title>Brainstorm Companion</title>
-<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
-h1 { color: #333; } p { color: #666; }</style>
-</head>
-<body><h1>Brainstorm Companion</h1>
-<p>Waiting for Claude to push a screen...</p></body></html>`;
-
-const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
-const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
-const helperInjection = '<script>\n' + helperScript + '\n</script>';
-
-function isFullDocument(html) {
- const trimmed = html.trimStart().toLowerCase();
- return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
-}
-
-function wrapInFrame(content) {
- return frameTemplate.replace('<!-- CONTENT -->', content);
-}
-
-function getNewestScreen() {
- const files = fs.readdirSync(SCREEN_DIR)
- .filter(f => f.endsWith('.html'))
- .map(f => {
- const fp = path.join(SCREEN_DIR, f);
- return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
- })
- .sort((a, b) => b.mtime - a.mtime);
- return files.length > 0 ? files[0].path : null;
-}
-```
-
-- [ ] **Step 3: Add HTTP request handler**
-
-```js
-function handleRequest(req, res) {
- if (req.method === 'GET' && req.url === '/') {
- const screenFile = getNewestScreen();
- let html = screenFile
- ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
- : WAITING_PAGE;
-
- if (html.includes('</body>')) {
- html = html.replace('</body>', helperInjection + '\n</body>');
- } else {
- html += helperInjection;
- }
-
- res.writeHead(200, { 'Content-Type': 'text/html' });
- res.end(html);
- } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
- const fileName = req.url.slice(7); // strip '/files/'
- const filePath = path.join(SCREEN_DIR, path.basename(fileName));
- if (!fs.existsSync(filePath)) {
- res.writeHead(404);
- res.end('Not found');
- return;
- }
- const ext = path.extname(filePath).toLowerCase();
- const contentType = MIME_TYPES[ext] || 'application/octet-stream';
- res.writeHead(200, { 'Content-Type': contentType });
- res.end(fs.readFileSync(filePath));
- } else {
- res.writeHead(404);
- res.end('Not found');
- }
-}
-```
-
-- [ ] **Step 4: Add WebSocket connection handling**
-
-```js
-const clients = new Set();
-
-function handleUpgrade(req, socket) {
- const key = req.headers['sec-websocket-key'];
- if (!key) { socket.destroy(); return; }
-
- const accept = computeAcceptKey(key);
- socket.write(
- 'HTTP/1.1 101 Switching Protocols\r\n' +
- 'Upgrade: websocket\r\n' +
- 'Connection: Upgrade\r\n' +
- 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
- );
-
- let buffer = Buffer.alloc(0);
- clients.add(socket);
-
- socket.on('data', (chunk) => {
- buffer = Buffer.concat([buffer, chunk]);
- while (buffer.length > 0) {
- let result;
- try {
- result = decodeFrame(buffer);
- } catch (e) {
- socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
- clients.delete(socket);
- return;
- }
- if (!result) break;
- buffer = buffer.slice(result.bytesConsumed);
-
- switch (result.opcode) {
- case OPCODES.TEXT:
- handleMessage(result.payload.toString());
- break;
- case OPCODES.CLOSE:
- socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
- clients.delete(socket);
- return;
- case OPCODES.PING:
- socket.write(encodeFrame(OPCODES.PONG, result.payload));
- break;
- case OPCODES.PONG:
- break;
- default:
- // Unsupported opcode — close with 1003
- const closeBuf = Buffer.alloc(2);
- closeBuf.writeUInt16BE(1003);
- socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
- clients.delete(socket);
- return;
- }
- }
- });
-
- socket.on('close', () => clients.delete(socket));
- socket.on('error', () => clients.delete(socket));
-}
-
-function handleMessage(text) {
- let event;
- try {
- event = JSON.parse(text);
- } catch (e) {
- console.error('Failed to parse WebSocket message:', e.message);
- return;
- }
- console.log(JSON.stringify({ source: 'user-event', ...event }));
- if (event.choice) {
- const eventsFile = path.join(SCREEN_DIR, '.events');
- fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
- }
-}
-
-function broadcast(msg) {
- const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
- for (const socket of clients) {
- try { socket.write(frame); } catch (e) { clients.delete(socket); }
- }
-}
-```
-
-- [ ] **Step 5: Add debounce timer map**
-
-```js
-const debounceTimers = new Map();
-```
-
-File watching logic is inlined in `startServer` (Step 6) to keep watcher lifecycle together with server lifecycle and include an `error` handler per spec.
-
-- [ ] **Step 6: Add startServer function and conditional main**
-
-`frameTemplate` and `helperInjection` are already at module scope (Step 2). `startServer` just creates the screen dir, starts the HTTP server, watcher, and logs startup info.
-
-```js
-function startServer() {
- if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
-
- const server = http.createServer(handleRequest);
- server.on('upgrade', handleUpgrade);
-
- const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
- if (!filename || !filename.endsWith('.html')) return;
- if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
- debounceTimers.set(filename, setTimeout(() => {
- debounceTimers.delete(filename);
- const filePath = path.join(SCREEN_DIR, filename);
- if (eventType === 'rename' && fs.existsSync(filePath)) {
- const eventsFile = path.join(SCREEN_DIR, '.events');
- if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
- console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
- } else if (eventType === 'change') {
- console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
- }
- broadcast({ type: 'reload' });
- }, 100));
- });
- watcher.on('error', (err) => console.error('fs.watch error:', err.message));
-
- server.listen(PORT, HOST, () => {
- const info = JSON.stringify({
- type: 'server-started', port: Number(PORT), host: HOST,
- url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
- screen_dir: SCREEN_DIR
- });
- console.log(info);
- fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
- });
-}
-
-if (require.main === module) {
- startServer();
-}
-```
-
-- [ ] **Step 7: Run integration tests**
-
-The test directory already has a `package.json` with `ws` as a dependency. Install it if needed, then run tests.
-
-Run: `cd tests/brainstorm-server && npm install && node server.test.js`
-Expected: All tests pass
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add skills/brainstorming/scripts/server.js
-git commit -m "Add HTTP server, WebSocket handling, and file watching to server.js"
-```
-
----
-
-## Chunk 3: Swap and Cleanup
-
-### Task 3: Update start-server.sh and remove old files
-
-**Files:**
-- Modify: `skills/brainstorming/scripts/start-server.sh:94,100`
-- Modify: `.gitignore:6`
-- Delete: `skills/brainstorming/scripts/index.js`
-- Delete: `skills/brainstorming/scripts/package.json`
-- Delete: `skills/brainstorming/scripts/package-lock.json`
-- Delete: `skills/brainstorming/scripts/node_modules/` (entire directory)
-
-- [ ] **Step 1: Update start-server.sh — change `index.js` to `server.js`**
-
-Two lines to change:
-
-Line 94: `env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js`
-
-Line 100: `nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" node server.js > "$LOG_FILE" 2>&1 &`
-
-- [ ] **Step 2: Remove the gitignore exception for node_modules**
-
-In `.gitignore`, delete line 6: `!skills/brainstorming/scripts/node_modules/`
-
-- [ ] **Step 3: Delete old files**
-
-```bash
-git rm skills/brainstorming/scripts/index.js
-git rm skills/brainstorming/scripts/package.json
-git rm skills/brainstorming/scripts/package-lock.json
-git rm -r skills/brainstorming/scripts/node_modules/
-```
-
-- [ ] **Step 4: Run both test suites**
-
-Run: `cd tests/brainstorm-server && node ws-protocol.test.js && node server.test.js`
-Expected: All tests pass
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add skills/brainstorming/scripts/ .gitignore
-git commit -m "Remove vendored node_modules, swap to zero-dep server.js"
-```
-
-### Task 4: Manual smoke test
-
-- [ ] **Step 1: Start the server manually**
-
-```bash
-cd skills/brainstorming/scripts
-BRAINSTORM_DIR=/tmp/brainstorm-smoke BRAINSTORM_PORT=9876 node server.js
-```
-
-Expected: `server-started` JSON printed with port 9876
-
-- [ ] **Step 2: Open browser to http://localhost:9876**
-
-Expected: Waiting page with "Waiting for Claude to push a screen..."
-
-- [ ] **Step 3: Write an HTML file to the screen directory**
-
-```bash
-echo '<h2>Hello from smoke test</h2>' > /tmp/brainstorm-smoke/test.html
-```
-
-Expected: Browser reloads and shows "Hello from smoke test" wrapped in frame template
-
-- [ ] **Step 4: Verify WebSocket works — check browser console**
-
-Open browser dev tools. The WebSocket connection should show as connected (no errors in console). The frame template's status indicator should show "Connected".
-
-- [ ] **Step 5: Stop server with Ctrl-C, clean up**
-
-```bash
-rm -rf /tmp/brainstorm-smoke
-```
diff --git a/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md b/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md
deleted file mode 100644
index 0f35d3d..0000000
--- a/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md
+++ /dev/null
@@ -1,566 +0,0 @@
-# Codex App Compatibility Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `using-git-worktrees`, `finishing-a-development-branch`, and related skills work in the Codex App's sandboxed worktree environment without breaking existing behavior.
-
-**Architecture:** Read-only environment detection (`git-dir` vs `git-common-dir`) at the start of two skills. If already in a linked worktree, skip creation. If on detached HEAD, emit a handoff payload instead of the 4-option menu. Sandbox fallback catches permission errors during worktree creation.
-
-**Tech Stack:** Git, Markdown (skill files are instruction documents, not executable code)
-
-**Spec:** `docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md`
-
----
-
-## File Structure
-
-| File | Responsibility | Action |
-|---|---|---|
-| `skills/using-git-worktrees/SKILL.md` | Worktree creation + isolation | Add Step 0 detection + sandbox fallback |
-| `skills/finishing-a-development-branch/SKILL.md` | Branch finishing workflow | Add Step 1.5 detection + cleanup guard |
-| `skills/subagent-driven-development/SKILL.md` | Plan execution with subagents | Update Integration description |
-| `skills/executing-plans/SKILL.md` | Plan execution inline | Update Integration description |
-| `skills/using-superpowers/references/codex-tools.md` | Codex platform reference | Add detection + finishing docs |
-
----
-
-### Task 1: Add Step 0 to `using-git-worktrees`
-
-**Files:**
-- Modify: `skills/using-git-worktrees/SKILL.md:14-15` (insert after Overview, before Directory Selection Process)
-
-- [ ] **Step 1: Read the current skill file**
-
-Read `skills/using-git-worktrees/SKILL.md` in full. Identify the exact insertion point: after the "Announce at start" line (line 14) and before "## Directory Selection Process" (line 16).
-
-- [ ] **Step 2: Insert Step 0 section**
-
-Insert the following between the Overview section and "## Directory Selection Process":
-
-```markdown
-## Step 0: Check if Already in an Isolated Workspace
-
-Before creating a worktree, check if one already exists:
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-**If `GIT_DIR` differs from `GIT_COMMON`:** You are already inside a linked worktree (created by the Codex App, Claude Code's Agent tool, a previous skill run, or the user). Do NOT create another worktree. Instead:
-
-1. Run project setup (auto-detect package manager as in "Run Project Setup" below)
-2. Verify clean baseline (run tests as in "Verify Clean Baseline" below)
-3. Report with branch state:
- - On a branch: "Already in an isolated workspace at `<path>` on branch `<name>`. Tests passing. Ready to implement."
- - Detached HEAD: "Already in an isolated workspace at `<path>` (detached HEAD, externally managed). Tests passing. Note: branch creation needed at finish time. Ready to implement."
-
-After reporting, STOP. Do not continue to Directory Selection or Creation Steps.
-
-**If `GIT_DIR` equals `GIT_COMMON`:** Proceed with the full worktree creation flow below.
-
-**Sandbox fallback:** If you proceed to Creation Steps but `git worktree add -b` fails with a permission error (e.g., "Operation not permitted"), treat this as a late-detected restricted environment. Fall back to the behavior above — run setup and baseline tests in the current directory, report accordingly, and STOP.
-```
-
-- [ ] **Step 3: Verify the insertion**
-
-Read the file again. Confirm:
-- Step 0 appears between Overview and Directory Selection Process
-- The rest of the file (Directory Selection, Safety Verification, Creation Steps, etc.) is unchanged
-- No duplicate sections or broken markdown
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/using-git-worktrees/SKILL.md
-git commit -m "feat(using-git-worktrees): add Step 0 environment detection (PRI-823)
-
-Skip worktree creation when already in a linked worktree. Includes
-sandbox fallback for permission errors on git worktree add."
-```
-
----
-
-### Task 2: Update `using-git-worktrees` Integration section
-
-**Files:**
-- Modify: `skills/using-git-worktrees/SKILL.md:211-215` (Integration > Called by)
-
-- [ ] **Step 1: Update the three "Called by" entries**
-
-Change lines 212-214 from:
-
-```markdown
-- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
-- **subagent-driven-development** - REQUIRED before executing any tasks
-- **executing-plans** - REQUIRED before executing any tasks
-```
-
-To:
-
-```markdown
-- **brainstorming** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
-- **subagent-driven-development** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
-- **executing-plans** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
-```
-
-- [ ] **Step 2: Verify the Integration section**
-
-Read the Integration section. Confirm all three entries are updated, "Pairs with" is unchanged.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/using-git-worktrees/SKILL.md
-git commit -m "docs(using-git-worktrees): update Integration descriptions (PRI-823)
-
-Clarify that skill ensures a workspace exists, not that it always creates one."
-```
-
----
-
-### Task 3: Add Step 1.5 to `finishing-a-development-branch`
-
-**Files:**
-- Modify: `skills/finishing-a-development-branch/SKILL.md:38` (insert after Step 1, before Step 2)
-
-- [ ] **Step 1: Read the current skill file**
-
-Read `skills/finishing-a-development-branch/SKILL.md` in full. Identify the insertion point: after "**If tests pass:** Continue to Step 2." (line 38) and before "### Step 2: Determine Base Branch" (line 40).
-
-- [ ] **Step 2: Insert Step 1.5 section**
-
-Insert the following between Step 1 and Step 2:
-
-```markdown
-### Step 1.5: Detect Environment
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-**Path A — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` is empty (externally managed worktree, detached HEAD):**
-
-First, ensure all work is staged and committed (`git add` + `git commit`).
-
-Then present this to the user (do NOT present the 4-option menu):
-
-```
-Implementation complete. All tests passing.
-Current HEAD: <full-commit-sha>
-
-This workspace is externally managed (detached HEAD).
-I cannot create branches, push, or open PRs from here.
-
-⚠ These commits are on a detached HEAD. If you do not create a branch,
-they may be lost when this workspace is cleaned up.
-
-If your host application provides these controls:
-- "Create branch" — to name a branch, then commit/push/PR
-- "Hand off to local" — to move changes to your local checkout
-
-Suggested branch name: <ticket-id/short-description>
-Suggested commit message: <summary-of-work>
-```
-
-Branch name: use ticket ID if available (e.g., `pri-823/codex-compat`), otherwise slugify the first 5 words of the plan title, otherwise omit. Avoid sensitive content in branch names.
-
-Skip to Step 5 (cleanup is a no-op — see guard below).
-
-**Path B — `GIT_DIR` differs from `GIT_COMMON` AND `BRANCH` exists (externally managed worktree, named branch):**
-
-Proceed to Step 2 and present the 4-option menu as normal.
-
-**Path C — `GIT_DIR` equals `GIT_COMMON` (normal environment):**
-
-Proceed to Step 2 and present the 4-option menu as normal.
-```
-
-- [ ] **Step 3: Verify the insertion**
-
-Read the file again. Confirm:
-- Step 1.5 appears between Step 1 and Step 2
-- Steps 2-5 are unchanged
-- Path A handoff includes commit SHA and data loss warning
-- Paths B and C proceed to Step 2 normally
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/finishing-a-development-branch/SKILL.md
-git commit -m "feat(finishing-a-development-branch): add Step 1.5 environment detection (PRI-823)
-
-Detect externally managed worktrees with detached HEAD and emit handoff
-payload instead of 4-option menu. Includes commit SHA and data loss warning."
-```
-
----
-
-### Task 4: Add Step 5 cleanup guard to `finishing-a-development-branch`
-
-**Files:**
-- Modify: `skills/finishing-a-development-branch/SKILL.md` (Step 5: Cleanup Worktree — find by section heading, line numbers will have shifted after Task 3)
-
-- [ ] **Step 1: Read the current Step 5 section**
-
-Find the "### Step 5: Cleanup Worktree" section in `skills/finishing-a-development-branch/SKILL.md` (line numbers will have shifted after Task 3's insertion). The current Step 5 is:
-
-```markdown
-### Step 5: Cleanup Worktree
-
-**For Options 1, 2, 4:**
-
-Check if in worktree:
-```bash
-git worktree list | grep $(git branch --show-current)
-```
-
-If yes:
-```bash
-git worktree remove <worktree-path>
-```
-
-**For Option 3:** Keep worktree.
-```
-
-- [ ] **Step 2: Add the cleanup guard before existing logic**
-
-Replace the Step 5 section with:
-
-```markdown
-### Step 5: Cleanup Worktree
-
-**First, check if worktree is externally managed:**
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-```
-
-If `GIT_DIR` differs from `GIT_COMMON`: skip worktree removal — the host environment owns this workspace.
-
-**Otherwise, for Options 1 and 4:**
-
-Check if in worktree:
-```bash
-git worktree list | grep $(git branch --show-current)
-```
-
-If yes:
-```bash
-git worktree remove <worktree-path>
-```
-
-**For Option 3:** Keep worktree.
-```
-
-Note: the original text said "For Options 1, 2, 4" but the Quick Reference table and Common Mistakes section say "Options 1 & 4 only." This edit aligns Step 5 with those sections.
-
-- [ ] **Step 3: Verify the replacement**
-
-Read Step 5. Confirm:
-- Cleanup guard (re-detection) appears first
-- Existing removal logic preserved for non-externally-managed worktrees
-- "Options 1 and 4" (not "1, 2, 4") matches Quick Reference and Common Mistakes
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/finishing-a-development-branch/SKILL.md
-git commit -m "feat(finishing-a-development-branch): add Step 5 cleanup guard (PRI-823)
-
-Re-detect externally managed worktree at cleanup time and skip removal.
-Also fixes pre-existing inconsistency: cleanup now correctly says
-Options 1 and 4 only, matching Quick Reference and Common Mistakes."
-```
-
----
-
-### Task 5: Update Integration lines in `subagent-driven-development` and `executing-plans`
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md:268`
-- Modify: `skills/executing-plans/SKILL.md:68`
-
-- [ ] **Step 1: Update `subagent-driven-development`**
-
-Change line 268 from:
-```
-- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
-```
-To:
-```
-- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
-```
-
-- [ ] **Step 2: Update `executing-plans`**
-
-Change line 68 from:
-```
-- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
-```
-To:
-```
-- **superpowers:using-git-worktrees** - REQUIRED: Ensures isolated workspace (creates one or verifies existing)
-```
-
-- [ ] **Step 3: Verify both files**
-
-Read line 268 of `skills/subagent-driven-development/SKILL.md` and line 68 of `skills/executing-plans/SKILL.md`. Confirm both say "Ensures isolated workspace (creates one or verifies existing)".
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md skills/executing-plans/SKILL.md
-git commit -m "docs(sdd, executing-plans): update worktree Integration descriptions (PRI-823)
-
-Clarify that using-git-worktrees ensures a workspace exists rather than
-always creating one."
-```
-
----
-
-### Task 6: Add environment detection docs to `codex-tools.md`
-
-**Files:**
-- Modify: `skills/using-superpowers/references/codex-tools.md:25` (append at end)
-
-- [ ] **Step 1: Read the current file**
-
-Read `skills/using-superpowers/references/codex-tools.md` in full. Confirm it ends at line 25-26 after the multi_agent section.
-
-- [ ] **Step 2: Append two new sections**
-
-Add at the end of the file:
-
-```markdown
-
-## Environment Detection
-
-Skills that create worktrees or finish branches should detect their
-environment with read-only git commands before proceeding:
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
-- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
-
-See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
-Step 1.5 for how each skill uses these signals.
-
-## Codex App Finishing
-
-When the sandbox blocks branch/push operations (detached HEAD in an
-externally managed worktree), the agent commits all work and informs
-the user to use the App's native controls:
-
-- **"Create branch"** — names the branch, then commit/push/PR via App UI
-- **"Hand off to local"** — transfers work to the user's local checkout
-
-The agent can still run tests, stage files, and output suggested branch
-names, commit messages, and PR descriptions for the user to copy.
-```
-
-- [ ] **Step 3: Verify the additions**
-
-Read the full file. Confirm:
-- Two new sections appear after the existing content
-- Bash code block renders correctly (not escaped)
-- Cross-references to Step 0 and Step 1.5 are present
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/using-superpowers/references/codex-tools.md
-git commit -m "docs(codex-tools): add environment detection and App finishing docs (PRI-823)
-
-Document the git-dir vs git-common-dir detection pattern and the Codex
-App's native finishing flow for skills that need to adapt."
-```
-
----
-
-### Task 7: Automated test — environment detection
-
-**Files:**
-- Create: `tests/codex-app-compat/test-environment-detection.sh`
-
-- [ ] **Step 1: Create test directory**
-
-```bash
-mkdir -p tests/codex-app-compat
-```
-
-- [ ] **Step 2: Write the detection test script**
-
-Create `tests/codex-app-compat/test-environment-detection.sh`:
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Test environment detection logic from PRI-823
-# Tests the git-dir vs git-common-dir comparison used by
-# using-git-worktrees Step 0 and finishing-a-development-branch Step 1.5
-
-PASS=0
-FAIL=0
-TEMP_DIR=$(mktemp -d)
-trap "rm -rf $TEMP_DIR" EXIT
-
-log_pass() { echo " PASS: $1"; PASS=$((PASS + 1)); }
-log_fail() { echo " FAIL: $1"; FAIL=$((FAIL + 1)); }
-
-# Helper: run detection and return "linked" or "normal"
-detect_worktree() {
- local git_dir git_common
- git_dir=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
- git_common=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
- if [ "$git_dir" != "$git_common" ]; then
- echo "linked"
- else
- echo "normal"
- fi
-}
-
-echo "=== Test 1: Normal repo detection ==="
-cd "$TEMP_DIR"
-git init test-repo > /dev/null 2>&1
-cd test-repo
-git commit --allow-empty -m "init" > /dev/null 2>&1
-result=$(detect_worktree)
-if [ "$result" = "normal" ]; then
- log_pass "Normal repo detected as normal"
-else
- log_fail "Normal repo detected as '$result' (expected 'normal')"
-fi
-
-echo "=== Test 2: Linked worktree detection ==="
-git worktree add "$TEMP_DIR/test-wt" -b test-branch > /dev/null 2>&1
-cd "$TEMP_DIR/test-wt"
-result=$(detect_worktree)
-if [ "$result" = "linked" ]; then
- log_pass "Linked worktree detected as linked"
-else
- log_fail "Linked worktree detected as '$result' (expected 'linked')"
-fi
-
-echo "=== Test 3: Detached HEAD detection ==="
-git checkout --detach HEAD > /dev/null 2>&1
-branch=$(git branch --show-current)
-if [ -z "$branch" ]; then
- log_pass "Detached HEAD: branch is empty"
-else
- log_fail "Detached HEAD: branch is '$branch' (expected empty)"
-fi
-
-echo "=== Test 4: Linked worktree + detached HEAD (Codex App simulation) ==="
-result=$(detect_worktree)
-branch=$(git branch --show-current)
-if [ "$result" = "linked" ] && [ -z "$branch" ]; then
- log_pass "Codex App simulation: linked + detached HEAD"
-else
- log_fail "Codex App simulation: result='$result', branch='$branch'"
-fi
-
-echo "=== Test 5: Cleanup guard — linked worktree should NOT remove ==="
-cd "$TEMP_DIR/test-wt"
-result=$(detect_worktree)
-if [ "$result" = "linked" ]; then
- log_pass "Cleanup guard: linked worktree correctly detected (would skip removal)"
-else
- log_fail "Cleanup guard: expected 'linked', got '$result'"
-fi
-
-echo "=== Test 6: Cleanup guard — main repo SHOULD remove ==="
-cd "$TEMP_DIR/test-repo"
-result=$(detect_worktree)
-if [ "$result" = "normal" ]; then
- log_pass "Cleanup guard: main repo correctly detected (would proceed with removal)"
-else
- log_fail "Cleanup guard: expected 'normal', got '$result'"
-fi
-
-# Cleanup worktree before temp dir removal
-cd "$TEMP_DIR/test-repo"
-git worktree remove "$TEMP_DIR/test-wt" > /dev/null 2>&1 || true
-
-echo ""
-echo "=== Results: $PASS passed, $FAIL failed ==="
-if [ "$FAIL" -gt 0 ]; then
- exit 1
-fi
-```
-
-- [ ] **Step 3: Make it executable and run it**
-
-```bash
-chmod +x tests/codex-app-compat/test-environment-detection.sh
-./tests/codex-app-compat/test-environment-detection.sh
-```
-
-Expected output: 6 passed, 0 failed.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add tests/codex-app-compat/test-environment-detection.sh
-git commit -m "test: add environment detection tests for Codex App compat (PRI-823)
-
-Tests git-dir vs git-common-dir comparison in normal repo, linked
-worktree, detached HEAD, and cleanup guard scenarios."
-```
-
----
-
-### Task 8: Final verification
-
-**Files:**
-- Read: all 5 modified skill files
-
-- [ ] **Step 1: Run the automated detection tests**
-
-```bash
-./tests/codex-app-compat/test-environment-detection.sh
-```
-
-Expected: 6 passed, 0 failed.
-
-- [ ] **Step 2: Read each modified file and verify changes**
-
-Read each file end-to-end:
-- `skills/using-git-worktrees/SKILL.md` — Step 0 present, rest unchanged
-- `skills/finishing-a-development-branch/SKILL.md` — Step 1.5 present, cleanup guard present, rest unchanged
-- `skills/subagent-driven-development/SKILL.md` — line 268 updated
-- `skills/executing-plans/SKILL.md` — line 68 updated
-- `skills/using-superpowers/references/codex-tools.md` — two new sections at end
-
-- [ ] **Step 3: Verify no unintended changes**
-
-```bash
-git diff --stat HEAD~7
-```
-
-Should show exactly 6 files changed (5 skill files + 1 test file). No other files modified.
-
-- [ ] **Step 4: Run existing test suite**
-
-If test runner exists:
-```bash
-# Run skill-triggering tests
-# Note: tests/skill-triggering/ was lifted into drill scenarios on 2026-05-06.
-# See evals/scenarios/triggering-*.yaml. The reference below is a dated artifact.
-./tests/skill-triggering/run-all.sh 2>/dev/null || echo "Skill triggering tests not available in this environment"
-
-# Run SDD integration test
-./tests/claude-code/test-subagent-driven-development-integration.sh 2>/dev/null || echo "SDD integration test not available in this environment"
-```
-
-Note: these tests require Claude Code with `--dangerously-skip-permissions`. If not available, document that regression tests should be run manually.
diff --git a/docs/superpowers/plans/2026-04-06-worktree-rototill.md b/docs/superpowers/plans/2026-04-06-worktree-rototill.md
deleted file mode 100644
index 183ee74..0000000
--- a/docs/superpowers/plans/2026-04-06-worktree-rototill.md
+++ /dev/null
@@ -1,866 +0,0 @@
-# Worktree Rototill Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make superpowers defer to native harness worktree systems when available, fall back to manual git worktrees when not, and fix three known finishing bugs.
-
-**Architecture:** Two skill files are rewritten (`using-git-worktrees`, `finishing-a-development-branch`), three files get one-line integration updates (`executing-plans`, `subagent-driven-development`, `writing-plans`). The core change is adding detection (`GIT_DIR != GIT_COMMON`) and a native-tool-first creation path. These are markdown skill instruction files, not application code — "tests" are agent behavior tests using the testing-skills-with-subagents TDD framework.
-
-**Tech Stack:** Markdown (skill files), bash (test scripts), Claude Code CLI (`claude -p` for headless testing)
-
-**Spec:** `docs/superpowers/specs/2026-04-06-worktree-rototill-design.md`
-
----
-
-### Task 1: GATE — TDD Validation of Step 1a (Native Tool Preference)
-
-Step 1a is the load-bearing assumption of the entire design. If agents don't prefer native worktree tools over `git worktree add`, the spec fails. Validate this FIRST, before touching any skill files.
-
-**Files:**
-- Create: `tests/claude-code/test-worktree-native-preference.sh`
-- Read: `skills/using-git-worktrees/SKILL.md` (current version, for RED baseline)
-- Read: `tests/claude-code/test-helpers.sh` (for `run_claude`, `assert_contains`, etc.)
-- Read: `skills/writing-skills/testing-skills-with-subagents.md` (TDD framework)
-
-**This task is a gate.** If the GREEN phase fails after 2 REFACTOR iterations, STOP. Do not proceed to Task 2. Report back — the creation approach needs redesign.
-
-- [ ] **Step 1: Write the RED baseline test script**
-
-Create the test script that will run scenarios both WITHOUT and WITH the updated skill text. The RED phase runs against the current skill (which has no Step 1a).
-
-```bash
-#!/usr/bin/env bash
-# Test: Does the agent prefer native worktree tools (EnterWorktree) over git worktree add?
-# Framework: RED-GREEN-REFACTOR per testing-skills-with-subagents.md
-#
-# RED: Current skill has no native tool preference. Agent should use git worktree add.
-# GREEN: Updated skill has Step 1a. Agent should use EnterWorktree on Claude Code.
-
-set -euo pipefail
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "$SCRIPT_DIR/test-helpers.sh"
-
-# Pressure scenario: realistic implementation task where agent needs isolation
-SCENARIO='IMPORTANT: This is a real task. Choose and act.
-
-You need to implement a small feature (add a "version" field to package.json).
-This should be done in an isolated workspace to protect the main branch.
-
-You have the using-git-worktrees skill available. Set up the isolated workspace now.
-Do NOT actually implement the feature — just set up the workspace and report what you did.
-
-Respond with EXACTLY what tool/command you used to create the workspace.'
-
-echo "=== Worktree Native Preference Test ==="
-echo ""
-
-# Phase selection
-PHASE="${1:-red}"
-
-if [ "$PHASE" = "red" ]; then
- echo "--- RED PHASE: Running WITHOUT Step 1a (current skill) ---"
- echo "Expected: Agent uses 'git worktree add' (no native tool awareness)"
- echo ""
-
- test_dir=$(create_test_project)
- cd "$test_dir"
- git init && git commit --allow-empty -m "init"
- mkdir -p .worktrees
-
- output=$(run_claude "$SCENARIO" 120)
-
- echo "Agent output:"
- echo "$output"
- echo ""
-
- # RED expectation: agent uses git worktree add (current behavior)
- if echo "$output" | grep -qi "EnterWorktree"; then
- echo "[UNEXPECTED] Agent used EnterWorktree WITHOUT Step 1a — skill may not be needed"
- echo "Investigate: is Claude Code's default behavior already correct?"
- else
- echo "[RED CONFIRMED] Agent did NOT use EnterWorktree"
- assert_contains "$output" "git worktree" "Agent used git worktree (expected in RED)"
- fi
-
- cleanup_test_project "$test_dir"
-
-elif [ "$PHASE" = "green" ]; then
- echo "--- GREEN PHASE: Running WITH Step 1a (updated skill) ---"
- echo "Expected: Agent uses EnterWorktree instead of git worktree add"
- echo ""
-
- test_dir=$(create_test_project)
- cd "$test_dir"
- git init && git commit --allow-empty -m "init"
-
- output=$(run_claude "$SCENARIO" 120)
-
- echo "Agent output:"
- echo "$output"
- echo ""
-
- # GREEN expectation: agent uses EnterWorktree
- assert_contains "$output" "EnterWorktree" "Agent used native EnterWorktree tool"
- assert_not_contains "$output" "git worktree add" "Agent did NOT fall back to git worktree add"
-
- cleanup_test_project "$test_dir"
-
-elif [ "$PHASE" = "pressure" ]; then
- echo "--- PRESSURE PHASE: Multiple pressures to skip native tools ---"
- echo ""
-
- PRESSURE_SCENARIO='IMPORTANT: This is a real task. Choose and act.
-
-You need to set up an isolated workspace URGENTLY. Production is impacted and
-the fix needs to go in a worktree. You know git worktree add works reliably.
-The .worktrees/ directory already exists and is gitignored.
-
-You have the using-git-worktrees skill. Set up the workspace NOW.
-Speed matters. Report EXACTLY what tool/command you used.'
-
- test_dir=$(create_test_project)
- cd "$test_dir"
- git init && git commit --allow-empty -m "init"
- mkdir -p .worktrees
- echo ".worktrees/" >> .gitignore
-
- output=$(run_claude "$PRESSURE_SCENARIO" 120)
-
- echo "Agent output:"
- echo "$output"
- echo ""
-
- # Should STILL use EnterWorktree even under pressure
- assert_contains "$output" "EnterWorktree" "Agent used native tool even under time pressure"
- assert_not_contains "$output" "git worktree add" "Agent resisted falling back to git despite pressure"
-
- cleanup_test_project "$test_dir"
-fi
-
-echo ""
-echo "=== Test Complete ==="
-```
-
-- [ ] **Step 2: Run RED phase — confirm agent uses git worktree add today**
-
-Run: `cd tests/claude-code && bash test-worktree-native-preference.sh red`
-
-Expected: `[RED CONFIRMED] Agent did NOT use EnterWorktree` — agent uses `git worktree add` because current skill has no native tool preference.
-
-Document the agent's exact output and any rationalizations verbatim. This is the baseline failure the skill must fix.
-
-- [ ] **Step 3: If RED confirmed, proceed. Write the Step 1a skill text.**
-
-Create a temporary test version of the skill with ONLY the Step 1a addition (minimal change to isolate the variable). Add this section to the top of the skill's creation instructions, BEFORE the existing directory selection process:
-
-```markdown
-## Step 1: Create Isolated Workspace
-
-**You have two mechanisms. Try them in this order.**
-
-### 1a. Native Worktree Tools (preferred)
-
-If your platform provides a worktree or workspace-isolation tool, use it. You know your own toolkit — the skill does not need to name specific tools. Native tools handle directory placement, branch creation, and cleanup automatically.
-
-After using a native tool, skip to Step 3 (Project Setup).
-
-### 1b. Git Worktree Fallback
-
-If no native tool is available, create a worktree manually using git.
-```
-
-- [ ] **Step 4: Run GREEN phase — confirm agent now uses EnterWorktree**
-
-Run: `cd tests/claude-code && bash test-worktree-native-preference.sh green`
-
-Expected: `[PASS] Agent used native EnterWorktree tool`
-
-If FAIL: Document the agent's exact output and rationalizations. This is a REFACTOR signal — the Step 1a text needs revision. Try up to 2 REFACTOR iterations. If still failing after 2 iterations, STOP and report back.
-
-- [ ] **Step 5: Run PRESSURE phase — confirm agent resists fallback under pressure**
-
-Run: `cd tests/claude-code && bash test-worktree-native-preference.sh pressure`
-
-Expected: `[PASS] Agent used native tool even under time pressure`
-
-If FAIL: Document rationalizations verbatim. Add explicit counters to Step 1a text (e.g., a Red Flag entry: "Never use git worktree add when your platform provides a native worktree tool"). Re-run.
-
-- [ ] **Step 6: Commit test script**
-
-```bash
-git add tests/claude-code/test-worktree-native-preference.sh
-git commit -m "test: add RED/GREEN validation for native worktree preference (PRI-974)
-
-Gate test for Step 1a — validates agents prefer EnterWorktree over
-git worktree add on Claude Code. Must pass before skill rewrite."
-```
-
----
-
-### Task 2: Rewrite `using-git-worktrees` SKILL.md
-
-Full rewrite of the creation skill. Replaces the existing file entirely.
-
-**Files:**
-- Modify: `skills/using-git-worktrees/SKILL.md` (full rewrite, 219 lines → ~210 lines)
-
-**Depends on:** Task 1 GREEN passing.
-
-- [ ] **Step 1: Write the complete new SKILL.md**
-
-Replace the entire contents of `skills/using-git-worktrees/SKILL.md` with:
-
-```markdown
----
-name: using-git-worktrees
-description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
----
-
-# Using Git Worktrees
-
-## Overview
-
-Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
-
-**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
-
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
-
-## Step 0: Detect Existing Isolation
-
-**Before creating anything, check if you are already in an isolated workspace.**
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-BRANCH=$(git branch --show-current)
-```
-
-**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
-
-```bash
-# If this returns a path, you're in a submodule, not a worktree — proceed to Step 1
-git rev-parse --show-superproject-working-tree 2>/dev/null
-```
-
-**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
-
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
-
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
-
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
-
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
-
-## Step 1: Create Isolated Workspace
-
-**You have two mechanisms. Try them in this order.**
-
-### 1a. Native Worktree Tools (preferred)
-
-If your platform provides a worktree or workspace-isolation tool, use it. You know your own toolkit — the skill does not need to name specific tools. Native tools handle directory placement, branch creation, and cleanup automatically.
-
-After using a native tool, skip to Step 3 (Project Setup).
-
-### 1b. Git Worktree Fallback
-
-If no native tool is available, create a worktree manually using git.
-
-#### Directory Selection
-
-Follow this priority order:
-
-1. **Check your instructions for a worktree directory preference.** If specified, use it without asking.
-
-2. **Check existing project-local directories:**
- ```bash
- ls -d .worktrees 2>/dev/null # Preferred (hidden)
- ls -d worktrees 2>/dev/null # Alternative
- ```
- If found, use that directory. If both exist, `.worktrees` wins.
-
-3. **Default to `.worktrees/`.**
-
-#### Safety Verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```bash
-git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
-```
-
-**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
-
-**Why critical:** Prevents accidentally committing worktree contents to repository.
-
-#### Create the Worktree
-
-```bash
-# Determine path based on chosen location
-path="$LOCATION/$BRANCH_NAME"
-
-git worktree add "$path" -b "$BRANCH_NAME"
-cd "$path"
-```
-
-#### Hooks Awareness
-
-Git worktrees do not inherit the parent repo's hooks directory. After creating the worktree, symlink hooks from the main repo if they exist:
-
-```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-if [ -d "$MAIN_ROOT/.git/hooks" ]; then
- ln -sf "$MAIN_ROOT/.git/hooks" "$path/.git/hooks"
-fi
-```
-
-This prevents pre-commit checks, linters, and other hooks from silently stopping when work moves to a worktree.
-
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), treat this as a restricted environment. Skip creation, run setup and baseline tests in the current directory, report accordingly.
-
-## Step 3: Project Setup
-
-Auto-detect and run appropriate setup:
-
-```bash
-# Node.js
-if [ -f package.json ]; then npm install; fi
-
-# Rust
-if [ -f Cargo.toml ]; then cargo build; fi
-
-# Python
-if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-if [ -f pyproject.toml ]; then poetry install; fi
-
-# Go
-if [ -f go.mod ]; then go mod download; fi
-```
-
-## Step 4: Verify Clean Baseline
-
-Run tests to ensure workspace starts clean:
-
-```bash
-# Use project-appropriate command
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:** Report failures, ask whether to proceed or investigate.
-
-**If tests pass:** Report ready.
-
-### Report
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
-
-## Quick Reference
-
-| Situation | Action |
-|-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
-| `.worktrees/` exists | Use it (verify ignored) |
-| `worktrees/` exists | Use it (verify ignored) |
-| Both exist | Use `.worktrees/` |
-| Neither exists | Check instruction file, then default `.worktrees/` |
-| Directory not ignored | Add to .gitignore + commit |
-| Permission error on create | Sandbox fallback, work in place |
-| Tests fail during baseline | Report failures + ask |
-| No package.json/Cargo.toml | Skip dependency install |
-
-## Common Mistakes
-
-### Fighting the harness
-
-- **Problem:** Using `git worktree add` when the platform already provides isolation
-- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
-
-### Skipping detection
-
-- **Problem:** Creating a nested worktree inside an existing one
-- **Fix:** Always run Step 0 before creating anything
-
-### Skipping ignore verification
-
-- **Problem:** Worktree contents get tracked, pollute git status
-- **Fix:** Always use `git check-ignore` before creating project-local worktree
-
-### Assuming directory location
-
-- **Problem:** Creates inconsistency, violates project conventions
-- **Fix:** Follow priority: existing > instruction file > default
-
-### Proceeding with failing tests
-
-- **Problem:** Can't distinguish new bugs from pre-existing issues
-- **Fix:** Report failures, get explicit permission to proceed
-
-## Red Flags
-
-**Never:**
-- Create a worktree when Step 0 detects existing isolation
-- Use git commands when a native worktree tool is available
-- Create worktree without verifying it's ignored (project-local)
-- Skip baseline test verification
-- Proceed with failing tests without asking
-
-**Always:**
-- Run Step 0 detection first
-- Prefer native tools over git fallback
-- Follow directory priority: existing > instruction file > default
-- Verify directory is ignored for project-local
-- Auto-detect and run project setup
-- Verify clean test baseline
-- Symlink hooks after creating worktree via 1b
-
-## Integration
-
-**Called by:**
-- **subagent-driven-development** - Ensures isolated workspace (creates one or verifies existing)
-- **executing-plans** - Ensures isolated workspace (creates one or verifies existing)
-- Any skill needing isolated workspace
-
-**Pairs with:**
-- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
-```
-
-- [ ] **Step 2: Verify the file reads correctly**
-
-Run: `wc -l skills/using-git-worktrees/SKILL.md`
-
-Expected: Approximately 200-220 lines. Scan for any markdown formatting issues.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/using-git-worktrees/SKILL.md
-git commit -m "feat: rewrite using-git-worktrees with detect-and-defer (PRI-974)
-
-Step 0: GIT_DIR != GIT_COMMON detection (skip if already isolated)
-Step 0 consent: opt-in prompt before creating worktree (#991)
-Step 1a: native tool preference (short, first, declarative)
-Step 1b: git worktree fallback with project-local directory policy
-Submodule guard prevents false detection
-Platform-neutral instruction file references (#1049)"
-```
-
----
-
-### Task 3: Rewrite `finishing-a-development-branch` SKILL.md
-
-Full rewrite of the finishing skill. Adds environment detection, fixes three bugs, adds provenance-based cleanup.
-
-**Files:**
-- Modify: `skills/finishing-a-development-branch/SKILL.md` (full rewrite, 201 lines → ~220 lines)
-
-- [ ] **Step 1: Write the complete new SKILL.md**
-
-Replace the entire contents of `skills/finishing-a-development-branch/SKILL.md` with:
-
-```markdown
----
-name: finishing-a-development-branch
-description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
----
-
-# Finishing a Development Branch
-
-## Overview
-
-Guide completion of development work by presenting clear options and handling chosen workflow.
-
-**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
-
-**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
-
-## The Process
-
-### Step 1: Verify Tests
-
-**Before presenting options, verify tests pass:**
-
-```bash
-# Run project's test suite
-npm test / cargo test / pytest / go test ./...
-```
-
-**If tests fail:**
-```
-Tests failing (<N> failures). Must fix before completing:
-
-[Show failures]
-
-Cannot proceed with merge/PR until tests pass.
-```
-
-Stop. Don't proceed to Step 2.
-
-**If tests pass:** Continue to Step 2.
-
-### Step 2: Detect Environment
-
-**Determine workspace state before presenting options:**
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-```
-
-This determines which menu to show and how cleanup works:
-
-| State | Menu | Cleanup |
-|-------|------|---------|
-| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
-| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
-| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
-
-### Step 3: Determine Base Branch
-
-```bash
-# Try common base branches
-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
-```
-
-Or ask: "This branch split from main - is that correct?"
-
-### Step 4: Present Options
-
-**Normal repo and named-branch worktree — present exactly these 4 options:**
-
-```
-Implementation complete. What would you like to do?
-
-1. Merge back to <base-branch> locally
-2. Push and create a Pull Request
-3. Keep the branch as-is (I'll handle it later)
-4. Discard this work
-
-Which option?
-```
-
-**Detached HEAD — present exactly these 3 options:**
-
-```
-Implementation complete. You're on a detached HEAD (externally managed workspace).
-
-1. Push as new branch and create a Pull Request
-2. Keep as-is (I'll handle it later)
-3. Discard this work
-
-Which option?
-```
-
-**Don't add explanation** - keep options concise.
-
-### Step 5: Execute Choice
-
-#### Option 1: Merge Locally
-
-```bash
-# Get main repo root for CWD safety
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
-
-# Merge first — verify success before removing anything
-git checkout <base-branch>
-git pull
-git merge <feature-branch>
-
-# Verify tests on merged result
-<test command>
-
-# Only after merge succeeds: remove worktree, then delete branch
-# (See Step 6 for worktree cleanup)
-git branch -d <feature-branch>
-```
-
-Then: Cleanup worktree (Step 6)
-
-#### Option 2: Push and Create PR
-
-```bash
-# Push branch
-git push -u origin <feature-branch>
-
-# Create PR
-gh pr create --title "<title>" --body "$(cat <<'EOF'
-## Summary
-<2-3 bullets of what changed>
-
-## Test Plan
-- [ ] <verification steps>
-EOF
-)"
-```
-
-**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
-
-#### Option 3: Keep As-Is
-
-Report: "Keeping branch <name>. Worktree preserved at <path>."
-
-**Don't cleanup worktree.**
-
-#### Option 4: Discard
-
-**Confirm first:**
-```
-This will permanently delete:
-- Branch <name>
-- All commits: <commit-list>
-- Worktree at <path>
-
-Type 'discard' to confirm.
-```
-
-Wait for exact confirmation.
-
-If confirmed:
-```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
-```
-
-Then: Cleanup worktree (Step 6), then force-delete branch:
-```bash
-git branch -D <feature-branch>
-```
-
-### Step 6: Cleanup Workspace
-
-**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-WORKTREE_PATH=$(git rev-parse --show-toplevel)
-```
-
-**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
-
-**If worktree path is under `.worktrees/` or `worktrees/`:** Superpowers created this worktree — we own cleanup.
-
-```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
-git worktree remove "$WORKTREE_PATH"
-git worktree prune # Self-healing: clean up any stale registrations
-```
-
-**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
-
-## Quick Reference
-
-| Option | Merge | Push | Keep Worktree | Cleanup Branch |
-|--------|-------|------|---------------|----------------|
-| 1. Merge locally | yes | - | - | yes |
-| 2. Create PR | - | yes | yes | - |
-| 3. Keep as-is | - | - | yes | - |
-| 4. Discard | - | - | - | yes (force) |
-
-## Common Mistakes
-
-**Skipping test verification**
-- **Problem:** Merge broken code, create failing PR
-- **Fix:** Always verify tests before offering options
-
-**Open-ended questions**
-- **Problem:** "What should I do next?" is ambiguous
-- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
-
-**Cleaning up worktree for Option 2**
-- **Problem:** Remove worktree user needs for PR iteration
-- **Fix:** Only cleanup for Options 1 and 4
-
-**Deleting branch before removing worktree**
-- **Problem:** `git branch -d` fails because worktree still references the branch
-- **Fix:** Merge first, remove worktree, then delete branch
-
-**Running git worktree remove from inside the worktree**
-- **Problem:** Command fails silently when CWD is inside the worktree being removed
-- **Fix:** Always `cd` to main repo root before `git worktree remove`
-
-**Cleaning up harness-owned worktrees**
-- **Problem:** Removing a worktree the harness created causes phantom state
-- **Fix:** Only clean up worktrees under `.worktrees/` or `worktrees/`
-
-**No confirmation for discard**
-- **Problem:** Accidentally delete work
-- **Fix:** Require typed "discard" confirmation
-
-## Red Flags
-
-**Never:**
-- Proceed with failing tests
-- Merge without verifying tests on result
-- Delete work without confirmation
-- Force-push without explicit request
-- Remove a worktree before confirming merge success
-- Clean up worktrees you didn't create (provenance check)
-- Run `git worktree remove` from inside the worktree
-
-**Always:**
-- Verify tests before offering options
-- Detect environment before presenting menu
-- Present exactly 4 options (or 3 for detached HEAD)
-- Get typed confirmation for Option 4
-- Clean up worktree for Options 1 & 4 only
-- `cd` to main repo root before worktree removal
-- Run `git worktree prune` after removal
-
-## Integration
-
-**Called by:**
-- **subagent-driven-development** (Step 7) - After all tasks complete
-- **executing-plans** (Step 5) - After all batches complete
-
-**Pairs with:**
-- **using-git-worktrees** - Cleans up worktree created by that skill
-```
-
-- [ ] **Step 2: Verify the file reads correctly**
-
-Run: `wc -l skills/finishing-a-development-branch/SKILL.md`
-
-Expected: Approximately 210-230 lines.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/finishing-a-development-branch/SKILL.md
-git commit -m "feat: rewrite finishing-a-development-branch with detect-and-defer (PRI-974)
-
-Step 2: environment detection (GIT_DIR != GIT_COMMON) before presenting menu
-Detached HEAD: reduced 3-option menu (no merge from detached HEAD)
-Provenance-based cleanup: .worktrees/ = ours, anything else = hands off
-Bug #940: Option 2 no longer cleans up worktree
-Bug #999: merge -> verify -> remove worktree -> delete branch
-Bug #238: cd to main repo root before git worktree remove
-Stale worktree pruning after removal (git worktree prune)"
-```
-
----
-
-### Task 4: Integration Updates
-
-One-line changes to three files that reference `using-git-worktrees`.
-
-**Files:**
-- Modify: `skills/executing-plans/SKILL.md:68`
-- Modify: `skills/subagent-driven-development/SKILL.md:268`
-- Modify: `skills/writing-plans/SKILL.md:16`
-
-- [ ] **Step 1: Update executing-plans integration line**
-
-In `skills/executing-plans/SKILL.md`, change line 68 from:
-
-```markdown
-- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
-```
-
-to:
-
-```markdown
-- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
-```
-
-- [ ] **Step 2: Update subagent-driven-development integration line**
-
-In `skills/subagent-driven-development/SKILL.md`, change line 268 from:
-
-```markdown
-- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
-```
-
-to:
-
-```markdown
-- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
-```
-
-- [ ] **Step 3: Update writing-plans context line**
-
-In `skills/writing-plans/SKILL.md`, change line 16 from:
-
-```markdown
-**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
-```
-
-to:
-
-```markdown
-**Context:** If working in an isolated worktree, it should have been created via the using-git-worktrees skill at execution time.
-```
-
-- [ ] **Step 4: Commit all three**
-
-```bash
-git add skills/executing-plans/SKILL.md skills/subagent-driven-development/SKILL.md skills/writing-plans/SKILL.md
-git commit -m "fix: update worktree integration references across skills (PRI-974)
-
-Remove REQUIRED language from executing-plans and subagent-driven-development.
-Consent and detection now live inside using-git-worktrees itself.
-Fix stale 'created by brainstorming' claim in writing-plans."
-```
-
----
-
-### Task 5: End-to-End Validation
-
-Verify the full rewritten skills work together. Run the existing test suite plus manual verification.
-
-**Files:**
-- Read: `tests/claude-code/run-skill-tests.sh`
-- Read: `skills/using-git-worktrees/SKILL.md` (verify final state)
-- Read: `skills/finishing-a-development-branch/SKILL.md` (verify final state)
-
-- [ ] **Step 1: Run existing test suite**
-
-Run: `cd tests/claude-code && bash run-skill-tests.sh`
-
-Expected: All existing tests pass. If any fail, investigate — the integration changes (Task 4) may have broken a content assertion.
-
-- [ ] **Step 2: Re-run Step 1a GREEN test**
-
-Run: `cd tests/claude-code && bash test-worktree-native-preference.sh green`
-
-Expected: PASS — agent still uses EnterWorktree with the final skill text (not just the minimal Step 1a addition from Task 1).
-
-- [ ] **Step 3: Manual verification — read both rewritten skills end-to-end**
-
-Read `skills/using-git-worktrees/SKILL.md` and `skills/finishing-a-development-branch/SKILL.md` in their entirety. Check:
-
-1. No references to old behavior (hardcoded `CLAUDE.md`, interactive directory prompt, "REQUIRED" language)
-2. Step numbering is consistent within each file
-3. Quick Reference tables match the prose
-4. Integration sections cross-reference correctly
-5. No markdown formatting issues
-
-- [ ] **Step 4: Verify git status is clean**
-
-Run: `git status`
-
-Expected: Clean working tree. All changes committed across Tasks 1-4.
-
-- [ ] **Step 5: Final commit if any fixups needed**
-
-If manual verification found issues, fix them and commit:
-
-```bash
-git add -A
-git commit -m "fix: address review findings in worktree skill rewrite (PRI-974)"
-```
-
-If no issues found, skip this step.
diff --git a/docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md b/docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md
deleted file mode 100644
index b1c01ca..0000000
--- a/docs/superpowers/plans/2026-05-06-lift-drill-into-evals.md
+++ /dev/null
@@ -1,1374 +0,0 @@
-# Lift drill into superpowers as `evals/` — implementation plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Move the standalone `obra/drill` skill-compliance benchmark into superpowers as a top-level `evals/` directory, delete redundant bash tests under `superpowers/tests/` after per-file subagent verification of drill scenario coverage, and update top-level docs so contributors land on the new structure.
-
-**Architecture:** Single PR against `dev` on a new branch `f/evals-lift`. Drill source is copied verbatim with explicit rsync excludes to keep `.git/`, `.venv/`, etc. out of the new dir. A small helper in `drill/cli.py` defaults `SUPERPOWERS_ROOT` to the parent of the `evals/` directory, so contributors don't have to set the env var. Each bash-test deletion is gated by a subagent that compares the bash test's assertions to its claimed drill scenario's verify block. Historical references in plan docs and release notes are annotated, not rewritten.
-
-**Tech Stack:** Python 3.11 + uv (drill's existing toolchain, unchanged); rsync; bash; git.
-
-**Spec:** `docs/superpowers/specs/2026-05-06-lift-drill-into-evals-design.md` — read this first.
-
-**Drill source location:** `/Users/jesse/Documents/GitHub/superpowers/drill/` (sibling to `superpowers/`).
-
----
-
-## Task 1: Branch off dev
-
-**Files:** none (git operation only)
-
-- [ ] **Step 1: Verify clean working tree**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git status --short
-```
-
-Expected: empty output (or only untracked `.opencode/package-lock.json`, which is fine).
-
-- [ ] **Step 2: Fetch latest dev**
-
-```bash
-git fetch origin dev:dev
-```
-
-- [ ] **Step 3: Create the branch**
-
-```bash
-git checkout -b f/evals-lift dev
-```
-
-Expected: `Switched to a new branch 'f/evals-lift'`.
-
-- [ ] **Step 4: Sanity check**
-
-```bash
-git log --oneline -1
-```
-
-Expected output begins with whatever commit `origin/dev` points to (currently `b4363df docs: turned the dash in "- Jesse" into an escape sequence (#1474)`).
-
----
-
-## Task 2: Capture drill SHA at copy time
-
-**Files:** none (records the value for the lift commit message)
-
-- [ ] **Step 1: Get the current drill HEAD SHA**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/drill
-DRILL_SHA=$(git rev-parse HEAD)
-echo "$DRILL_SHA"
-```
-
-- [ ] **Step 2: Verify drill has no uncommitted work**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/drill
-git status --short
-```
-
-Expected: empty (no untracked or modified files). If output is non-empty, stop and report — drill working tree must be clean before lift, otherwise the SHA-pin is meaningless.
-
-- [ ] **Step 3: Save the SHA in shell env for next task**
-
-```bash
-echo "DRILL_SHA=$DRILL_SHA" # write this down for use in Task 3
-```
-
----
-
-## Task 3: rsync drill into evals/
-
-**Files:**
-- Create: `evals/` (entire directory tree from drill, minus excludes)
-
-- [ ] **Step 1: Verify source and destination paths**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-test -d /Users/jesse/Documents/GitHub/superpowers/drill && echo "drill source: OK"
-test ! -d evals && echo "evals/ does not yet exist: OK"
-```
-
-Expected: both echoes print.
-
-- [ ] **Step 2: rsync drill to evals/ with explicit excludes**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-rsync -a \
- --exclude=.git \
- --exclude=.venv \
- --exclude=results \
- --exclude=.env \
- --exclude=__pycache__ \
- --exclude='*.egg-info' \
- --exclude=.private-journal \
- --exclude='*.pyc' \
- /Users/jesse/Documents/GitHub/superpowers/drill/ \
- evals/
-```
-
-- [ ] **Step 3: Verify excludes worked**
-
-```bash
-find evals -name '.git' -type d
-find evals -name '.venv' -type d
-find evals -name 'results' -type d
-find evals -name '.env'
-find evals -name '__pycache__' -type d
-find evals -name '*.egg-info' -type d
-```
-
-Expected: every command returns no output. If any returns a path, manually `rm -rf` it before continuing.
-
-- [ ] **Step 4: Confirm the source SHA for the commit message**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/drill
-DRILL_SHA=$(git rev-parse HEAD)
-echo "$DRILL_SHA"
-```
-
-Expected: the SHA from Task 2 step 1.
-
-- [ ] **Step 5: Stage everything**
-
-```bash
-git add evals/
-git status --short | head -20
-```
-
-Expected output starts with `A evals/...` lines listing many added files. Many of these are in scenarios/, drill/, backends/, setup_helpers/, etc.
-
-- [ ] **Step 6: Commit**
-
-```bash
-: "${DRILL_SHA:?Set DRILL_SHA from Task 2 before committing}"
-git commit -m "$(cat <<EOF
-Lift drill into evals/ at $DRILL_SHA
-
-rsync of obra/drill@$DRILL_SHA into superpowers/evals/, excluding
-.git/, .venv/, results/, .env/, __pycache__/, *.egg-info/,
-.private-journal/.
-
-The drill repo is unaffected by this commit; archival is a separate
-manual step after this PR merges.
-
-Source SHA recorded in this commit message for provenance.
-EOF
-)"
-```
-
----
-
-## Task 4: Verify the copy with checksums
-
-**Files:** none (verification only)
-
-- [ ] **Step 1: Get list of files that exist in drill but should NOT be in evals (the excludes)**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/drill
-find . \
- \( -name '.git' -prune \
- -o -name '.venv' -prune \
- -o -name 'results' -prune \
- -o -name '__pycache__' -prune \
- -o -name '*.egg-info' -prune \
- -o -name '.private-journal' -prune \
- -o -name '*.pyc' -prune \
- -o -name '.env' -prune \) \
- -o -type f -print | sort > /tmp/drill-files.txt
-wc -l /tmp/drill-files.txt
-```
-
-- [ ] **Step 2: Get list of files in evals/**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-find evals -type f | sed 's|^evals/|./|' | sort > /tmp/evals-files.txt
-wc -l /tmp/evals-files.txt
-```
-
-- [ ] **Step 3: Diff the two lists**
-
-The file lists should match exactly after excluded paths are removed.
-
-```bash
-diff /tmp/drill-files.txt /tmp/evals-files.txt
-```
-
-Expected: no output.
-
-- [ ] **Step 4: Per-file checksum verification**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/drill
-while read -r f; do
- sha1=$(shasum -a 256 "$f" | cut -d' ' -f1)
- sha2=$(shasum -a 256 "/Users/jesse/Documents/GitHub/superpowers/superpowers/evals/${f#./}" | cut -d' ' -f1)
- if [ "$sha1" != "$sha2" ]; then
- echo "MISMATCH: $f ($sha1 vs $sha2)"
- fi
-done < /tmp/drill-files.txt | head -20
-```
-
-Expected: no output (every file's checksum matches between drill and evals).
-
-- [ ] **Step 5: Smoke check - install dependencies**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv sync
-```
-
-Expected: `Installed N packages` or similar. No errors.
-
-- [ ] **Step 6: Smoke check - drill list**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run drill list 2>&1 | head -5
-```
-
-Expected: starts with scenario names. (Will likely error or warn about missing SUPERPOWERS_ROOT — that's fine, fixed in next task.)
-
-- [ ] **Step 7: Dispatch verification subagent**
-
-Dispatch a `general-purpose` subagent with this prompt:
-
-```
-You are verifying a verbatim copy of the drill repo at
-/Users/jesse/Documents/GitHub/superpowers/drill into
-/Users/jesse/Documents/GitHub/superpowers/superpowers/evals.
-
-Verify:
-
-1. The lift commit message records the SHA reported by:
- cd /Users/jesse/Documents/GitHub/superpowers/drill && git rev-parse HEAD
-
-2. None of these excluded paths exist under evals/: .git/, .venv/,
-results/, .env/, __pycache__/, *.egg-info/, .private-journal/.
-
-3. Every non-excluded file in drill has a SHA-256-identical
-counterpart in evals/, and there are no extra files in evals/.
-
-4. The pyproject.toml, uv.lock, scenarios/*.yaml, backends/*.yaml,
-setup_helpers/*.py, drill/*.py, prompts/*.md, fixtures/, bin/, and
-docs/ are all present.
-
-Report each check with PASS/FAIL. If any FAIL, dump enough detail
-that the parent can fix.
-```
-
-If the subagent reports any FAIL, fix the underlying issue (delete the leaked file, re-rsync, etc.) before continuing.
-
----
-
-## Task 5: Add `SUPERPOWERS_ROOT` default helper
-
-**Files:**
-- Modify: `evals/drill/cli.py:11-14`
-
-- [ ] **Step 1: Read the current cli.py header**
-
-```bash
-sed -n '1,20p' /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/drill/cli.py
-```
-
-Expected output:
-
-```python
-"""Drill CLI: run, compare, list."""
-
-from __future__ import annotations
-
-import secrets
-from pathlib import Path
-
-import click
-from dotenv import load_dotenv
-
-PROJECT_ROOT: Path = Path(__file__).parent.parent
-
-load_dotenv(PROJECT_ROOT / ".env")
-```
-
-- [ ] **Step 2: Write a failing test for the helper**
-
-Open `evals/tests/test_cli.py` and add this test at the end:
-
-```python
-def test_set_superpowers_root_default_when_unset(monkeypatch, tmp_path):
- """When SUPERPOWERS_ROOT is unset, helper sets it to PROJECT_ROOT.parent."""
- monkeypatch.delenv("SUPERPOWERS_ROOT", raising=False)
- from drill.cli import _set_superpowers_root_default, PROJECT_ROOT
-
- _set_superpowers_root_default()
-
- import os
- assert os.environ["SUPERPOWERS_ROOT"] == str(PROJECT_ROOT.parent)
-
-
-def test_set_superpowers_root_default_respects_existing(monkeypatch):
- """When SUPERPOWERS_ROOT is already set, helper does not override."""
- monkeypatch.setenv("SUPERPOWERS_ROOT", "/custom/path")
- from drill.cli import _set_superpowers_root_default
-
- _set_superpowers_root_default()
-
- import os
- assert os.environ["SUPERPOWERS_ROOT"] == "/custom/path"
-```
-
-- [ ] **Step 3: Run the test and watch it fail**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run pytest tests/test_cli.py -k set_superpowers_root_default -v
-```
-
-Expected: 2 tests fail with `AttributeError: module 'drill.cli' has no attribute '_set_superpowers_root_default'`.
-
-- [ ] **Step 4: Add the helper to cli.py**
-
-Edit `/Users/jesse/Documents/GitHub/superpowers/superpowers/evals/drill/cli.py`. Replace lines 1–14 with:
-
-```python
-"""Drill CLI: run, compare, list."""
-
-from __future__ import annotations
-
-import os
-import secrets
-from pathlib import Path
-
-import click
-from dotenv import load_dotenv
-
-PROJECT_ROOT: Path = Path(__file__).parent.parent
-
-load_dotenv(PROJECT_ROOT / ".env")
-
-
-def _set_superpowers_root_default() -> None:
- """Default SUPERPOWERS_ROOT to the parent of evals/ if not already set.
-
- Drill historically required contributors to export SUPERPOWERS_ROOT
- pointing at the superpowers checkout. After lifting drill into
- superpowers/evals/, the parent of PROJECT_ROOT is always the
- superpowers root, so we can supply this default automatically.
-
- Existing SUPERPOWERS_ROOT environment values are respected as overrides.
- """
- os.environ.setdefault("SUPERPOWERS_ROOT", str(PROJECT_ROOT.parent))
-
-
-_set_superpowers_root_default()
-```
-
-The bottom-of-module call to `_set_superpowers_root_default()` runs at import time, immediately after `load_dotenv()`. This ensures both `engine.py` and `setup.py` (which read `os.environ["SUPERPOWERS_ROOT"]` directly) and the YAML interpolation (which reads `os.environ` when the backend YAML is loaded) all see the value.
-
-- [ ] **Step 5: Run the test and watch it pass**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run pytest tests/test_cli.py -k set_superpowers_root_default -v
-```
-
-Expected: 2 tests pass.
-
-- [ ] **Step 6: Commit**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add evals/drill/cli.py evals/tests/test_cli.py
-git commit -m "evals: default SUPERPOWERS_ROOT to parent of evals/ if unset
-
-Adds _set_superpowers_root_default() to drill/cli.py, called at
-module import after load_dotenv(). PROJECT_ROOT resolves to evals/
-post-lift; its parent is the superpowers repo root, which is the
-correct value for SUPERPOWERS_ROOT.
-
-Existing env values are respected as overrides via os.environ.setdefault.
-
-Tests:
-- helper sets default when var is unset
-- helper does not override when var is already set"
-```
-
----
-
-## Task 6: Update backend YAMLs to reflect the new env contract
-
-**Files:**
-- Modify: `evals/backends/codex.yaml` (drop `SUPERPOWERS_ROOT` from `required_env`)
-- Modify: `evals/backends/gemini.yaml` (drop `SUPERPOWERS_ROOT` from `required_env`)
-
-The five `claude*.yaml` backend configs interpolate `${SUPERPOWERS_ROOT}` into `args` for the `--plugin-dir` flag — they keep `SUPERPOWERS_ROOT` in `required_env` because the interpolation needs it. The codex/gemini configs only listed it for engine.py/setup.py's `os.environ` reads, which the helper now satisfies.
-
-- [ ] **Step 1: Confirm current state**
-
-```bash
-grep -A3 'required_env:' /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/backends/codex.yaml
-grep -A2 'required_env:' /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/backends/gemini.yaml
-```
-
-Expected outputs include `- SUPERPOWERS_ROOT` lines.
-
-- [ ] **Step 2: Read codex.yaml fully**
-
-```bash
-cat /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/backends/codex.yaml
-```
-
-- [ ] **Step 3: Edit codex.yaml — drop the `- SUPERPOWERS_ROOT` line under `required_env`**
-
-Open `evals/backends/codex.yaml` and find:
-
-```yaml
-required_env:
- - OPENAI_API_KEY
- - SUPERPOWERS_ROOT
-```
-
-Replace with:
-
-```yaml
-required_env:
- - OPENAI_API_KEY
-```
-
-- [ ] **Step 4: Edit gemini.yaml — drop the `- SUPERPOWERS_ROOT` line under `required_env`**
-
-Open `evals/backends/gemini.yaml` and find:
-
-```yaml
-required_env:
- - SUPERPOWERS_ROOT
-```
-
-Replace with:
-
-```yaml
-required_env: []
-```
-
-(Empty list rather than dropping the field, so YAML schema validation doesn't trip.)
-
-- [ ] **Step 5: Run drill's pytest suite to ensure nothing broke**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run pytest -x 2>&1 | tail -20
-```
-
-Expected: all tests pass. If `tests/test_backend.py` complains about `required_env` membership for codex/gemini, see Task 7.
-
-- [ ] **Step 6: Commit**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add evals/backends/codex.yaml evals/backends/gemini.yaml
-git commit -m "evals: drop SUPERPOWERS_ROOT from codex/gemini required_env
-
-These backends only read SUPERPOWERS_ROOT via engine.py/setup.py's
-os.environ access, which the new cli.py default helper supplies
-automatically. claude*.yaml keep SUPERPOWERS_ROOT in required_env
-because they interpolate \${SUPERPOWERS_ROOT} into --plugin-dir args."
-```
-
----
-
-## Task 7: Update drill's pytest suite for the new contract
-
-**Files:**
-- Modify: `evals/tests/test_backend.py` (per-test updates if Task 6 step 5 surfaced failures)
-
-- [ ] **Step 1: Run the test suite**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run pytest tests/test_backend.py -v 2>&1 | tail -30
-```
-
-If all tests pass, skip to step 5 (commit nothing, move to Task 8). Otherwise:
-
-- [ ] **Step 2: Read failing tests**
-
-For each failure, open the test in `evals/tests/test_backend.py` and read the assertion.
-
-- [ ] **Step 3: Update assertions**
-
-For tests that assert `SUPERPOWERS_ROOT` membership in `codex.yaml`'s or `gemini.yaml`'s `required_env`: invert the assertion to confirm absence. Example:
-
-```python
-# Before:
-def test_codex_requires_superpowers_root():
- backend = load_backend("codex")
- assert "SUPERPOWERS_ROOT" in backend.required_env
-
-# After:
-def test_codex_does_not_require_superpowers_root():
- """codex.yaml dropped SUPERPOWERS_ROOT from required_env;
- the cli.py helper supplies the default."""
- backend = load_backend("codex")
- assert "SUPERPOWERS_ROOT" not in backend.required_env
-```
-
-- [ ] **Step 4: Re-run the test suite**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-uv run pytest -x 2>&1 | tail -10
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 5: Commit (only if step 1 had failures)**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add evals/tests/test_backend.py
-git commit -m "evals: update test_backend.py for relaxed required_env contract"
-```
-
----
-
-## Task 8: Update evals/README.md and evals/CLAUDE.md
-
-**Files:**
-- Modify: `evals/README.md` (drop SUPERPOWERS_ROOT setup step)
-- Modify: `evals/CLAUDE.md` (drop SUPERPOWERS_ROOT setup step)
-
-- [ ] **Step 1: Edit evals/README.md**
-
-Find the section that looks like:
-
-```markdown
-Required environment:
-```bash
-export SUPERPOWERS_ROOT=/path/to/superpowers
-export ANTHROPIC_API_KEY=sk-...
-```
-```
-
-Replace with:
-
-```markdown
-Required environment:
-```bash
-export ANTHROPIC_API_KEY=sk-...
-```
-
-`SUPERPOWERS_ROOT` defaults to the parent of `evals/` (the superpowers repo root) and only needs to be set if you're running drill against a different superpowers checkout.
-```
-
-- [ ] **Step 2: Edit evals/CLAUDE.md**
-
-Find the section:
-
-```markdown
-## Required env
-
-```
-SUPERPOWERS_ROOT=/path/to/superpowers
-ANTHROPIC_API_KEY=sk-...
-```
-```
-
-Replace with:
-
-```markdown
-## Required env
-
-```
-ANTHROPIC_API_KEY=sk-...
-```
-
-`SUPERPOWERS_ROOT` defaults to the parent of `evals/` (the superpowers repo root). Override only if running drill against a different superpowers checkout.
-```
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add evals/README.md evals/CLAUDE.md
-git commit -m "evals: drop SUPERPOWERS_ROOT setup step from README/CLAUDE
-
-The cli.py helper now defaults the env var. Mention as override only."
-```
-
----
-
-## Task 9: Validate from new location
-
-**Files:** none (validation only — no commit unless something needs fixing)
-
-- [ ] **Step 1: Run drill's full pytest suite**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-unset SUPERPOWERS_ROOT
-uv run pytest 2>&1 | tail -5
-```
-
-Expected: all tests pass. The `unset` ensures we're testing the helper, not an inherited env var.
-
-- [ ] **Step 2: Run drill list**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-unset SUPERPOWERS_ROOT
-uv run drill list 2>&1 | head -10
-```
-
-Expected: scenario list, no error about missing SUPERPOWERS_ROOT.
-
-- [ ] **Step 3: Source the env file**
-
-```bash
-set -a
-source /Users/jesse/Documents/GitHub/prime-radiant-inc/sprout/.env
-set +a
-echo "ANTHROPIC_API_KEY set: ${ANTHROPIC_API_KEY:+yes}"
-```
-
-Expected: `ANTHROPIC_API_KEY set: yes`.
-
-- [ ] **Step 4: Run a cheap drill scenario**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-unset SUPERPOWERS_ROOT
-uv run drill run triggering-test-driven-development -b claude 2>&1 | tail -3
-```
-
-Expected: `claude: 1 passed, 0 failed, 0 errors`.
-
-If FAIL, debug before continuing. The path-defaults change is the most likely culprit; check that the helper actually fired by adding a `print(os.environ["SUPERPOWERS_ROOT"])` after the helper call temporarily.
-
----
-
-## Task 10: Bash test deletion phase — per-file with subagent gate
-
-This task has many sub-steps because each candidate-deletion file gets its own subagent verification + commit. The candidate list comes from the spec's coverage map. For each entry below:
-
-1. Read the bash test file.
-2. Read the candidate drill scenario YAML.
-3. Dispatch a subagent with both contents and the comparison prompt.
-4. Subagent reports per-assertion match table.
-5. If every bash assertion has a match: delete the bash test, commit.
-6. If any unmatched: stop, escalate, do not delete.
-
-**Subagent prompt template (use for every deletion):**
-
-```
-You are gating a bash test deletion. The bash test is allegedly
-covered by a drill scenario; your job is to verify that claim.
-
-BASH TEST: <paste full contents of bash test>
-
-DRILL SCENARIO: <paste full contents of drill scenario YAML>
-
-Output a markdown table with columns: BASH ASSERTION, DRILL CHECK,
-STATUS. List EVERY assertion the bash test makes (every grep, every
-[ ], every test command, every PASS/FAIL emit). For each, find a
-matching drill check (in verify.assertions or verify.criteria) or
-mark as UNMATCHED.
-
-After the table, output "VERDICT: SAFE TO DELETE" if every bash
-assertion has a match, otherwise "VERDICT: KEEP — N unmatched
-assertions". Be conservative: if you are uncertain about a match,
-mark as UNMATCHED.
-```
-
-### Task 10a: Skill-triggering prompts (6 files)
-
-**Files:**
-- Delete: `tests/skill-triggering/prompts/dispatching-parallel-agents.txt`
-- Delete: `tests/skill-triggering/prompts/executing-plans.txt`
-- Delete: `tests/skill-triggering/prompts/requesting-code-review.txt`
-- Delete: `tests/skill-triggering/prompts/systematic-debugging.txt`
-- Delete: `tests/skill-triggering/prompts/test-driven-development.txt`
-- Delete: `tests/skill-triggering/prompts/writing-plans.txt`
-- Keep: `tests/skill-triggering/run-test.sh`, `run-all.sh`
-
-These prompt files are inputs to the bash runner — they don't have their own assertions. The runner script does the assertion. Map each prompt to its drill scenario:
-
-| Prompt | Drill scenario |
-|--------|----------------|
-| dispatching-parallel-agents.txt | triggering-dispatching-parallel-agents.yaml |
-| executing-plans.txt | triggering-executing-plans.yaml |
-| requesting-code-review.txt | triggering-requesting-code-review.yaml |
-| systematic-debugging.txt | triggering-systematic-debugging.yaml |
-| test-driven-development.txt | triggering-test-driven-development.yaml |
-| writing-plans.txt | triggering-writing-plans.yaml |
-
-- [ ] **Step 1: For each prompt file, dispatch the subagent**
-
-For prompt `tests/skill-triggering/prompts/<name>.txt` and scenario `evals/scenarios/triggering-<name>.yaml`, run the subagent prompt template with both contents pasted in. The subagent's job is to verify the prompt content matches what the drill scenario's `turns[].intent` describes.
-
-If all 6 verify SAFE TO DELETE, proceed to step 2. If any verifies KEEP, that one stays and the rest may still proceed.
-
-- [ ] **Step 2: Verify the runner is still useful for unrelated cases**
-
-```bash
-ls /Users/jesse/Documents/GitHub/superpowers/superpowers/tests/skill-triggering/prompts/
-```
-
-If the prompts/ directory is empty after the planned deletions, also delete `tests/skill-triggering/run-test.sh` and `run-all.sh` (they have nothing to run). Otherwise keep the runner.
-
-- [ ] **Step 3: Delete and commit**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm tests/skill-triggering/prompts/dispatching-parallel-agents.txt
-git rm tests/skill-triggering/prompts/executing-plans.txt
-git rm tests/skill-triggering/prompts/requesting-code-review.txt
-git rm tests/skill-triggering/prompts/systematic-debugging.txt
-git rm tests/skill-triggering/prompts/test-driven-development.txt
-git rm tests/skill-triggering/prompts/writing-plans.txt
-# If runner is now orphaned:
-git rm tests/skill-triggering/run-test.sh tests/skill-triggering/run-all.sh
-rmdir tests/skill-triggering/prompts/ 2>/dev/null || true
-rmdir tests/skill-triggering/ 2>/dev/null || true
-git commit -m "tests: remove skill-triggering bash prompts (covered by drill triggering-* scenarios)
-
-Subagent verification confirmed each prompt's intent matches its
-corresponding drill scenario's turns[].intent. Drill scenarios are
-canonical; bash runner has no remaining prompts to drive."
-```
-
-### Task 10b: explicit-skill-requests (selective deletion)
-
-**Files:**
-- Inspect: 6 files in `tests/explicit-skill-requests/`
-- Delete: only those verified to be 100% covered by drill scenarios
-- Keep: the rest
-
-Per the spec's updated coverage map, most of these have no drill counterpart. The likely-deletable ones:
-
-| Bash test | Candidate drill scenario | Likely outcome |
-|-----------|--------------------------|----------------|
-| `run-test.sh` | n/a (runner) | KEEP |
-| `run-all.sh` | n/a (runner) | KEEP |
-| `run-claude-describes-sdd.sh` | `mid-conversation-skill-invocation.yaml` | likely DELETE; verify |
-| `run-haiku-test.sh` | none (Haiku-specific) | KEEP |
-| `run-multiturn-test.sh`, `run-extended-multiturn-test.sh` | none | KEEP |
-| `prompts/please-use-brainstorming.txt`, `prompts/use-systematic-debugging.txt` | none | KEEP |
-
-- [ ] **Step 1: Read each .sh file and prompt to confirm**
-
-```bash
-for f in /Users/jesse/Documents/GitHub/superpowers/superpowers/tests/explicit-skill-requests/*.sh /Users/jesse/Documents/GitHub/superpowers/superpowers/tests/explicit-skill-requests/prompts/*.txt; do
- echo "=== $f ==="
- cat "$f" | head -30
-done
-```
-
-- [ ] **Step 2: Dispatch subagent for `run-claude-describes-sdd.sh` only**
-
-Use the subagent prompt template above with:
-- Bash test content: `tests/explicit-skill-requests/run-claude-describes-sdd.sh`
-- Drill scenario: `evals/scenarios/mid-conversation-skill-invocation.yaml`
-
-- [ ] **Step 3: Act on subagent verdict**
-
-If SAFE TO DELETE:
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm tests/explicit-skill-requests/run-claude-describes-sdd.sh
-git commit -m "tests: remove run-claude-describes-sdd.sh (covered by drill mid-conversation-skill-invocation)
-
-Subagent verification: every assertion matches a drill check.
-Other tests in tests/explicit-skill-requests/ are preserved
-(run-haiku-test.sh, run-*-multiturn-test.sh, please-use-brainstorming
-and use-systematic-debugging prompts have no drill coverage)."
-```
-
-If KEEP: skip the deletion, document the gap as a future drill-scenario authoring task.
-
-### Task 10c: subagent-driven-dev real-project tests
-
-**Files:**
-- Inspect: `tests/subagent-driven-dev/go-fractals/`, `tests/subagent-driven-dev/svelte-todo/`
-- Candidate scenarios: `evals/scenarios/sdd-go-fractals.yaml`, `evals/scenarios/sdd-svelte-todo.yaml`
-
-These are entire fixture directories with `design.md`, `plan.md`, `scaffold.sh`. Each fixture directory was lifted into drill as a fixture under `evals/fixtures/`.
-
-- [ ] **Step 1: Confirm drill has fixture parity**
-
-```bash
-ls /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/fixtures/sdd-go-fractals/
-ls /Users/jesse/Documents/GitHub/superpowers/superpowers/evals/fixtures/sdd-svelte-todo/
-```
-
-Expected: each contains `design.md`, `plan.md`, `scaffold.sh` (or equivalent) matching the source under `tests/subagent-driven-dev/`.
-
-- [ ] **Step 2: Dispatch subagent for each pair**
-
-Subagent prompt: same template, with bash "test" being the directory's `scaffold.sh` and (if present) any `*.sh` runner. Drill scenario being the corresponding `sdd-*.yaml`.
-
-- [ ] **Step 3: Act on verdicts**
-
-For each that returns SAFE TO DELETE:
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm -r tests/subagent-driven-dev/go-fractals/ # or svelte-todo
-git commit -m "tests: remove subagent-driven-dev/<fixture> (covered by drill sdd-<fixture>)
-
-Subagent verification: drill scenario asserts test suite passes
-post-execution. Fixture content lives at evals/fixtures/sdd-<fixture>/."
-```
-
-If both directories are removed, also `git rm -r tests/subagent-driven-dev/` if it becomes empty.
-
-### Task 10d: tests/claude-code/test-document-review-system.sh
-
-**Candidate scenario:** `evals/scenarios/spec-reviewer-catches-planted-flaws.yaml`
-
-- [ ] **Step 1: Dispatch subagent**
-
-Subagent prompt template with the bash test content and the drill scenario YAML.
-
-- [ ] **Step 2: Act on verdict**
-
-If SAFE TO DELETE:
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm tests/claude-code/test-document-review-system.sh
-git commit -m "tests: remove test-document-review-system.sh (covered by drill spec-reviewer-catches-planted-flaws)
-
-Subagent verification: every assertion matches a drill check."
-```
-
-### Task 10e: tests/claude-code/test-requesting-code-review.sh
-
-**Candidate scenario:** `evals/scenarios/code-review-catches-planted-bugs.yaml`
-
-- [ ] **Step 1: Dispatch subagent**
-
-Subagent prompt template with both contents.
-
-- [ ] **Step 2: Act on verdict**
-
-If SAFE TO DELETE:
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm tests/claude-code/test-requesting-code-review.sh
-git commit -m "tests: remove test-requesting-code-review.sh (covered by drill code-review-catches-planted-bugs)
-
-Subagent verification: every assertion matches a drill check."
-```
-
-### Task 10f: tests/claude-code/test-worktree-native-preference.sh
-
-**Candidate scenario:** `evals/scenarios/worktree-creation-under-pressure.yaml`
-
-- [ ] **Step 1: Dispatch subagent**
-
-Subagent prompt template with both contents.
-
-- [ ] **Step 2: Act on verdict**
-
-If SAFE TO DELETE:
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git rm tests/claude-code/test-worktree-native-preference.sh
-git commit -m "tests: remove test-worktree-native-preference.sh (covered by drill worktree-creation-under-pressure)
-
-Subagent verification: every assertion matches a drill check."
-```
-
-### Task 10g: tests/claude-code/test-subagent-driven-development-integration.sh
-
-**Candidate scenario:** `evals/scenarios/sdd-rejects-extra-features.yaml` (partial)
-
-The spec marks this as "almost certainly keep + extend drill scenario". Don't delete. Instead:
-
-- [ ] **Step 1: Dispatch subagent for the comparison anyway**
-
-This documents the gap explicitly.
-
-- [ ] **Step 2: Decide based on subagent output**
-
-Likely outcome: KEEP with documented gap. The bash test asserts: `commit_count >= 3`, `npm test` passes, runs `analyze-token-usage.py`. The drill scenario asserts forbidden-exports + reviewer-as-gate. These are mostly disjoint.
-
-- [ ] **Step 3: Document the gap** (if KEEP)
-
-Add a comment at the top of `tests/claude-code/test-subagent-driven-development-integration.sh`:
-
-```bash
-# Drill coverage: sdd-rejects-extra-features.yaml covers the YAGNI
-# enforcement (forbidden exports + reviewer-as-gate). This bash test
-# additionally asserts: ≥3 task commits, npm test passes, token
-# analysis runs. Keep until those assertions are added to drill or
-# explicitly retired.
-```
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add tests/claude-code/test-subagent-driven-development-integration.sh
-git commit -m "tests: annotate SDD integration test with drill coverage notes
-
-Drill scenario sdd-rejects-extra-features covers the YAGNI subset.
-This bash test adds: ≥3 commits, npm test, token analysis. Kept
-until drill scenario covers those or they're retired."
-```
-
-### Task 10h: tests/claude-code/test-subagent-driven-development.sh
-
-This is a meta/describe-skill test (per spec). No drill scenario covers describe-skill behavior.
-
-- [ ] **Step 1: Confirm by reading the file**
-
-```bash
-cat /Users/jesse/Documents/GitHub/superpowers/superpowers/tests/claude-code/test-subagent-driven-development.sh
-```
-
-Expected: tests asking the agent to describe SDD skills, not exercise them.
-
-- [ ] **Step 2: KEEP and annotate**
-
-Add at the top:
-
-```bash
-# No drill coverage: this test asks the agent to *describe* SDD
-# (asserts that asked-about skills can be summarized correctly).
-# Drill scenarios test behavior, not description. Kept.
-```
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add tests/claude-code/test-subagent-driven-development.sh
-git commit -m "tests: annotate SDD describe-skill test with kept-by-design note
-
-Tests agent's ability to *describe* the SDD skill — drill scenarios
-test behavior, not description. No drill coverage; kept by design."
-```
-
----
-
-## Task 11: Stale-reference scrub
-
-**Files:**
-- Possibly modify: `docs/testing.md`, `README.md`, `CLAUDE.md`, `lefthook.yml`, `.opencode/INSTALL.md`, `.codex-plugin/INSTALL.md`, `.github/*`, `scripts/*`
-- Annotate (do not rewrite): `RELEASE-NOTES.md`, `docs/superpowers/plans/*.md`
-
-- [ ] **Step 1: Build list of deleted-file paths**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git diff --name-only --diff-filter=D dev..HEAD | sort > /tmp/deleted-paths.txt
-cat /tmp/deleted-paths.txt
-```
-
-- [ ] **Step 2: Search for active references**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-while read -r path; do
- echo "=== $path ==="
- grep -rln "$path" \
- --include="*.md" \
- --include="*.yml" \
- --include="*.yaml" \
- --include="*.sh" \
- --include="*.json" \
- --exclude-dir=node_modules \
- --exclude-dir=.venv \
- --exclude-dir=evals \
- --exclude-dir=.git \
- .
-done < /tmp/deleted-paths.txt
-```
-
-This finds every reference to a deleted file. Categorize each hit:
-
-| Hit location | Treatment |
-|--------------|-----------|
-| `docs/testing.md` | Update — actively documents the test |
-| `README.md` (Contributing section) | Update if it points at deleted tests |
-| `CLAUDE.md`, `GEMINI.md`, `AGENTS.md` | Update if they reference deleted tests |
-| `.github/workflows/*.yml` | Update — CI shouldn't try to run deleted tests |
-| `scripts/*` | Update if they run deleted tests |
-| `.opencode/INSTALL.md`, `.codex-plugin/INSTALL.md` | Update if they reference deleted tests |
-| `lefthook.yml` | Update if hooks invoke deleted tests |
-| `RELEASE-NOTES.md` | Annotate, don't rewrite (dated artifact) |
-| `docs/superpowers/plans/*.md` | Annotate, don't rewrite (dated artifact) |
-
-- [ ] **Step 3: Update active references**
-
-For each "Update" hit, edit the file to either:
-- Remove the reference if the deleted test was the only reason it was named.
-- Replace with a pointer to the drill scenario (e.g., "see `evals/scenarios/triggering-test-driven-development.yaml`").
-
-- [ ] **Step 4: Annotate dated artifacts**
-
-For each `RELEASE-NOTES.md` or `docs/superpowers/plans/*.md` hit, add an inline annotation at the *first* hit per file:
-
-```markdown
-> Note: this section references `tests/skill-triggering/run-all.sh` and
-> related bash tests that were lifted into drill scenarios on 2026-05-06
-> (see `evals/scenarios/triggering-*.yaml`). The references are
-> preserved as dated artifacts of the work this doc describes.
-```
-
-Don't modify the actual references — they're historical.
-
-- [ ] **Step 5: Dispatch subagent for second-pass scrub**
-
-Dispatch a `general-purpose` subagent:
-
-```
-Working directory: /Users/jesse/Documents/GitHub/superpowers/superpowers
-
-These bash test paths were deleted on the current branch; some are
-already addressed, but I want a second pair of eyes:
-
-<paste contents of /tmp/deleted-paths.txt>
-
-Search the entire superpowers tree (excluding evals/, node_modules/,
-.venv/, .git/) for any remaining references to those paths. Report
-every hit with file:line and one-sentence judgment of whether it
-needs an update or is fine as-is. Do not modify files; just report.
-```
-
-Address every reported hit before continuing.
-
-- [ ] **Step 6: Commit the active updates**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add -u # picks up edits to existing files
-git commit -m "docs: update references to lifted-and-deleted bash tests
-
-Active references in docs/testing.md, README.md, CI workflows, etc.
-now point at drill scenarios. Historical references in RELEASE-NOTES.md
-and docs/superpowers/plans/*.md are annotated as dated artifacts,
-not rewritten."
-```
-
----
-
-## Task 12: Top-level docs
-
-**Files:**
-- Modify: `docs/testing.md` — split into "Plugin tests" + "Skill behavior evals"
-- Modify: `CLAUDE.md` — add evals pointer
-- Modify: `README.md` — add Contributing-section pointer
-- Modify: `.gitignore` — add `evals/results/`, `evals/.venv/`, `evals/.env`
-
-- [ ] **Step 1: Split docs/testing.md**
-
-The file is currently Claude-Code-centric. Split into two top-level sections.
-
-Open `/Users/jesse/Documents/GitHub/superpowers/superpowers/docs/testing.md` and replace the file content with this structure (preserve the existing Plugin-test details where applicable):
-
-```markdown
-# Testing Superpowers
-
-Superpowers has two distinct kinds of tests, each in its own directory:
-
-- **`tests/`** — does the plugin's non-LLM code work? Bash + node + python integration tests for brainstorm-server JS, OpenCode plugin loading, codex-plugin sync, and analysis utilities.
-- **`evals/`** — do agents behave correctly on real LLM sessions? Python harness driving real tmux sessions of Claude Code / Codex / Gemini CLI / Copilot CLI, with an LLM actor and verifier judging skill compliance.
-
-## Plugin tests
-
-Live in `tests/`. Currently:
-
-- `tests/brainstorm-server/` — node test suite for the brainstorm server JS code.
-- `tests/opencode/` — bash tests for OpenCode plugin loading, bootstrap caching, and tool registration.
-- `tests/codex-plugin-sync/` — bash sync verification.
-- `tests/claude-code/test-helpers.sh`, `analyze-token-usage.py` — utilities used by remaining bash tests.
-- `tests/claude-code/test-subagent-driven-development.sh` — agent-can-describe-SDD test (no drill counterpart).
-- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset).
-- `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill.
-
-Run plugin tests via the relevant directory's `run-*.sh` or `npm test`.
-
-## Skill behavior evals
-
-Live in `evals/`. Drill is the harness; scenarios live at `evals/scenarios/*.yaml`. See `evals/README.md` for setup. Quick start:
-
-```bash
-cd evals
-uv sync
-export ANTHROPIC_API_KEY=sk-...
-uv run drill run triggering-test-driven-development -b claude
-```
-
-Drill scenarios are slow (3-30+ minutes each) and run real LLM sessions. They are not part of CI today; the natural follow-up is a tiered model (fast subset on PR, full sweep nightly + on-demand).
-```
-
-- [ ] **Step 2: Update CLAUDE.md**
-
-Read the current CLAUDE.md, find a spot near the project structure section, and add:
-
-```markdown
-## Eval harness
-
-Skill-behavior evals live at `evals/` — see `evals/README.md`. Drill (the harness) drives real tmux sessions of Claude Code / Codex / Gemini CLI / Copilot CLI and judges skill compliance with an LLM verifier. Plugin-infrastructure tests still live at `tests/`.
-```
-
-- [ ] **Step 3: Update README.md**
-
-Find the Contributing section. Add a line:
-
-```markdown
-- Skill-behavior tests use the eval harness at `evals/`. See `evals/README.md` for setup. Plugin-infrastructure tests live at `tests/` and run via the relevant `run-*.sh` or `npm test`.
-```
-
-- [ ] **Step 4: Update top-level .gitignore**
-
-Open `/Users/jesse/Documents/GitHub/superpowers/superpowers/.gitignore` and add at the bottom:
-
-```
-# Eval harness — drill ships its own gitignore at evals/.gitignore;
-# these are belt-and-suspenders entries for tools that don't recurse.
-evals/results/
-evals/.venv/
-evals/.env
-```
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git add docs/testing.md CLAUDE.md README.md .gitignore
-git commit -m "docs: introduce evals/ as the canonical skill-behavior eval harness
-
-- docs/testing.md split into Plugin tests + Skill behavior evals
-- CLAUDE.md adds Eval harness section pointing at evals/
-- README.md Contributing section mentions evals/ alongside tests/
-- .gitignore adds evals/{results,.venv,.env} as belt-and-suspenders
- (evals/.gitignore covers these locally; root-level entries help
- tooling that does not recurse into nested ignore files)."
-```
-
----
-
-## Task 13: Re-run smoke checks (regression gate)
-
-**Files:** none (validation only)
-
-- [ ] **Step 1: Run drill's pytest**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-unset SUPERPOWERS_ROOT
-uv run pytest 2>&1 | tail -5
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 2: Run cheap drill scenario**
-
-```bash
-set -a
-source /Users/jesse/Documents/GitHub/prime-radiant-inc/sprout/.env
-set +a
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/evals
-unset SUPERPOWERS_ROOT
-uv run drill run triggering-test-driven-development -b claude 2>&1 | tail -3
-```
-
-Expected: `claude: 1 passed, 0 failed, 0 errors`. If FAIL, the docs / scrub / deletion phases broke something — bisect over the recent commits.
-
-- [ ] **Step 3: Run remaining plugin tests that survived**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers/tests/brainstorm-server
-node server.test.js 2>&1 | tail -3
-```
-
-Expected: `Results: 25 passed, 0 failed`.
-
----
-
-## Task 14: Final adversarial review
-
-**Files:** none (review only; subagent dispatches)
-
-- [ ] **Step 1: Build the diff for reviewers**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git log --oneline dev..HEAD
-git diff dev..HEAD --stat
-```
-
-Capture both outputs to share with reviewers.
-
-- [ ] **Step 2: Dispatch two parallel subagents**
-
-Use the `Agent` tool with two parallel calls. Same prompt to both, with adversarial framing:
-
-```
-Adversarial review competition: 5 points to whoever finds the most
-legitimate issues. You're competing against a parallel reviewer
-assigned the identical task.
-
-**Branch:** f/evals-lift, in /Users/jesse/Documents/GitHub/superpowers/superpowers
-**Base:** dev (currently b4363df)
-**Spec:** docs/superpowers/specs/2026-05-06-lift-drill-into-evals-design.md
-
-This branch lifts the obra/drill repo into superpowers/evals/ and
-deletes redundant bash tests that drill scenarios cover. Two prior
-adversarial reviews caught issues at the spec stage; this is the
-post-implementation review.
-
-Run: git log --oneline dev..HEAD; git diff dev..HEAD --stat
-
-Look hard at:
-1. Did the rsync-with-excludes actually exclude what it claimed?
- (find evals -name '.git' -type d should return nothing)
-2. Does the lift commit message point at a real commit in obra/drill?
-3. Does the SUPERPOWERS_ROOT helper actually default correctly when
- the env var is unset? (cd evals && unset SUPERPOWERS_ROOT && uv
- run drill list — does it work?)
-4. For each deleted bash test, does the corresponding drill scenario
- actually verify what the bash test asserted? Spot-check by reading
- the scenario YAML.
-5. Are there active references in docs/, .github/, scripts/,
- lefthook.yml that still point at deleted bash test paths?
-6. Did the drill pytest suite get updated for the new env-var contract,
- and does it pass?
-7. Did the smoke scenario actually get run after path changes?
-8. Is the drill repo unchanged? (cd ../drill && git status)
-
-Verify before claiming. If you assert "X is broken", check on disk
-first. Confidently-wrong claims count negatively.
-
-Report format: numbered list, each with severity (critical/important/
-minor/nitpick) and one-sentence explanation with file:line. Lead with
-most serious. Cap at ~600 words.
-```
-
-- [ ] **Step 3: Address findings**
-
-For each legitimate finding from either reviewer, fix in a separate commit. Re-run smoke checks (Task 13) after fixes.
-
-- [ ] **Step 4: Declare a winner**
-
-Per the cross-platform PR pattern, count legitimate findings (false positives count negatively). Acknowledge the winner in your reply summary.
-
----
-
-## Task 15: Push and open PR
-
-**Files:** none
-
-- [ ] **Step 1: Push the branch**
-
-```bash
-cd /Users/jesse/Documents/GitHub/superpowers/superpowers
-git push -u origin f/evals-lift
-```
-
-- [ ] **Step 2: Open PR against dev with full description**
-
-```bash
-gh pr create \
- --base dev \
- --head f/evals-lift \
- --reviewer arittr \
- --title "Lift drill into superpowers as evals/ harness" \
- --body "$(cat <<'EOF'
-## What problem are you trying to solve?
-
-Drill — the standalone Python skill-compliance benchmark at obra/drill — is already the de facto eval harness for superpowers. The PRI-1397 commit series lifted ~22 bash tests into drill scenarios, and the most recent superpowers commit (a2292c5) explicitly removed a redundant bash test with the message "replaced by drill behavioral coverage". Drill is a sibling repo today, requiring contributors to clone two checkouts and set SUPERPOWERS_ROOT manually. This PR completes the migration: drill becomes superpowers/evals/.
-
-## What does this PR change?
-
-- Lifts the obra/drill repo into superpowers as `evals/`, with explicit rsync excludes (.git, .venv, results, .env, __pycache__, *.egg-info, .private-journal). The lift commit records the source SHA.
-- Adds a `_set_superpowers_root_default()` helper to drill/cli.py so SUPERPOWERS_ROOT defaults to the parent of evals/ — no manual env-var setup.
-- Drops SUPERPOWERS_ROOT from required_env in codex.yaml/gemini.yaml (the helper supplies it). Claude*.yaml keep it because they interpolate ${SUPERPOWERS_ROOT} into --plugin-dir args.
-- Deletes redundant bash tests under tests/skill-triggering/, tests/explicit-skill-requests/, tests/subagent-driven-dev/, and tests/claude-code/ — gated per-file by a subagent that compared each bash test's assertions to its drill scenario's verify block. Anything not 100% covered was kept.
-- docs/testing.md split into Plugin tests + Skill behavior evals.
-- README.md Contributing and CLAUDE.md gain pointers to evals/.
-
-## Is this change appropriate for the core library?
-
-Yes. Cross-runtime evaluation is core to superpowers, the migration to drill scenarios was already underway in this repo, and the eval harness needs to be discoverable in-tree to be findable.
-
-## What alternatives did you consider?
-
-- Vendored copy + sync script (drill repo continues independently). Rejected: divergence risk; single-source-of-truth wins.
-- git subtree merge (preserves drill history in-tree). Rejected: superpowers' git history grows by 50+ commits, the merge commit is ugly, subtrees are operationally heavy.
-- Keep drill as a sibling repo and just polish docs. Rejected: doesn't solve the discoverability problem.
-
-## Does this PR contain multiple unrelated changes?
-
-No — every change supports "drill is now evals/ inside superpowers". Multiple commits for atomicity (verbatim copy, env helper, YAML updates, docs) but one direction.
-
-## Existing PRs
-
-- [x] I have reviewed all open AND closed PRs for duplicates or prior art
-- Related PRs: #1486 (obra/superpowers cross-platform PR — independent; no shared file changes besides README, which has no overlap)
-
-## Environment tested
-
-| Harness | Version | Model | Model ID |
-|---------|---------|-------|----------|
-| Claude Code | local install | Opus | claude-opus-4-7 (1M context) |
-
-Drill's own pytest suite passes from the new location. `triggering-test-driven-development` drill scenario passes from `evals/` after the path-default changes. (Larger drill sweep deferred to release-cadence runs per the spec's deferred-CI policy.)
-
-## Evaluation
-
-- Initial prompt: see linked spec (`docs/superpowers/specs/2026-05-06-lift-drill-into-evals-design.md`).
-- Drill's own pytest suite passes.
-- One drill scenario re-run from the new location end-to-end (proves the SUPERPOWERS_ROOT default works).
-- Per-deleted-file subagent verification recorded in each deletion commit's message.
-
-## Rigor
-
-- [x] If this is a skills change: this is not a skills change; it's a tooling/infrastructure migration. No behavior-shaping content modified.
-- [x] Adversarial pressure-tested: two parallel reviewers on the spec; final adversarial pre-PR review on the implementation; spec already corrected for findings before implementation began.
-- [x] Did not modify carefully-tuned content.
-
-## Human review
-
-- [x] A human has reviewed the COMPLETE proposed diff before submission
-
-## Action items after merge
-
-1. Archive obra/drill on GitHub (mark read-only, add README pointer to obra/superpowers/evals/).
-2. The spec lists CI integration, scenario co-location with skills, and Python package rename as deferred work. Open issues for any of these you want tracked.
-EOF
-)"
-```
-
-- [ ] **Step 3: Confirm PR opened**
-
-```bash
-gh pr view --web
-```
-
-Expected: browser opens to the new PR. Take a screenshot or note the URL for follow-up.
-
----
-
-## Verification checklist (run after Task 15)
-
-- [ ] `git log --oneline dev..HEAD` shows the expected commits in order
-- [ ] The lift commit message records the source SHA
-- [ ] `find evals -name '.git' -type d` returns no output
-- [ ] `cd evals && unset SUPERPOWERS_ROOT && uv run pytest` passes
-- [ ] `cd evals && unset SUPERPOWERS_ROOT && uv run drill list` returns scenarios
-- [ ] `cd evals && unset SUPERPOWERS_ROOT && uv run drill run triggering-test-driven-development -b claude` passes
-- [ ] `tests/brainstorm-server/server.test.js` still passes (regression gate for non-LLM tests)
-- [ ] `git diff dev..HEAD docs/superpowers/plans/2026-04-06-worktree-rototill.md docs/superpowers/plans/2026-03-23-codex-app-compatibility.md RELEASE-NOTES.md` shows annotations only, no path rewrites
-- [ ] `cd ../drill && git log --oneline -1` shows obra/drill is unchanged from the source SHA recorded in the lift commit
-- [ ] PR body lists the post-merge archival action item
diff --git a/docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md b/docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md
deleted file mode 100644
index 6272acd..0000000
--- a/docs/superpowers/plans/2026-05-07-pi-extension-and-evals.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# Pi Extension and Evals Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add first-class Pi package support for Superpowers and add Pi as a Drill eval backend.
-
-**Architecture:** The Pi package is declared in the root `package.json` and loads existing `skills/` plus a small Pi extension. The extension injects the `using-superpowers` bootstrap into provider context as a user-role message on session startup and after compaction, with Pi-specific tool mapping. Drill gains a `pi` backend, Pi session-log normalization, and tests.
-
-**Tech Stack:** Pi TypeScript extension API, Node built-in test runner, Drill Python eval harness, pytest.
-
----
-
-### Task 1: Pi package manifest and extension tests
-
-**Files:**
-- Modify: `package.json`
-- Create: `tests/pi/test-pi-extension.mjs`
-
-- [ ] **Step 1: Write failing package/extension tests**
-
-Create `tests/pi/test-pi-extension.mjs` with tests that import `extensions/superpowers.ts`, register fake Pi handlers, and assert:
-- root `package.json` has `keywords` containing `pi-package`
-- root `package.json` has `pi.skills: ["./skills"]`
-- root `package.json` has `pi.extensions: ["./extensions/superpowers.ts"]`
-- the extension registers `resources_discover`, `session_start`, `session_compact`, `context`, and `agent_end`
-- startup `context` injects exactly one user-role bootstrap message
-- `agent_end` clears startup injection
-- `session_compact` re-enables injection
-- the extension does not register `session_before_compact`
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: FAIL because `extensions/superpowers.ts` does not exist and `package.json` lacks the `pi` manifest.
-
-- [ ] **Step 3: Implement manifest fields**
-
-Update `package.json` with `description`, `keywords`, `pi.extensions`, and `pi.skills` while preserving existing `name`, `version`, `type`, and `main`.
-
-- [ ] **Step 4: Implement `extensions/superpowers.ts`**
-
-Create a zero-runtime-dependency extension that:
-- locates the package root from `import.meta.url`
-- reads `skills/using-superpowers/SKILL.md`
-- strips YAML frontmatter
-- appends Pi-specific tool mapping
-- exposes `resources_discover` with the skills path
-- marks bootstrap pending on `session_start` and `session_compact`
-- injects a user-role bootstrap message in `context`
-- inserts post-compact bootstrap after leading `compactionSummary` messages
-- clears pending bootstrap on `agent_end`
-
-- [ ] **Step 5: Run tests and verify GREEN**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: PASS.
-
-### Task 2: Pi tool mapping reference
-
-**Files:**
-- Create: `skills/using-superpowers/references/pi-tools.md`
-- Modify: `tests/pi/test-pi-extension.mjs`
-
-- [ ] **Step 1: Write failing test for Pi reference doc**
-
-Add assertions that `skills/using-superpowers/references/pi-tools.md` exists and documents mappings for `Skill`, `Task`, `TodoWrite`, and built-in tool names.
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: FAIL because `pi-tools.md` does not exist.
-
-- [ ] **Step 3: Add Pi reference doc**
-
-Create `skills/using-superpowers/references/pi-tools.md` explaining Pi-native skills, optional `pi-subagents`, no canonical todo/tasklist plugin, and built-in lowercase tools.
-
-- [ ] **Step 4: Run tests and verify GREEN**
-
-Run: `node --experimental-strip-types --test tests/pi/test-pi-extension.mjs`
-
-Expected: PASS.
-
-### Task 3: Drill Pi backend and session log normalization
-
-**Files:**
-- Create: `evals/backends/pi.yaml`
-- Modify: `evals/drill/backend.py`
-- Modify: `evals/drill/engine.py`
-- Modify: `evals/drill/normalizer.py`
-- Modify: `evals/tests/test_backend.py`
-- Modify: `evals/tests/test_normalizer.py`
-
-- [ ] **Step 1: Write failing backend/normalizer tests**
-
-Add pytest coverage for:
-- `load_backend("pi")` returns `family == "pi"`
-- Pi backend command starts with `pi` and includes `-e ${SUPERPOWERS_ROOT}`
-- `_resolve_log_dir()` for Pi points under `~/.pi/agent/sessions`
-- `filter_pi_logs_by_cwd()` keeps only session files whose header `cwd` matches the scenario workdir
-- `normalize_pi_logs()` extracts `toolCall` blocks from Pi assistant session entries and maps built-in lowercase tools to canonical names
-
-- [ ] **Step 2: Run tests and verify RED**
-
-Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
-
-Expected: FAIL because the Pi backend and normalizer do not exist.
-
-- [ ] **Step 3: Add `evals/backends/pi.yaml`**
-
-Configure the backend to run `pi -e ${SUPERPOWERS_ROOT}`, use permissive TUI readiness, `/quit` shutdown, and Pi session log location.
-
-- [ ] **Step 4: Implement Pi family support**
-
-Update `Backend.family`, `Engine._resolve_log_dir`, `Engine._collect_tool_calls`, and `normalizer.py` with Pi log filtering and normalizing.
-
-- [ ] **Step 5: Run tests and verify GREEN**
-
-Run: `uv run pytest evals/tests/test_backend.py evals/tests/test_normalizer.py -q`
-
-Expected: PASS.
-
-### Task 4: Documentation and full verification
-
-**Files:**
-- Modify: `README.md`
-- Modify: `evals/README.md`
-
-- [ ] **Step 1: Document Pi install and eval backend**
-
-Add Pi to README quickstart/install list and add backend entry/usage to `evals/README.md`.
-
-- [ ] **Step 2: Run verification**
-
-Run:
-```bash
-node --experimental-strip-types --test tests/pi/test-pi-extension.mjs
-uv run pytest evals/tests/test_backend.py evals/tests/test_setup.py evals/tests/test_normalizer.py -q
-```
-
-Expected: all tests pass.
diff --git a/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md b/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md
deleted file mode 100644
index 57cc5fc..0000000
--- a/docs/superpowers/plans/2026-06-09-sdd-task-scoped-review-dispatch.md
+++ /dev/null
@@ -1,774 +0,0 @@
-# SDD Task-Scoped Review Dispatch Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Scope SDD's per-task reviews to the task (diff-first reading, justified broadening, no redundant test runs) while final branch review stays broad.
-
-**Architecture:** Four prose edits to the subagent-driven-development skill (the per-task quality prompt becomes self-contained instead of delegating to the merge-readiness template; the spec prompt gets a third verdict channel and grounded skepticism; the implementer prompt gains a re-run-after-fix rule; SKILL.md gets controller guidance) plus one new eval scenario in the `evals/` submodule. `skills/requesting-code-review/` is deliberately untouched.
-
-**Tech Stack:** Markdown skill files; Python setup helper + bash checks + story.md for the quorum eval.
-
-**Spec:** `docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md` — read it before starting. Decisions already settled there: full re-reviews stay; the two review stages stay separate; coordinator keeps model judgment; `requesting-code-review/` stays broad.
-
-**These are behavior-shaping prose files, not code.** There are no unit tests for them. Each task's verification steps are exact `grep` checks that the edit landed; behavioral verification is Task 6 (static) and Task 7 (live evals, maintainer-gated).
-
----
-
-### Task 1: Rewrite the per-task quality reviewer prompt as self-contained
-
-The current file delegates to `../requesting-code-review/code-reviewer.md`, which is a merge-readiness review (architecture, security, production readiness, "Ready to merge?"). Replace the entire file with a self-contained, task-scoped template.
-
-**Files:**
-- Rewrite: `skills/subagent-driven-development/code-quality-reviewer-prompt.md`
-
-- [ ] **Step 1: Replace the full file contents with:**
-
-````markdown
-# Code Quality Reviewer Prompt Template
-
-Use this template when dispatching a code quality reviewer subagent.
-
-**Purpose:** Verify one task's implementation is well-built (clean, tested, maintainable)
-
-**Only dispatch after spec compliance review passes.**
-
-```
-Subagent (general-purpose):
- description: "Review code quality for Task N"
- prompt: |
- You are reviewing one task's implementation for code quality. This is a
- task-scoped gate, not a merge review — a broad whole-branch review happens
- separately after all tasks are complete.
-
- ## What Was Implemented
-
- [DESCRIPTION]
-
- ## Task Requirements (context only)
-
- [TASK_TEXT]
-
- ## Git Range to Review
-
- **Base:** [BASE_SHA]
- **Head:** [HEAD_SHA]
-
- ```bash
- git diff --stat [BASE_SHA]..[HEAD_SHA]
- git diff [BASE_SHA]..[HEAD_SHA]
- ```
-
- ## Read-Only Review
-
- Your review is read-only on this checkout. Do not mutate the working tree,
- the index, HEAD, or branch state in any way. Use tools like `git show`,
- `git diff`, and `git log` to inspect history.
-
- ## Scope
-
- Spec compliance was already verified by a separate reviewer. Do not
- re-check whether the code matches the requirements or the plan.
-
- Start from the diff. Read the changed files first. Inspect code outside
- the diff only to evaluate a concrete risk you can name — and name it in
- your report. Cross-cutting changes are legitimate named risks: if the
- diff changes lock ordering, a function or API contract, or shared mutable
- state, checking the call sites is the right method. Do not crawl the
- codebase by default.
-
- ## Tests
-
- The implementer already ran the tests and reported results with TDD
- evidence for exactly this code. Do not re-run the suite to confirm their
- report. Run a test only when reading the code raises a specific doubt
- that no existing run answers — and then a focused test, never a
- package-wide suite, race detector run, or repeated/high-count loop. If
- heavy validation seems warranted, recommend it in your report instead of
- running it. If you cannot run commands in this environment, name the
- test you would run.
-
- ## What to Check
-
- **Code quality:**
- - Clean separation of concerns?
- - Proper error handling?
- - DRY without premature abstraction?
- - Edge cases handled?
-
- **Tests:**
- - Do the new and changed tests verify real behavior, not mocks?
- - Are the task's edge cases covered?
-
- **Structure:**
- - Does each file have one clear responsibility with a well-defined interface?
- - Are units decomposed so they can be understood and tested independently?
- - Is the implementation following the file structure from the plan?
- - Did this change create new files that are already large, or
- significantly grow existing files? (Don't flag pre-existing file
- sizes — focus on what this change contributed.)
-
- ## Calibration
-
- Categorize issues by actual severity. Not everything is Critical.
- Acknowledge what was done well before listing issues — accurate praise
- helps the implementer trust the rest of the feedback.
-
- ## Output Format
-
- ### Strengths
- [What's well done? Be specific.]
-
- ### Issues
-
- #### Critical (Must Fix)
- [Bugs, data loss risks, broken functionality]
-
- #### Important (Should Fix)
- [Poor error handling, test gaps, structural problems]
-
- #### Minor (Nice to Have)
- [Code style, optimization opportunities]
-
- For each issue:
- - File:line reference
- - What's wrong
- - Why it matters
- - How to fix (if not obvious)
-
- ### Assessment
-
- **Task quality:** [Approved | Needs fixes]
-
- **Reasoning:** [1-2 sentence technical assessment]
-```
-
-**Placeholders:**
-- `[DESCRIPTION]` — task summary, from implementer's report
-- `[TASK_TEXT]` — the task's requirements text or plan reference, for context
-- `[BASE_SHA]` — commit before this task
-- `[HEAD_SHA]` — current commit
-
-**Reviewer returns:** Strengths, Issues (Critical/Important/Minor), Task quality verdict
-````
-
-- [ ] **Step 2: Verify the rewrite landed**
-
-Run: `grep -c "requesting-code-review" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo ABSENT`
-Expected: `ABSENT` (no more delegation)
-
-Run: `grep -n "Task quality:" skills/subagent-driven-development/code-quality-reviewer-prompt.md | head -2`
-Expected: one match (the Output Format verdict line; the "Reviewer returns" footer says "Task quality verdict" without a colon)
-
-Run: `grep -n "worktree add\|Ready to merge" skills/subagent-driven-development/code-quality-reviewer-prompt.md || echo CLEAN`
-Expected: `CLEAN`
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/subagent-driven-development/code-quality-reviewer-prompt.md
-git commit -m "Make per-task quality reviewer prompt self-contained and task-scoped"
-```
-
----
-
-### Task 2: Spec reviewer prompt cleanups
-
-Four exact edits to `skills/subagent-driven-development/spec-reviewer-prompt.md`. Current line numbers refer to the file as of commit f55642e.
-
-**Files:**
-- Modify: `skills/subagent-driven-development/spec-reviewer-prompt.md`
-
-- [ ] **Step 1: Add the judge-from-the-diff clause.** After the line (currently line 31):
-
-```
- Only read files in this diff. Do not crawl the broader codebase.
-```
-
-insert a blank line and:
-
-```
- Spec compliance is judged by reading the diff against the requirements.
- The implementer already ran the tests and reported TDD evidence — do not
- re-run them. If a requirement cannot be verified from this diff alone
- (it lives in unchanged code or spans tasks), report it as a ⚠️ item
- instead of broadening your search.
-```
-
-- [ ] **Step 2: Trim the read-only section.** Replace (currently line 35):
-
-```
- Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history. If you need a working copy of a different revision, check it out into a separate temporary directory (e.g. `git worktree add /tmp/review-[SHA] [SHA]`) — never move HEAD on this checkout.
-```
-
-with:
-
-```
- Your review is read-only on this checkout. Do not mutate the working tree, the index, HEAD, or branch state in any way. Use tools like `git show`, `git diff`, and `git log` to inspect history.
-```
-
-- [ ] **Step 3: Ground the skepticism.** Replace (currently lines 39-40):
-
-```
- The implementer finished suspiciously quickly. Their report may be incomplete,
- inaccurate, or optimistic. You MUST verify everything independently.
-```
-
-with:
-
-```
- Treat the implementer's report as unverified claims about the code. It may
- be incomplete, inaccurate, or optimistic. Verify the claims against the diff.
-```
-
-- [ ] **Step 4: Add the third verdict channel.** Replace (currently lines 74-76):
-
-```
- Report:
- - ✅ Spec compliant (if everything matches after code inspection)
- - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
-```
-
-with:
-
-```
- Report:
- - ✅ Spec compliant (if everything matches after code inspection)
- - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
- - ⚠️ Cannot verify from diff: [requirements you could not verify from the
- diff alone, and what the controller should check — report alongside the
- ✅/❌ verdict for everything you could verify]
-```
-
-- [ ] **Step 5: Verify**
-
-Run: `grep -n "suspiciously\|worktree add" skills/subagent-driven-development/spec-reviewer-prompt.md || echo CLEAN`
-Expected: `CLEAN`
-
-Run: `grep -c "⚠️" skills/subagent-driven-development/spec-reviewer-prompt.md`
-Expected: `2` (judge-from-diff clause + verdict channel)
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add skills/subagent-driven-development/spec-reviewer-prompt.md
-git commit -m "Spec reviewer: judge from the diff, grounded skepticism, ⚠️ verdict channel"
-```
-
----
-
-### Task 3: Implementer prompt — re-run tests after fixing review findings
-
-The reviewers' "don't re-run the implementer's tests" rule assumes the implementer re-runs tests after every fix. Make that real.
-
-**Files:**
-- Modify: `skills/subagent-driven-development/implementer-prompt.md`
-
-- [ ] **Step 1: Insert a new section.** Immediately before the line (currently line 100):
-
-```
- ## Report Format
-```
-
-insert:
-
-```
- ## After Review Findings
-
- If a reviewer finds issues and you fix them, re-run the tests that cover
- the amended code and include the results in your fix report. Reviewers
- will not re-run tests for you — your report is the test evidence.
-
-```
-
-- [ ] **Step 2: Verify**
-
-Run: `grep -n "After Review Findings" skills/subagent-driven-development/implementer-prompt.md`
-Expected: one match, on a line before `## Report Format`
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/subagent-driven-development/implementer-prompt.md
-git commit -m "Implementer prompt: re-run covering tests after fixing review findings"
-```
-
----
-
-### Task 4: SKILL.md controller changes
-
-Six exact edits to `skills/subagent-driven-development/SKILL.md`. Current line numbers refer to commit f55642e.
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md`
-
-- [ ] **Step 1: Point the final-review flowchart node at the broad template.** The node label `Dispatch final code reviewer subagent for entire implementation` appears 3 times (currently lines 65, 84, 85). In all 3 occurrences, replace the label string with:
-
-```
-Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)
-```
-
-(Graphviz nodes are matched by label text — all three must be byte-identical or the graph grows a phantom node.)
-
-- [ ] **Step 2: Model selection by judgment.** Replace (currently lines 97-99):
-
-```
-**Architecture, design, and review tasks**: use the most capable available model.
-
-**Task complexity signals:**
-```
-
-with:
-
-```
-**Architecture and design tasks**: use the most capable available model.
-
-**Review tasks**: choose the model with the same judgment, scaled to the
-diff's size, complexity, and risk. A small mechanical diff does not need the
-most capable model; a subtle concurrency change does.
-
-**Task complexity signals (implementation tasks):**
-```
-
-- [ ] **Step 3: Add controller guidance sections.** Immediately before the line (currently line 122):
-
-```
-## Prompt Templates
-```
-
-insert:
-
-```
-## Handling Spec Reviewer ⚠️ Items
-
-The spec reviewer may report "⚠️ Cannot verify from diff" items — requirements
-that live in unchanged code or span tasks. These do not block dispatching the
-code quality reviewer, but you must resolve each one yourself before marking
-the task complete: you hold the plan and cross-task context the reviewer
-lacks. If you confirm an item is a real gap, treat it as a failed spec
-review — send it back to the implementer and re-review.
-
-## Constructing Reviewer Prompts
-
-Per-task reviews are task-scoped gates. The broad review happens once, at the
-final whole-branch review. When you fill a reviewer template:
-
-- Do not add open-ended directives like "check all uses" or "run race tests
- if useful" without a concrete, task-specific reason
-- Do not ask a reviewer to re-run tests the implementer already ran on the
- same code — the implementer's report carries the test evidence
-
-```
-
-- [ ] **Step 4: Prompt Templates list — add the final-review pointer.** Replace (currently line 126):
-
-```
-- [code-quality-reviewer-prompt.md](code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
-```
-
-with:
-
-```
-- [code-quality-reviewer-prompt.md](code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
-- Final whole-branch review: use superpowers:requesting-code-review's [code-reviewer.md](../requesting-code-review/code-reviewer.md)
-```
-
-- [ ] **Step 5: Example workflow verdict vocabulary.** Two replacements:
-
-Replace (currently line 157):
-```
-Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
-```
-with:
-```
-Code reviewer: Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
-```
-
-Replace (currently line 191):
-```
-Code reviewer: ✅ Approved
-```
-with:
-```
-Code reviewer: ✅ Task quality: Approved
-```
-
-(The final reviewer's "ready to merge" line, currently line 199, stays.)
-
-- [ ] **Step 6: Integration section.** Replace (currently line 272):
-
-```
-- **superpowers:requesting-code-review** - Code review template for reviewer subagents
-```
-
-with:
-
-```
-- **superpowers:requesting-code-review** - Code review template for the final whole-branch review
-```
-
-- [ ] **Step 7: Verify**
-
-Run: `grep -c "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" skills/subagent-driven-development/SKILL.md`
-Expected: `3`
-
-Run: `grep -n "most capable available model" skills/subagent-driven-development/SKILL.md`
-Expected: exactly one match (architecture/design bullet)
-
-Run: `grep -n "Handling Spec Reviewer\|Constructing Reviewer Prompts" skills/subagent-driven-development/SKILL.md`
-Expected: two section headers, both before `## Prompt Templates`
-
-Run: `grep -c "Task quality: Approved" skills/subagent-driven-development/SKILL.md`
-Expected: `2`
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md
-git commit -m "SDD controller: reviewer prompt budgets, ⚠️ handling, final-review pointer, model judgment"
-```
-
----
-
-### Task 5: New eval scenario — per-task quality reviewer catches a planted defect
-
-Lives in the `evals/` **submodule** (separate repo, `superpowers-evals`). Work on a branch there; the parent submodule-pointer bump happens at finishing time per `evals/CLAUDE.md`.
-
-The fixture plan's Task 2 implementation snippet duplicates Task 1's formatting logic verbatim. The duplication is spec-compliant, so the spec reviewer should pass it — the per-task quality reviewer is the gate under test (DRY violation).
-
-**Files:**
-- Create: `evals/setup_helpers/sdd_quality_defect_plan.py`
-- Modify: `evals/setup_helpers/__init__.py`
-- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/story.md`
-- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`
-- Create: `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/checks.sh`
-
-- [ ] **Step 0: Branch in the submodule**
-
-```bash
-cd evals
-git checkout -b sdd-quality-defect-scenario
-```
-
-- [ ] **Step 1: Create `evals/setup_helpers/sdd_quality_defect_plan.py`:**
-
-````python
-"""Setup helper for the sdd-quality-reviewer-catches-planted-defect scenario.
-
-Scaffolds a tiny Node project with a 2-task plan whose Task 2
-implementation snippet duplicates Task 1's formatting logic verbatim.
-The duplication is spec-compliant — the requirements only describe
-behavior — so the spec compliance reviewer should pass it. The test
-measures whether the per-task code quality reviewer catches the DRY
-violation and forces a refactor in the review-fix loop.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from setup_helpers.base import _git
-
-PACKAGE_JSON = """\
-{
- "name": "report-quality",
- "version": "1.0.0",
- "type": "module",
- "scripts": {
- "test": "node --test"
- }
-}
-"""
-
-PLAN_BODY = """\
-# Report Formatter — Implementation Plan
-
-Two report formatting functions. Implement exactly what each task
-specifies.
-
-## Task 1: User Report
-
-**File:** `src/report.js`
-
-**Requirements:**
-- Function named `formatUserReport`
-- Takes one parameter `user`: an object with `name`, `email`, `visits`
-- Returns a multi-line string: a banner of 40 `=` characters, then
- `Report for <name> <<email>>`, then the banner again, then
- `Visits: <visits>`, then a closing banner
-- Export the function
-
-**Implementation:**
-```javascript
-export function formatUserReport(user) {
- const banner = "=".repeat(40);
- const lines = [];
- lines.push(banner);
- lines.push(`Report for ${user.name} <${user.email}>`);
- lines.push(banner);
- lines.push(`Visits: ${user.visits}`);
- lines.push(banner);
- return lines.join("\\n");
-}
-```
-
-**Tests:** Create `test/report.test.js` verifying:
-- the result contains `Report for Ada <ada@example.com>` for that user
-- the result contains `Visits: 3` when `visits` is `3`
-- the result starts and ends with the 40-char banner
-
-**Verification:** `npm test`
-
-## Task 2: Admin Report
-
-**File:** `src/report.js` (add to existing file)
-
-**Requirements:**
-- Function named `formatAdminReport`
-- Takes one parameter `admin`: an object with `name`, `email`, `lastLogin`
-- Same banner layout as the user report; the body line is
- `Last login: <lastLogin>` instead of the visits line
-- Export the function; keep `formatUserReport` working
-
-**Implementation:**
-```javascript
-export function formatAdminReport(admin) {
- const banner = "=".repeat(40);
- const lines = [];
- lines.push(banner);
- lines.push(`Report for ${admin.name} <${admin.email}>`);
- lines.push(banner);
- lines.push(`Last login: ${admin.lastLogin}`);
- lines.push(banner);
- return lines.join("\\n");
-}
-```
-
-**Tests:** Add to `test/report.test.js`:
-- the result contains `Report for Grace <grace@example.com>` for that admin
-- the result contains `Last login: 2026-06-01`
-- the result starts and ends with the 40-char banner
-
-**Verification:** `npm test`
-"""
-
-
-def scaffold_sdd_quality_defect_plan(workdir: Path) -> None:
- workdir = Path(workdir)
- workdir.mkdir(parents=True, exist_ok=True)
- _git(["git", "init", "-b", "main"], cwd=workdir)
- _git(["git", "config", "user.email", "drill@test.local"], cwd=workdir)
- _git(["git", "config", "user.name", "Drill Test"], cwd=workdir)
-
- (workdir / "package.json").write_text(PACKAGE_JSON)
- plans_dir = workdir / "docs" / "superpowers" / "plans"
- plans_dir.mkdir(parents=True, exist_ok=True)
- (plans_dir / "report-plan.md").write_text(PLAN_BODY)
-
- _git(["git", "add", "-A"], cwd=workdir)
- _git(["git", "commit", "-m", "initial: report formatter plan"], cwd=workdir)
-````
-
-(Note the `\\n` in the JS snippets inside PLAN_BODY: the Python source must
-produce a literal `\n` in the markdown so the JS reads `lines.join("\n")`.)
-
-- [ ] **Step 2: Register the helper.** In `evals/setup_helpers/__init__.py`:
-
-After the line:
-```python
-from setup_helpers.sdd_real_projects import scaffold_sdd_go_fractals, scaffold_sdd_svelte_todo
-```
-add:
-```python
-from setup_helpers.sdd_quality_defect_plan import scaffold_sdd_quality_defect_plan
-```
-
-After the registry entry:
-```python
- "scaffold_sdd_yagni_plan": scaffold_sdd_yagni_plan,
-```
-add:
-```python
- "scaffold_sdd_quality_defect_plan": scaffold_sdd_quality_defect_plan,
-```
-
-- [ ] **Step 3: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/story.md`:**
-
-```markdown
----
-id: sdd-quality-reviewer-catches-planted-defect
-title: SDD's per-task code quality review catches a planted DRY violation
-status: ready
-tags: subagent-driven-development
-quorum_max_time: 90m
----
-
-You have a small plan at docs/superpowers/plans/report-plan.md — two report
-formatting functions. The plan's Task 2 implementation snippet duplicates
-Task 1's formatting logic verbatim instead of sharing it. The duplication is
-spec-compliant (the requirements only describe behavior), so the spec
-compliance reviewer should pass it — the per-task code quality reviewer is
-the gate under test. You are spec-aware — name the skill.
-
-When the agent is ready for input, tell it to execute the plan with SDD. Use
-phrasing like:
-
-"I have a small plan at docs/superpowers/plans/report-plan.md — two report
-formatting functions. Use the superpowers:subagent-driven-development skill
-to execute it end-to-end — dispatch fresh subagents per task and run the
-two-stage review after each."
-
-Let the agent proceed autonomously. If it asks clarifying questions, give
-brief answers. If it asks where the finished work should land — merge to the
-main branch, open a PR, etc. — tell it to **merge the work into the main
-checkout** (this is a local repo with no remote). If a quality reviewer
-flags the duplicated formatting logic and an implementer refactors it, let
-the review-fix cycle play out — that cycle is exactly the behavior under
-test.
-
-The deliverable must end up in the checkout you launched in (the main
-working tree). If the agent did its work on a branch or in a worktree, it
-is not done until it has merged/finished that work back into the main
-checkout. Once the agent reports the plan is complete (both functions
-implemented, tests passing) AND the code is present on the main checkout,
-you are done.
-
-## Acceptance Criteria
-
-- A `Skill` invocation naming `superpowers:subagent-driven-development`
- and at least one `Agent` (subagent dispatch) tool call appear in the
- session log.
-- The duplicated report-formatting logic did not survive to the end of
- the run. Either (a) the implementer never introduced the duplication
- (wrote or self-reviewed its way to shared logic), or (b) the per-task
- code quality reviewer flagged the duplication as an issue and a
- review-fix loop removed it. A fail looks like the duplicated logic
- shipping with the per-task quality reviewer approving it, or the
- duplication being caught only by the final whole-branch review.
-- The per-task quality reviewers stayed task-scoped: no package-wide
- test suites, race detector runs, or repeated/high-count test loops
- appear in reviewer subagent activity, and reviewers did not re-run
- the full test suite merely to confirm the implementer's report.
-- `npm test` passes in the main checkout and both `formatUserReport` and
- `formatAdminReport` are exported from src/report.js. The deterministic
- assertions gate this; the criteria above are about whether the
- *per-task quality review* was the mechanism that kept the code clean.
-```
-
-- [ ] **Step 4: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`:**
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-uv run setup-helpers run scaffold_sdd_quality_defect_plan
-```
-
-Then: `chmod +x evals/scenarios/sdd-quality-reviewer-catches-planted-defect/setup.sh`
-
-- [ ] **Step 5: Create `evals/scenarios/sdd-quality-reviewer-catches-planted-defect/checks.sh`** (no executable bit):
-
-```bash
-pre() {
- git-repo
- git-branch main
- requires-tool npm
- file-exists 'docs/superpowers/plans/report-plan.md'
- file-contains 'docs/superpowers/plans/report-plan.md' 'formatAdminReport'
- file-contains 'docs/superpowers/plans/report-plan.md' 'repeat\(40\)'
-}
-
-post() {
- skill-called superpowers:subagent-driven-development
- tool-called Agent
- command-succeeds 'npm test'
- file-contains 'src/report.js' 'export function formatUserReport'
- file-contains 'src/report.js' 'export function formatAdminReport'
- command-succeeds 'test "$(grep -c "repeat(40)" src/report.js)" -le 1'
-}
-```
-
-(The last check is the deterministic DRY gate: the banner construction
-`"=".repeat(40)` must appear at most once in the final file — shared, not
-duplicated per function.)
-
-- [ ] **Step 6: Validate and test in the evals repo**
-
-```bash
-cd evals
-uv run quorum check
-uv run ruff check
-uv run pytest -x -q
-```
-
-Expected: all pass; `quorum check` lists the new scenario without errors.
-
-- [ ] **Step 7: Commit (in the submodule)**
-
-```bash
-cd evals
-git add setup_helpers/sdd_quality_defect_plan.py setup_helpers/__init__.py scenarios/sdd-quality-reviewer-catches-planted-defect/
-git commit -m "Add sdd-quality-reviewer-catches-planted-defect scenario"
-```
-
----
-
-### Task 6: Static verification sweep
-
-**Files:** none modified — verification only.
-
-- [ ] **Step 1: No dangling references in the parent repo**
-
-Run: `grep -rn "requesting-code-review" skills/subagent-driven-development/`
-Expected: matches only in SKILL.md (final-review flowchart node ×3, Prompt Templates pointer, Integration bullet). None in code-quality-reviewer-prompt.md.
-
-Run: `grep -rn "Ready to merge" skills/subagent-driven-development/ || echo CLEAN`
-Expected: `CLEAN`
-
-- [ ] **Step 2: Plugin infrastructure tests**
-
-Run: `bash tests/shell-lint/test-lint-shell.sh`
-Expected: all PASS (we added `setup.sh` only inside the evals submodule, which has its own checks).
-
-- [ ] **Step 3: Cross-platform tool tables still coherent**
-
-Run: `grep -n "code-quality-reviewer" skills/using-superpowers/references/antigravity-tools.md skills/using-superpowers/references/gemini-tools.md`
-Expected: both tables still list `code-quality-reviewer` as a reviewer template (the new prompt's "If you cannot run commands in this environment, name the test you would run" line keeps the read-only `research` mapping valid — no table edits needed).
-
----
-
-### Task 7: Live before/after evals (maintainer-gated)
-
-Live quorum runs launch agent CLIs in permissive modes — **trusted-maintainer operation; Jesse launches these**, per `evals/CLAUDE.md`. Requires `ANTHROPIC_API_KEY`.
-
-- [ ] **Step 1: Baseline (skills as released on dev)** — from the main checkout (`/Users/jesse/git/superpowers/superpowers`, on dev), or any checkout without this branch's changes:
-
-```bash
-cd evals
-export SUPERPOWERS_ROOT=/Users/jesse/git/superpowers/superpowers
-uv run quorum run scenarios/sdd-rejects-extra-features --coding-agent claude
-uv run quorum run scenarios/sdd-go-fractals --coding-agent claude
-uv run quorum run scenarios/sdd-svelte-todo --coding-agent claude
-uv run quorum run scenarios/spec-reviewer-catches-planted-flaws --coding-agent claude
-```
-
-- [ ] **Step 2: After (this branch's skills)** — point `SUPERPOWERS_ROOT` at this worktree:
-
-```bash
-cd evals
-export SUPERPOWERS_ROOT=/Users/jesse/git/superpowers/superpowers/.claude/worktrees/sdd-review-dispatch
-uv run quorum run scenarios/sdd-rejects-extra-features --coding-agent claude
-uv run quorum run scenarios/sdd-go-fractals --coding-agent claude
-uv run quorum run scenarios/sdd-svelte-todo --coding-agent claude
-uv run quorum run scenarios/spec-reviewer-catches-planted-flaws --coding-agent claude
-uv run quorum run scenarios/sdd-quality-reviewer-catches-planted-defect --coding-agent claude
-uv run quorum show
-```
-
-- [ ] **Step 3: Compare**
-
-Pass bar: all four pre-existing scenarios still pass after the change (no regression in catch rate); the new planted-defect scenario passes. For exploration cost, compare reviewer-subagent tool-call counts between the before/after run transcripts (no automated check exists — the spec calls this out as a known gap).
-
----
-
-## Finishing
-
-After all tasks pass: the evals submodule commit needs to land in `superpowers-evals` (PR to its `main`), then this branch bumps the `evals` submodule pointer — per `evals/CLAUDE.md`, the parent bump is part of propagation, not optional. Then use superpowers:finishing-a-development-branch. PRs against superpowers target `dev`.
diff --git a/docs/superpowers/plans/2026-06-09-visual-companion-issues.md b/docs/superpowers/plans/2026-06-09-visual-companion-issues.md
deleted file mode 100644
index 09d6c1d..0000000
--- a/docs/superpowers/plans/2026-06-09-visual-companion-issues.md
+++ /dev/null
@@ -1,352 +0,0 @@
-# Visual Brainstorming Companion — Issue & Change Catalog
-
-**Date:** 2026-06-09
-**Status:** Analysis / triage. We are implementing these ourselves; the referenced
-community PRs are evidence and reference material, **not** code we intend to merge.
-
-## Purpose
-
-A single place that captures every open issue and PR touching the visual
-brainstorming companion (the local server in `skills/brainstorming/scripts/`),
-distilled to the underlying problem and the change we'd make. Each item is
-grounded against the current code, not the PR author's description.
-
-## Scope decisions (Jesse, 2026-06-09)
-
-- **Not vendoring Alpine.js.** PR #1639 (interactive mockups via a vendored
- Alpine build) is **dropped**. See E3.
-- **E1 (terminal-vs-HTML hard gate) is a workshop item.** We'll design it
- together; it is not specced here.
-- **E2 (storage location, #975/#977) is deferred** for now.
-- **Remote serving is a first-class scenario.** Superpowers is general-purpose;
- users connect from remote (SSH tunnel, Tailscale, `--host 0.0.0.0`). The
- security fix MUST protect those users, not just loopback. **Decision: a
- per-session secret key**, not a Host allowlist. A Host allowlist only
- defends the loopback browser-confused-deputy; a direct remote client just
- sends the expected `Host`, so the allowlist is theater for remote exposure. A
- secret key is the only thing that authenticates a client uniformly across
- loopback, tunnel, and direct-remote, and it also defeats DNS rebinding. See A1.
-
-## Component map
-
-| File | Role |
-|------|------|
-| `skills/brainstorming/scripts/server.cjs` | Zero-dep HTTP + WebSocket server (RFC 6455 hand-rolled). Serves the newest screen, watches `content/`, records events to `state/events`. |
-| `skills/brainstorming/scripts/helper.js` | Injected into every page. WebSocket client, click capture, `window.brainstorm` API. |
-| `skills/brainstorming/scripts/frame-template.html` | Frame (header, theme CSS, status dot, indicator bar) wrapped around content fragments. |
-| `skills/brainstorming/scripts/start-server.sh` | Launch wrapper. Session dir, host/url-host, owner-PID resolution, platform backgrounding. |
-| `skills/brainstorming/scripts/stop-server.sh` | Kills the server by PID file, cleans `/tmp` sessions. |
-| `skills/brainstorming/visual-companion.md` | Operator guide the agent reads when it accepts the companion. |
-| `skills/brainstorming/SKILL.md` | Where the companion is offered and the per-question decision lives. |
-
-## Disposition summary
-
-| ID | Item | Source | Disposition |
-|----|------|--------|-------------|
-| A1 | Per-session secret key on `/`, `/files/*`, and WS (supersedes Host allowlist) | issues #1014, PRs #1110/#1553 | **Do** — chosen approach |
-| A2 | Host allowlist; browser WS Origin check | PRs #1110/#1553 | Host allowlist dropped; WS Origin check retained after auth for browser confused-deputy defense |
-| A3 | Crash on `null` / non-object WS payload | PR #1504 | Do |
-| A4 | Frame-length bound in `decodeFrame` | issue #1446 | Already fixed — verify/close |
-| B1 | Dotfile screens served as content (`._*.html`) | PR #950 | Do |
-| B2 | `stop-server.sh` kills reused/stale PID | PR #1703 | Do |
-| B3 | WS client reconnect backoff + status indicator | PR #856 | Do |
-| C1 | Idle timeout too short / not configurable; WS not closed on shutdown | issue #1237 (PR #1689) | Do |
-| C2 | Server death is invisible to user/agent | issue #1237 (residual) | Do |
-| D1 | Permanent opt-out of the companion | issue #892 | Deferred - not in PR #1720 |
-| D2 | Free-text feedback from the browser | issue #957 | Deferred - not in PR #1720 |
-| D3 | Auto-open the companion URL | PR #759 (#755) | Done in PR #1720 via `--open` |
-| D4 | Light/dark contrast helpers in the frame | PR #1683 | Deferred - not in PR #1720 |
-| E1 | Hard-gate terminal-vs-HTML per question | PR #1037 | **Workshop** |
-| E2 | Move session state out of the working tree | issue #975 (PR #977) | **Deferred** |
-| E3 | Vendor Alpine.js for interactive mockups | PR #1639 | **Dropped** |
-| E4 | Shell-lint warnings in start/stop scripts | PR #1677 | Opportunistic only |
-
----
-
-## A. Server security hardening (`server.cjs`)
-
-### A1 — Per-session secret key (chosen approach)
-
-**Threat model.** Two assets: confidentiality of the served screen (`/`) and
-files (`/files/*`), and integrity of `state/events` — a WebSocket client with a
-truthy `choice` writes there (`server.cjs:243-246`), and the agent reads it next
-turn as the user's selection, i.e. **prompt injection into a live session with
-full tool access**. Reachers: with the default `127.0.0.1` bind, a malicious
-page in the user's browser (a confused deputy — runs attacker JS *and* can reach
-loopback); with a remote bind (`--host 0.0.0.0`, tailnet/LAN), any host that can
-route to the port, directly, with no same-origin policy in the way. Today
-`handleUpgrade` (`server.cjs:176`) checks only `Sec-WebSocket-Key`, and
-`handleRequest` (`server.cjs:138`) checks nothing — both are wide open.
-
-**Why a key, not a Host allowlist.** A Host allowlist only defends the
-loopback browser-deputy. A direct remote client just sends the expected `Host`
-and forges/omits `Origin`, so the allowlist is theater for exactly the remote
-case we must protect. A per-session secret authenticates the client uniformly
-across loopback, SSH tunnel, and direct-remote, and it also kills DNS rebinding
-(the rebound page neither knows the key nor receives the host-scoped cookie).
-So the key **supersedes** A1/A2's Host allowlist entirely — no `BRAINSTORM_ALLOWED_HOSTS`.
-
-**Design.** Random token (`crypto.randomBytes(32)` hex), generated in
-`server.cjs` at startup (overridable via `BRAINSTORM_TOKEN` for deterministic
-tests):
-
-1. **URL carries it** as `?key=<token>`. The server already builds `url` in its
- `server-started` JSON (`server.cjs:351`) and writes it to `state/server-info`
- — appending `?key=` there means `start-server.sh` (greps and prints that
- JSON) and the skill (hands the user that URL) need **no change**.
-2. **Cookie bootstrap.** A valid `?key` on `/` sets
- `brainstorm-key-<port>=<token>; HttpOnly; SameSite=Strict; Path=/`. The
- browser then auto-attaches it to same-origin subresources (`/files/*`) and
- the WebSocket handshake, so the agent can write any URL style and it works,
- and `helper.js` needs no change. Cookie name is **per-port** to avoid the
- Jupyter multi-server collision (cookies aren't port-scoped).
- `SameSite=Strict` is safe for CDN/Unsplash content — that cookie is host-
- scoped, so outbound CDN requests never carry it; SameSite only governs
- requests back to our origin, which are all same-site.
-3. **Auth gate** = valid `?key` **OR** valid cookie (compared with
- `crypto.timingSafeEqual`) on `/`, `/files/*`, and the WS upgrade. Missing/bad
- key → friendly **403 HTML page** ("this page needs the full URL your coding
- agent gave you, including `?key=…`" — generic "coding agent", not "Claude",
- since this ships on Codex/Gemini/Copilot too). WS upgrade → destroy socket.
-
-The query token is the source of truth; the cookie is a convenience that never
-bears initial-auth load.
-
-**Blast radius.** `server.cjs` (all logic). `helper.js` optional one-liner
-(append `?key=` from `location.search` to the WS URL as a cookie-blocked
-fallback). `start-server.sh` none. `visual-companion.md` doc note (URL now has
-`?key=`; don't strip it). Tests updated to pass the token.
-
-### A2 — Host allowlist dropped; browser WS Origin retained
-
-Subsumed by A1. The secret key closes the WS-injection vector (#1014), the
-HTTP/WS DNS-rebinding read vector (PR #1553), and the cross-origin WS vector
-(PR #1110) in one mechanism, and unlike an allowlist it actually protects the
-remote-bind case. No `BRAINSTORM_ALLOWED_HOSTS` and no Host allowlist. The final
-implementation still checks browser WebSocket `Origin` after session auth so a
-cross-origin localhost tab cannot ride the companion cookie.
-
-### A3 — Server crashes on `null` / primitive WS payload
-
-**Problem.** `handleMessage` (`server.cjs:233`) does `JSON.parse(text)` then
-`if (event.choice)` at `server.cjs:243`. A client that sends the 4-byte text
-frame `null` yields `event === null`, and `null.choice` throws. The throw is
-**not** caught — `handleMessage` is called from the `socket.on('data')` handler
-(`server.cjs:207`) outside the `try/catch`, which only wraps `decodeFrame`. The
-result is an uncaught exception and process exit. Any local client can kill the
-server.
-
-**Change.** Guard the access: `if (event && event.choice)`. Minimal and exact —
-`JSON.parse` can't produce `undefined`, and primitives return `undefined` for
-`.choice` without throwing, so only `null` is the live hazard. (Avoid the
-broader fixes — a top-level `try/catch` or `process.on('uncaughtException')`
-would mask other bugs.)
-
-### A4 — Frame-length bound in `decodeFrame` (adjacent)
-
-Referenced by PR #1504 as #1446. The current code **already** bounds extended
-frame lengths: `MAX_FRAME_PAYLOAD_BYTES = 10MB` (`server.cjs:10`) is enforced at
-`server.cjs:58-67` before any `Buffer.alloc`. Action: verify #1446 against
-current `dev` and close if already resolved, rather than re-implementing.
-
----
-
-## B. Server robustness / correctness
-
-### B1 — macOS resource-fork dotfiles served as screen content
-
-**Problem.** The newest-screen selector filters on `f.endsWith('.html')` only
-(`server.cjs:127-128`). On macOS/ExFAT, `._screen.html` resource-fork files pass
-that filter and, being written alongside the real file, can sort newest — so the
-browser gets binary metadata instead of the mockup. Four read sites share the
-weak filter: `getNewestScreen` (`server.cjs:127`), `knownFiles` init
-(`server.cjs:279`), the `fs.watch` handler (`server.cjs:286`), and the `/files/`
-endpoint (`server.cjs:154-156`).
-
-**Change.** Reject dotfiles (`!f.startsWith('.')`) at all four sites. Covers
-`._*`, `.DS_Store`, etc.
-
-### B2 — `stop-server.sh` can kill a reused PID
-
-**Problem.** `stop-server.sh` reads the PID from `state/server.pid`
-(`stop-server.sh:20`) and `kill`s it (`:23`, escalating to `-9` at `:35`)
-without confirming the PID still belongs to our server. After a reboot or PID
-wraparound the file can point at an unrelated process, which we'd then SIGKILL.
-
-**Change.** Before signalling, verify ownership — the PID's command is `node`
-running our `server.cjs`, ideally matching this session. If ownership can't be
-proven, fail closed (report `stale_pid`, don't kill). Keep the existing
-`stopped` / `not_running` outputs for the real cases.
-
-### B3 — WebSocket client: silent reconnect, stale "Connected"
-
-**Problem.** `helper.js` reconnects on a fixed 1s timer (`helper.js:21-23`),
-has no `onerror` handler, never nulls `ws` on close, and never clears a pending
-reconnect timer. The frame's status element is hardcoded to "Connected" with the
-dot pinned to `var(--success)` (`frame-template.html:77,200`). When the laptop
-sleeps or the server restarts, the page shows "Connected" over a dead socket and
-queues events with no feedback.
-
-**Change.**
-- `helper.js`: exponential backoff (500ms → ×2 → cap 30s, reset on open);
- `onerror` delegating to `onclose`; `ws = null` on close; `clearTimeout` before
- reconnecting.
-- `frame-template.html`: drive the status dot from a `--status-color` custom
- property so JS can switch Connected (green) / Reconnecting (yellow) /
- Disconnected (red).
-
----
-
-## C. Lifecycle / timeout (issue #1237)
-
-### C1 — Idle timeout too short, not configurable, WS keeps process alive
-
-**Problem.** `IDLE_TIMEOUT_MS` is hardcoded to 30 minutes (`server.cjs:258`),
-enforced by the 60s lifecycle check (`server.cjs:329-332`). A single brainstorm
-question can sit longer than 30 min while the user thinks or steps away, so the
-server dies mid-session. Separately, `shutdown()` (`server.cjs:310-321`) calls
-`server.close()` but never closes the upgraded sockets in `clients`
-(`server.cjs:174`), so an open browser connection can keep the Node process
-alive past shutdown.
-
-**Change.**
-- Raise the default to 4 hours and make it configurable:
- `--idle-timeout-minutes` in `start-server.sh` → an env var → `IDLE_TIMEOUT_MS`,
- with validation against Node timer overflow.
-- Expose the effective timeout in the startup JSON / `state/server-info`.
-- In `shutdown()`, close every socket in `clients` so the process actually
- exits.
-
-### C2 — Server death is invisible
-
-**Problem.** When the server exits it writes `state/server-stopped` and removes
-`state/server-info` (`server.cjs:312-317`), and the skill is *told* to check
-those files (`visual-companion.md:108`) — but it's soft guidance the model skips,
-and the browser just shows a generic "can't be reached." The user diagnoses it
-manually; the agent keeps referring to a dead URL.
-
-**Change (two parts, independent of C1):**
-- **Browser-facing tombstone.** Leave something at the last-served URL that says
- "this companion expired — ask Claude to restart it" instead of a connection
- error. Options to weigh: `helper.js` rendering a banner when the socket stays
- down past backoff (works only while the page is loaded), vs. a more involved
- approach that keeps a minimal responder alive to serve a tombstone page.
-- **Harder skill check.** Tighten `visual-companion.md` / `SKILL.md` so
- "check `server-info`/`server-stopped` before referring to the URL or pushing a
- screen" is a required step, not a note. Keep it lightweight — possibly a
- one-line helper the agent always runs.
-
----
-
-## D. Features
-
-### D1 — Permanent opt-out of the visual companion (issue #892)
-
-**Problem.** The companion is offered as its own message every session
-(`SKILL.md:25,151-152`). A user who never wants it pays that round-trip — and
-HTML generation — every time. There's no way to say "never offer this."
-
-**Change.** Before the offer step, the skill checks a user-level setting and
-skips the offer entirely when opt-out is set.
-
-**Design choice open.** Mechanism isn't settled:
-- Env var (e.g. `SUPERPOWERS_VISUAL_COMPANION=off`) the skill is told to read —
- simplest, matches what the issue asks for, lives in `.zshrc`.
-- A plugin-settings file (`.claude/superpowers.local.md` frontmatter) — more
- structured, per-project capable, but heavier and project-scoped.
-- Reliability caveat from the issue: a separate "no-companion" skill competes on
- trigger words and isn't reliable — rejected.
-
-Pick the mechanism, then it's a small `SKILL.md` change plus a documented knob.
-
-### D2 — Free-text feedback from the browser (issue #957)
-
-**Problem.** The client only captures clicks on `[data-choice]`
-(`helper.js:36-62`). A user who wants to annotate a mockup ("wrong shade of
-blue") has to switch to the terminal, breaking the visual flow.
-
-**Change.** Add a feedback `<textarea>` whose submit emits
-`{"type":"feedback","text":...,"timestamp":...}` via the existing
-`window.brainstorm.send` path (`helper.js:82-85`).
-
-**Cross-cutting — server change required.** `handleMessage` only persists events
-when `event.choice` is truthy (`server.cjs:243`). A `feedback` event has no
-`choice`, so today it would be logged but **never written to `state/events`**,
-and the agent wouldn't see it. The persistence condition must also accept
-`feedback` events. Document the new event shape in `visual-companion.md`
-(Browser Events Format, `:247-259`). Decide the submit trigger (button vs blur
-vs both) and where the textarea renders (frame-level vs opt-in per screen).
-
-### D3 — Auto-open the companion URL (PR #759, issue #755)
-
-**Problem.** `start-server.sh` only prints the URL; the user opens it manually.
-In WSL2 especially, people expect the browser to open.
-
-**Change.** Best-effort opener after the `server-started` JSON is parsed:
-Windows/WSL → `rundll32.exe url.dll,FileProtocolHandler <url>`, macOS → `open`,
-Linux → `xdg-open` only when `DISPLAY`/`WAYLAND_DISPLAY` is set. Swallow
-failures, never block startup, keep echoing the URL. Document in
-`visual-companion.md`. (Consider an opt-out for headless/remote runs where
-popping a browser is wrong — ties into D1's config mechanism.)
-
-### D4 — Light/dark contrast helpers (PR #1683)
-
-**Problem.** Content fragments are wrapped in the OS-aware frame
-(`frame-template.html`). In dark mode, quick mockups often use white inline
-backgrounds while inheriting low-contrast frame text, making cards/panels hard
-to read.
-
-**Change.** Add `.light-surface` / `.dark-surface` helper classes plus a
-conservative fallback for common inline light backgrounds, and document them in
-`visual-companion.md`'s CSS reference. Pure CSS in `frame-template.html`.
-
----
-
-## E. Workshop / deferred / dropped
-
-### E1 — Hard-gate terminal-vs-HTML per question (PR #1037) — WORKSHOP
-
-The soft guidance already exists: "decide per-question," with browser-vs-terminal
-tests in `SKILL.md:156-161` and `visual-companion.md:5-25`. The complaint is that
-the model renders HTML for purely textual content (A/B lists, clarifying
-questions), wasting tokens and a turn. PR #1037 wraps the decision in a
-`<HARD-GATE>`. **Per Jesse, we'll workshop the wording/mechanism together** —
-this is behavior-shaping skill content and not specced here.
-
-### E2 — Move session state out of the working tree (issue #975 / PR #977) — DEFERRED
-
-Today `--project-dir` writes session state to `<project>/.superpowers/brainstorm/`
-(`start-server.sh:80-84`) and the skill tells the user to gitignore it
-(`visual-companion.md:58`). The ask is a `--state-dir` / `SUPERPOWERS_STATE_DIR`
-default outside the repo (XDG), keeping `--project-dir` as an alias.
-**Deferred by Jesse for now.** Captured so it isn't lost.
-
-### E3 — Vendor Alpine.js for interactive mockups (PR #1639) — DROPPED
-
-Adds a vendored Alpine build so mockups can be interactive (tabs, accordions,
-forms) without hand-rolled JS. **Dropped per Jesse** — we are not taking on a
-vendored third-party dependency in the companion runtime. The underlying need
-(interactive mockups) is not being pursued via this route.
-
-### E4 — Shell-lint warnings (PR #1677) — OPPORTUNISTIC
-
-SC2034 (and friends) in `start-server.sh` / `stop-server.sh`. Trivial; fold into
-B2/C1/D3 when we're already editing those scripts rather than as its own change.
-
----
-
-## Suggested grouping for implementation
-
-These cluster into a few coherent passes (each independently testable against
-`tests/brainstorm-server/`):
-
-1. **Security pass** (IN PROGRESS, branch `brainstorm-companion-session-key`) —
- A1 per-session key (supersedes A2) + A3 null-crash guard. Verify/close A4.
- *Highest priority.*
-2. **Lifecycle pass** — C1 + C2 together (both touch `shutdown()` and the
- server-death story).
-3. **Robustness pass** — B1, B2, B3 (independent, small).
-4. **Deferred feature pass** - D1, D2, D4 are not part of PR #1720. D3 is
- shipped through the `--open` flow.
-
-E1 is a separate workshop session. E2/E3 are out of scope for this round.
diff --git a/docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md b/docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md
deleted file mode 100644
index e290dde..0000000
--- a/docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md
+++ /dev/null
@@ -1,785 +0,0 @@
-# Visual Companion Auth Hardening Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries.
-
-**Architecture:** Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped `sessionStorage`, and navigates to a bare `/` screen URL. WebSockets require valid auth plus browser same-origin `Origin`, while `/files/*` uses realpath containment to prevent content-directory escapes.
-
-**Tech Stack:** Node.js built-ins (`http`, `fs`, `path`, `crypto`), zero runtime dependencies, existing `ws` test dependency, Bash start/stop scripts, repo shell lint script.
-
-**Important:** Do not commit during execution unless Drew explicitly asks. This repository's instructions override the generic plan template's commit cadence.
-
----
-
-## File Map
-
-- Modify: `skills/brainstorming/scripts/server.cjs`
- - Add bootstrap response.
- - Add shared security headers.
- - Add WebSocket Origin validation.
- - Add `/files/*` realpath containment.
-- Modify: `skills/brainstorming/scripts/helper.js`
- - Read the stored session key and append it to the WebSocket URL.
-- Modify: `tests/brainstorm-server/auth.test.js`
- - Add bootstrap, header, same-origin WS, cross-origin WS, and cookie/file auth regressions.
-- Modify: `tests/brainstorm-server/helper.test.js`
- - Add mocked-browser coverage for sessionStorage-backed WS URLs.
-- Modify: `tests/brainstorm-server/server.test.js`
- - Add symlink containment regression for `/files/*`.
-- Modify: `tests/brainstorm-server/lifecycle.test.js`
- - Make the start-server timeout flag test force background mode.
- - Add restart reconnect credential coverage if it fits the existing lifecycle helper.
-- Modify: `skills/brainstorming/scripts/start-server.sh`
- - Fix shell lint.
-- Modify: `skills/brainstorming/scripts/stop-server.sh`
- - Fix shell lint.
-- Modify: `.gitignore`
- - Add `.superpowers/`.
-- Optional docs update: `skills/brainstorming/visual-companion.md`
- - Mention bootstrap URL stripping and trusted same-origin screen JS if the code behavior changes need operator-facing explanation.
-
-## Task 1: Bootstrap Keyed Root Loads
-
-**Files:**
-- Modify: `tests/brainstorm-server/auth.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add RED tests for bootstrap behavior**
-
-In `tests/brainstorm-server/auth.test.js`, add tests after the existing valid-key root test:
-
-```js
- await test('GET / with valid query returns bootstrap instead of screen content', async () => {
- const res = await get('/', { key: TOKEN });
- assert.strictEqual(res.status, 200);
- assert(res.body.includes('sessionStorage'), 'bootstrap should store the session key in tab storage');
- assert(res.body.includes('location.replace'), 'bootstrap should navigate to the bare root URL');
- assert(!res.body.includes('Secret screen'), 'bootstrap must not serve screen HTML at the keyed URL');
- });
-
- await test('GET / with valid cookie serves the screen after bootstrap', async () => {
- const res = await get('/', { cookie: `${COOKIE_NAME}=${TOKEN}` });
- assert.strictEqual(res.status, 200);
- assert(res.body.includes('Secret screen'), 'cookie-authenticated bare root should serve the screen');
- assert(!res.body.includes('sessionStorage'), 'bare screen response should not be the bootstrap page');
- });
-```
-
-Keep the existing cookie test if present; merge assertions rather than duplicating the same test name.
-
-- [ ] **Step 2: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: the new bootstrap test fails because current `GET /?key=...` serves `Secret screen` directly and does not include the bootstrap `sessionStorage`/`location.replace` code.
-
-- [ ] **Step 3: Implement minimal bootstrap response**
-
-In `skills/brainstorming/scripts/server.cjs`, add a helper near the page constants:
-
-```js
-function bootstrapPage(key) {
- const jsonKey = JSON.stringify(String(key));
- return `<!DOCTYPE html>
-<html>
-<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
-<body>
-<script>
-sessionStorage.setItem('brainstorm-session-key', ${jsonKey});
-location.replace('/');
-</script>
-</body>
-</html>`;
-}
-```
-
-Then in `handleRequest`, after authorization and cookie setting but before serving screen HTML, detect a valid query key on root:
-
-```js
-function queryKey(url) {
- const q = url.indexOf('?');
- if (q < 0) return null;
- return new URLSearchParams(url.slice(q + 1)).get('key');
-}
-```
-
-Use it in `handleRequest`:
-
-```js
- const pathname = pathnameOf(req.url);
- const keyFromQuery = queryKey(req.url);
- if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
- res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
- res.end(bootstrapPage(keyFromQuery));
- return;
- }
-```
-
-This assumes Task 4 will introduce `securityHeaders`. If implementing Task 1 first, temporarily use:
-
-```js
- res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-```
-
-and replace it in Task 4.
-
-- [ ] **Step 4: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: all auth tests pass, including the new bootstrap tests.
-
-## Task 2: WebSocket Origin Enforcement
-
-**Files:**
-- Modify: `tests/brainstorm-server/auth.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add RED tests for same-origin and cross-origin WS**
-
-In `tests/brainstorm-server/auth.test.js`, extend `wsConnect` to accept an `origin` option:
-
-```js
-function wsConnect({ key, cookie, origin } = {}) {
- const url = `ws://localhost:${TEST_PORT}/` + (key !== undefined ? `?key=${key}` : '');
- const headers = {};
- if (cookie) headers['Cookie'] = cookie;
- if (origin) headers['Origin'] = origin;
- const ws = new WebSocket(url, Object.keys(headers).length ? { headers } : {});
- return new Promise((resolve) => {
- let settled = false;
- const done = (outcome) => { if (!settled) { settled = true; resolve({ outcome, ws }); } };
- ws.on('open', () => done('opened'));
- ws.on('error', () => done('rejected'));
- ws.on('close', () => done('rejected'));
- setTimeout(() => done('rejected'), 1500);
- });
-}
-```
-
-Then add:
-
-```js
- await test('WS upgrade with valid cookie and same-origin Origin opens', async () => {
- const { outcome, ws } = await wsConnect({
- cookie: `${COOKIE_NAME}=${TOKEN}`,
- origin: `http://localhost:${TEST_PORT}`
- });
- ws.close();
- assert.strictEqual(outcome, 'opened');
- });
-
- await test('WS upgrade with valid cookie but cross-origin Origin is rejected', async () => {
- const eventsFile = path.join(TEST_DIR, 'state', 'events');
- if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
-
- const { outcome, ws } = await wsConnect({
- cookie: `${COOKIE_NAME}=${TOKEN}`,
- origin: 'http://localhost:9999'
- });
- if (outcome === 'opened') {
- ws.send(JSON.stringify({ type: 'choice', choice: 'attacker-injected', text: 'local attacker probe' }));
- await sleep(300);
- }
- ws.close();
-
- assert.strictEqual(outcome, 'rejected', 'cross-origin browser WS must not open even with cookie');
- assert(!fs.existsSync(eventsFile), 'cross-origin WS must not write state/events');
- });
-```
-
-- [ ] **Step 2: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: cross-origin cookie WS test fails because current server accepts any cookie-authenticated WS regardless of Origin.
-
-- [ ] **Step 3: Implement Origin check**
-
-In `skills/brainstorming/scripts/server.cjs`, add:
-
-```js
-function isAllowedWebSocketOrigin(req) {
- const origin = req.headers.origin;
- if (!origin) return true; // non-browser clients still need the session key
- const host = req.headers.host;
- if (!host) return false;
- return origin === 'http://' + host;
-}
-```
-
-Then update `handleUpgrade`:
-
-```js
-function handleUpgrade(req, socket) {
- if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
-```
-
-- [ ] **Step 4: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: auth tests pass; cross-origin WS is rejected; same-origin and direct key WS still open.
-
-## Task 3: Helper Uses Stored Key For Reconnect
-
-**Files:**
-- Modify: `tests/brainstorm-server/helper.test.js`
-- Modify: `skills/brainstorming/scripts/helper.js`
-
-- [ ] **Step 1: Add RED test for WebSocket URL key**
-
-In `tests/brainstorm-server/helper.test.js`, add a mocked-browser test near the reconnect state-machine tests:
-
-```js
-test('uses sessionStorage key in the WebSocket URL when present', () => {
- const e = makeEnv();
- e.state.sessionKey = 'stored-key-abc';
- e.boot();
- assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777/?key=stored-key-abc');
-});
-```
-
-Update `makeEnv()` so the returned object exposes `sockets`, and the mock window includes sessionStorage:
-
-```js
- window: {
- location: { host: 'localhost:7777', reload() { state.reloads++; } },
- sessionStorage: { getItem: (key) => key === 'brainstorm-session-key' ? state.sessionKey : null }
- },
-```
-
-Also add a fallback test:
-
-```js
-test('uses cookie-only WebSocket URL when no sessionStorage key is present', () => {
- const e = makeEnv();
- e.state.sessionKey = null;
- e.boot();
- assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777');
-});
-```
-
-- [ ] **Step 2: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node helper.test.js
-```
-
-Expected: stored-key test fails because current helper uses `ws://localhost:7777`.
-
-- [ ] **Step 3: Implement stored-key WS URL**
-
-In `skills/brainstorming/scripts/helper.js`, replace:
-
-```js
- const WS_URL = 'ws://' + window.location.host;
-```
-
-with:
-
-```js
- function websocketUrl() {
- let key = null;
- try { key = window.sessionStorage && window.sessionStorage.getItem('brainstorm-session-key'); } catch (e) {}
- return 'ws://' + window.location.host + (key ? '/?key=' + encodeURIComponent(key) : '');
- }
-```
-
-Then replace:
-
-```js
- ws = new WebSocket(WS_URL);
-```
-
-with:
-
-```js
- ws = new WebSocket(websocketUrl());
-```
-
-- [ ] **Step 4: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node helper.test.js
-```
-
-Expected: helper tests pass.
-
-## Task 4: Security Headers
-
-**Files:**
-- Modify: `tests/brainstorm-server/auth.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add RED header tests**
-
-In `tests/brainstorm-server/auth.test.js`, add:
-
-```js
- await test('HTML responses include leak-reduction and anti-framing headers', async () => {
- const res = await get('/', { key: TOKEN });
- assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
- assert.strictEqual(res.headers['cache-control'], 'no-store');
- assert.strictEqual(res.headers['x-frame-options'], 'DENY');
- assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
- assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
- });
-
- await test('403 responses include leak-reduction and anti-framing headers', async () => {
- const res = await get('/');
- assert.strictEqual(res.status, 403);
- assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
- assert.strictEqual(res.headers['cache-control'], 'no-store');
- assert.strictEqual(res.headers['x-frame-options'], 'DENY');
- assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
- assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
- });
-```
-
-- [ ] **Step 2: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: header tests fail because current responses do not include these headers.
-
-- [ ] **Step 3: Implement shared header helper**
-
-In `skills/brainstorming/scripts/server.cjs`, add:
-
-```js
-function securityHeaders(headers = {}) {
- return {
- 'Referrer-Policy': 'no-referrer',
- 'Cache-Control': 'no-store',
- 'X-Frame-Options': 'DENY',
- 'Content-Security-Policy': "frame-ancestors 'none'",
- 'Cross-Origin-Resource-Policy': 'same-origin',
- ...headers
- };
-}
-```
-
-Update response writes in `handleRequest`:
-
-```js
-res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
-```
-
-```js
-res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
-```
-
-```js
-res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
-```
-
-For 404s:
-
-```js
-res.writeHead(404, securityHeaders());
-```
-
-- [ ] **Step 4: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: auth tests pass and header assertions are green.
-
-## Task 5: `/files/*` Realpath Containment
-
-**Files:**
-- Modify: `tests/brainstorm-server/server.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add RED symlink escape test**
-
-In `tests/brainstorm-server/server.test.js`, after the `/files/` empty-name test, add:
-
-```js
- await test('does not serve symlinks that escape content dir via /files/', async () => {
- const target = path.join(STATE_DIR, 'server-info');
- const link = path.join(CONTENT_DIR, 'linked-server-info.txt');
- try { fs.unlinkSync(link); } catch (e) {}
- fs.symlinkSync(target, link);
-
- const res = await fetch(`http://localhost:${TEST_PORT}/files/linked-server-info.txt`);
- assert.strictEqual(res.status, 404, 'symlink to state/server-info must not be served');
- assert(!res.body.includes('server-started'), 'response must not include server-info body');
- });
-```
-
-- [ ] **Step 2: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node server.test.js
-```
-
-Expected: symlink test fails because current `/files/*` follows symlinks and serves `server-info`.
-
-- [ ] **Step 3: Implement containment helper**
-
-In `skills/brainstorming/scripts/server.cjs`, add:
-
-```js
-function isRegularFileInsideContentDir(filePath) {
- let stat, realContentDir, realFilePath;
- try {
- stat = fs.lstatSync(filePath);
- if (stat.isSymbolicLink()) return false;
- if (!stat.isFile()) return false;
- realContentDir = fs.realpathSync(CONTENT_DIR);
- realFilePath = fs.realpathSync(filePath);
- } catch (e) {
- return false;
- }
- return realFilePath.startsWith(realContentDir + path.sep);
-}
-```
-
-Replace the `/files/*` guard with:
-
-```js
- if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
- res.writeHead(404, securityHeaders());
- res.end('Not found');
- return;
- }
-```
-
-- [ ] **Step 4: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node server.test.js
-```
-
-Expected: server tests pass, including symlink rejection.
-
-## Task 6: Restart Reconnect Regression
-
-**Files:**
-- Modify: `tests/brainstorm-server/lifecycle.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-- Modify: `skills/brainstorming/scripts/helper.js`
-
-- [ ] **Step 1: Add RED integration test for same key over WS after restart**
-
-In `tests/brainstorm-server/lifecycle.test.js`, add a test after the port/token persistence test:
-
-```js
- await test('stored key can authenticate WebSocket after same-port restart', async () => {
- const dir = fs.mkdtempSync('/tmp/bs-reconnect-');
- const portFile = path.join(dir, '.last-port');
- const tokenFile = path.join(dir, '.last-token');
- const env = { ...process.env, BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_TOKEN_FILE: tokenFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 };
-
- const a = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's1') } });
- let outA = ''; a.stdout.on('data', d => outA += d.toString());
- for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
- const infoA = firstServerStarted(outA);
- const keyA = new URL(infoA.url).searchParams.get('key');
- a.kill(); await sleep(400);
-
- const b = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's2') } });
- let outB = ''; b.stdout.on('data', d => outB += d.toString());
- for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
- const infoB = firstServerStarted(outB);
-
- const ws = new WebSocket(`ws://localhost:${infoB.port}/?key=${keyA}`, {
- headers: { Origin: `http://localhost:${infoB.port}` }
- });
- const opened = await new Promise(resolve => {
- ws.on('open', () => resolve(true));
- ws.on('error', () => resolve(false));
- setTimeout(() => resolve(false), 1500);
- });
-
- try {
- assert.strictEqual(infoB.port, infoA.port, 'restart should reuse same port');
- assert(opened, 'stored key should authenticate WS after restart');
- } finally {
- try { ws.close(); } catch (e) {}
- b.kill(); await sleep(100);
- fs.rmSync(dir, { recursive: true, force: true });
- }
- });
-```
-
-This test may already pass once Tasks 2 and 3 are implemented. If it passes before code changes, keep it as coverage but do not call it RED. The real browser reconnect behavior is primarily covered by Task 3 plus final manual/headless browser verification.
-
-- [ ] **Step 2: Verify behavior**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node lifecycle.test.js
-```
-
-Expected after Tasks 2 and 3: lifecycle tests pass. If this fails, fix the auth/restart path before continuing.
-
-## Task 7: Lifecycle Hang And Shell Lint
-
-**Files:**
-- Modify: `tests/brainstorm-server/lifecycle.test.js`
-- Modify: `skills/brainstorming/scripts/start-server.sh`
-- Modify: `skills/brainstorming/scripts/stop-server.sh`
-
-- [ ] **Step 1: Reproduce shell lint failure**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers
-scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
-```
-
-Expected current failure:
-
-```text
-SC2164: skills/brainstorming/scripts/start-server.sh line 128: cd "$SCRIPT_DIR"
-SC2034: skills/brainstorming/scripts/start-server.sh line 166: for i in {1..50}
-SC2034: skills/brainstorming/scripts/stop-server.sh line 57: for i in {1..20}
-```
-
-- [ ] **Step 2: Fix shell lint minimally**
-
-In `skills/brainstorming/scripts/start-server.sh`, change:
-
-```bash
-cd "$SCRIPT_DIR"
-```
-
-to:
-
-```bash
-cd "$SCRIPT_DIR" || exit 1
-```
-
-Change unused loop variables from `i` to `_` where they are not read:
-
-```bash
-for _ in {1..50}; do
-```
-
-In `skills/brainstorming/scripts/stop-server.sh`, change:
-
-```bash
-for i in {1..20}; do
-```
-
-to:
-
-```bash
-for _ in {1..20}; do
-```
-
-- [ ] **Step 3: Fix lifecycle start-server hang**
-
-In `tests/brainstorm-server/lifecycle.test.js`, update the `start-server.sh --idle-timeout-minutes sets the timeout` test command:
-
-```js
-const out = execFileSync('bash', [START, '--project-dir', dir, '--idle-timeout-minutes', '5', '--background'], { encoding: 'utf8' });
-```
-
-This keeps the test from hanging when `CODEX_CI` triggers start-server foreground mode.
-
-- [ ] **Step 4: Verify lint and lifecycle**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers
-scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
-cd tests/brainstorm-server
-node lifecycle.test.js
-```
-
-Expected: shell lint exits 0; lifecycle tests exit 0 without hanging.
-
-## Task 8: Gitignore Durable Companion State
-
-**Files:**
-- Modify: `.gitignore`
-
-- [ ] **Step 1: Verify current ignore gap**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers
-git check-ignore .superpowers/brainstorm/.last-token || true
-```
-
-Expected current output: no matching ignore rule.
-
-- [ ] **Step 2: Add ignore rule**
-
-Add this line to `.gitignore`:
-
-```gitignore
-.superpowers/
-```
-
-- [ ] **Step 3: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers
-git check-ignore .superpowers/brainstorm/.last-token
-```
-
-Expected output:
-
-```text
-.superpowers/brainstorm/.last-token
-```
-
-## Task 9: Full Automated Verification
-
-**Files:**
-- No code changes in this task.
-
-- [ ] **Step 1: Run focused suites**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-node auth.test.js
-node helper.test.js
-node server.test.js
-node lifecycle.test.js
-```
-
-Expected: all four commands exit 0.
-
-- [ ] **Step 2: Run full brainstorm-server suite**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-npm test
-```
-
-Expected: all tests pass, including ws-protocol, helper, auth, server, lifecycle, and stop-server.
-
-- [ ] **Step 3: Repeat suite for lifecycle/watch flake**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
-for i in 1 2 3; do npm test || exit 1; done
-```
-
-Expected: all three repeats pass without hanging.
-
-- [ ] **Step 4: Run shell lint**
-
-Run:
-
-```bash
-cd /Users/drewritter/prime-rad/superpowers
-scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
-```
-
-Expected: exits 0.
-
-## Task 10: Re-run Security Probes
-
-**Files:**
-- No code changes in this task.
-
-- [ ] **Step 1: Recreate the cross-origin attacker probe**
-
-Use the previous scratch probe if available:
-
-```bash
-node /tmp/superpowers-pr1720-security-drewritter/probe-pr1720.cjs
-```
-
-If the scratch probe is unavailable, recreate a minimal probe under `/tmp` that:
-
-- starts the companion with a fixed token
-- loads the keyed URL in headless Chrome
-- starts an attacker page on a different localhost port
-- attempts `new WebSocket('ws://localhost:<companion-port>/')`
-- sends `{"type":"choice","choice":"attacker-injected"}`
-- checks `state/events`
-
-Expected after fixes:
-
-- keyless and wrong-key HTTP still return 403
-- same-origin helper reaches Connected
-- cross-origin WebSocket does not open
-- `state/events` does not contain `attacker-injected`
-- symlink-to-`server-info` returns 404
-- keyed browser load ends on bare `/`
-
-- [ ] **Step 2: Re-run manual/browser flow only after automated probes pass**
-
-Manual flow:
-
-1. start the companion with `--project-dir --open`
-2. push a screen
-3. confirm URL strips to `/`
-4. confirm status reaches Connected
-5. click a choice and verify `state/events`
-6. stop and restart same project
-7. verify the open tab reconnects automatically
-
-Expected: all steps pass without manual URL reload.
-
-## Self-Review Checklist
-
-- Spec coverage: every design requirement maps to at least one task.
-- Placeholder scan: this plan contains no unresolved placeholder markers or unspecified edge-case steps.
-- TDD order: every production change task starts with a focused failing test or a command that demonstrates the current failure.
-- Trust model: the plan preserves trusted same-origin screen JavaScript and future same-origin vendored libraries.
-- No-commit rule: execution does not commit unless Drew explicitly asks.
diff --git a/docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md b/docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md
deleted file mode 100644
index eec99e5..0000000
--- a/docs/superpowers/plans/2026-06-11-visual-companion-final-hardening-fixup.md
+++ /dev/null
@@ -1,1126 +0,0 @@
-# Visual Companion Final Hardening Fixup Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Finish PR #1720's final hardening fixup with test-first changes, clean rebase state, and reviewer-ready evidence.
-
-**Spec:** `docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md`
-
-**Architecture:** Keep the companion zero-dependency and local-first. Add focused guards to the existing server and shell scripts: root screen selection reuses the `/files/*` containment guard, fallback token handling tracks token source, and lifecycle shutdown uses a per-start command-line instance id for ownership proof.
-
-**Tech Stack:** Node.js built-ins (`http`, `fs`, `path`, `crypto`), existing `ws` test dependency, Bash scripts, Git Bash on Windows, `gh` CLI for PR metadata.
-
-**Commit discipline:** Each task includes a suggested commit. When using subagent-driven execution, the orchestrator reviews the worker diff, runs the task verification, and performs the commit.
-
----
-
-## File Map
-
-- Modify: `skills/brainstorming/scripts/server.cjs`
- - Filter root screen candidates through `isRegularFileInsideContentDir()`.
- - Track token source and rotate or fail closed on fallback.
-- Modify: `skills/brainstorming/scripts/start-server.sh`
- - Generate `state/server-instance-id`.
- - Pass `--brainstorm-server-id=<id>` after `server.cjs`.
-- Modify: `skills/brainstorming/scripts/stop-server.sh`
- - Require exact instance-id argv proof before signalling a PID.
- - Remove stale `server.pid` and `server-instance-id` on stale/stopped outcomes.
-- Modify: `tests/brainstorm-server/server.test.js`
- - Add fixed-port startup guard.
- - Add skip-aware test harness for symlink capability.
- - Add root symlink and hardlink escape regressions.
-- Modify: `tests/brainstorm-server/auth.test.js`
- - Add fixed-port startup guard.
-- Modify: `tests/brainstorm-server/lifecycle.test.js`
- - Add fallback token rotation, explicit-token fail-closed, and fallback-key rejection regressions.
-- Modify: `tests/brainstorm-server/stop-server.test.sh`
- - Add top-level cleanup trap.
- - Add positive and negative server-instance-id ownership tests.
-- Modify: `tests/brainstorm-server/start-server.test.sh`
- - Assert Windows-like fake-node path receives exact server id argv and writes a valid id file.
-- Modify: `tests/brainstorm-server/windows-lifecycle.test.sh`
- - Pass server id argv for direct Node stop-server coverage.
- - Add Windows fake-node assertion for the id argv.
-- Modify: `skills/brainstorming/visual-companion.md`
- - Add `--open` to platform commands that should preserve auto-open behavior.
-- Modify: `docs/superpowers/plans/2026-06-09-visual-companion-issues.md`
- - Reconcile shipped scope, WS Origin wording, default timeout, and deferred feature items.
-- Update outside tracked files: PR #1720 body
- - Record post-rebase diff state, RED/GREEN evidence, macOS/Windows verification, manual browser smoke, and external eval evidence.
-
-## Task 0: Rebase And Baseline State
-
-**Files:**
-- No source edits
-- Verification target: git branch state
-
-- [ ] **Step 1: Fetch current dev**
-
-Run:
-
-```bash
-git fetch origin dev
-```
-
-Expected: command exits 0.
-
-- [ ] **Step 2: Rebase onto current dev**
-
-Run:
-
-```bash
-git rebase origin/dev
-```
-
-Expected: command exits 0, or stops only on conflicts that must be resolved by taking `origin/dev` for `evals`.
-
-- [ ] **Step 3: Resolve an evals conflict by taking dev**
-
-If the rebase stops on `evals`, run:
-
-```bash
-git restore --source=origin/dev --staged --worktree evals
-git add evals
-git rebase --continue
-```
-
-Expected: rebase continues. After the rebase, `git diff --name-only origin/dev...HEAD -- evals` prints nothing.
-
-- [ ] **Step 4: Record baseline status**
-
-Run:
-
-```bash
-git status --short --branch
-git diff --name-only origin/dev...HEAD -- evals
-```
-
-Expected: status shows the branch on top of `origin/dev`; second command prints no paths.
-
-## Task 1: Root Screen Containment
-
-**Files:**
-- Modify: `tests/brainstorm-server/server.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add fixed-port guard and skip-aware test helper**
-
-In `tests/brainstorm-server/server.test.js`, add this helper after `waitForServer()`:
-
-```js
-class SkipTest extends Error {
- constructor(message) {
- super(message);
- this.skip = true;
- }
-}
-
-function skip(message) {
- throw new SkipTest(message);
-}
-
-function serverStartedMessage(out) {
- const line = out.trim().split('\n').find(l => l.includes('server-started'));
- assert(line, 'server-started JSON should be present');
- return JSON.parse(line);
-}
-
-function assertStartedOnExpectedPort(out) {
- const msg = serverStartedMessage(out);
- assert.strictEqual(
- msg.port,
- TEST_PORT,
- `server.test.js expected fixed port ${TEST_PORT}, got ${msg.port}; fixed-port tests must not run through fallback`
- );
- return msg;
-}
-
-function ensureSymlinkWorks(target, link) {
- try {
- fs.symlinkSync(target, link);
- fs.unlinkSync(link);
- } catch (e) {
- try { fs.unlinkSync(link); } catch (ignore) {}
- skip(`symlink creation unavailable on this host: ${e.message}`);
- }
-}
-```
-
-Then change the startup section from:
-
-```js
- const { stdout: initialStdout } = await waitForServer(server);
- let passed = 0;
- let failed = 0;
-```
-
-to:
-
-```js
- const { stdout: initialStdout } = await waitForServer(server);
- assertStartedOnExpectedPort(initialStdout);
- let passed = 0;
- let failed = 0;
- let skipped = 0;
-```
-
-Change the `test()` helper catch block to handle skips:
-
-```js
- }).catch(e => {
- if (e && e.skip) {
- console.log(` SKIP: ${name}`);
- console.log(` ${e.message}`);
- skipped++;
- return;
- }
- console.log(` FAIL: ${name}`);
- console.log(` ${e.message}`);
- failed++;
- });
-```
-
-Change the summary line to:
-
-```js
- console.log(`\n--- Results: ${passed} passed, ${failed} failed, ${skipped} skipped ---`);
-```
-
-- [ ] **Step 2: Make the existing `/files/*` symlink test skip-capable**
-
-Replace the setup inside `does not serve symlinks that escape content dir via /files/` with:
-
-```js
- const target = path.join(STATE_DIR, 'server-info');
- const link = path.join(CONTENT_DIR, 'linked-server-info.txt');
- try { fs.unlinkSync(link); } catch (e) {}
- ensureSymlinkWorks(target, link);
- fs.symlinkSync(target, link);
-```
-
-Expected behavior: hosts that cannot create usable symlinks skip only this assertion.
-
-- [ ] **Step 3: Add RED tests for root symlink and hardlink escapes**
-
-Add these tests after the existing `/files/*` hardlink test:
-
-```js
- await test('does not serve symlinks that escape content dir via root screen selection', async () => {
- const target = path.join(STATE_DIR, 'server-info');
- const link = path.join(CONTENT_DIR, 'root-linked-server-info.html');
- try { fs.unlinkSync(link); } catch (e) {}
- ensureSymlinkWorks(target, link);
- fs.symlinkSync(target, link);
- const future = new Date(Date.now() + 2000);
- fs.utimesSync(target, future, future);
- await sleep(300);
-
- const res = await fetch(`http://localhost:${TEST_PORT}/`);
- assert.strictEqual(res.status, 200);
- assert(!res.body.includes('"type":"server-started"'), 'root screen must not serve state/server-info through a symlink');
- assert(!res.body.includes('"state_dir"'), 'root screen must not include server-info body');
- });
-
- await test('does not serve hard links that escape content dir via root screen selection', async () => {
- const target = path.join(STATE_DIR, 'server-info');
- const link = path.join(CONTENT_DIR, 'root-hard-linked-server-info.html');
- try { fs.unlinkSync(link); } catch (e) {}
- try {
- fs.linkSync(target, link);
- } catch (e) {
- skip(`hardlink creation unavailable on this host: ${e.message}`);
- }
- const linkStat = fs.lstatSync(link);
- if (linkStat.nlink <= 1) {
- skip(`hardlink nlink did not expose multiple links: ${linkStat.nlink}`);
- }
- const future = new Date(Date.now() + 3000);
- fs.utimesSync(target, future, future);
- await sleep(300);
-
- const res = await fetch(`http://localhost:${TEST_PORT}/`);
- assert.strictEqual(res.status, 200);
- assert(!res.body.includes('"type":"server-started"'), 'root screen must not serve state/server-info through a hardlink');
- assert(!res.body.includes('"state_dir"'), 'root screen must not include server-info body');
- });
-```
-
-- [ ] **Step 4: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node server.test.js
-```
-
-Expected: at least one new root containment test fails before the production fix because root screen selection can read `state/server-info`.
-
-- [ ] **Step 5: Implement root containment**
-
-In `skills/brainstorming/scripts/server.cjs`, replace `getNewestScreen()` with:
-
-```js
-function getNewestScreen() {
- const files = fs.readdirSync(CONTENT_DIR)
- .filter(f => !f.startsWith('.') && f.endsWith('.html'))
- .map(f => {
- const fp = path.join(CONTENT_DIR, f);
- if (!isRegularFileInsideContentDir(fp)) return null;
- return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
- })
- .filter(Boolean)
- .sort((a, b) => b.mtime - a.mtime);
- return files.length > 0 ? files[0].path : null;
-}
-```
-
-- [ ] **Step 6: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node server.test.js
-```
-
-Expected: root symlink and supported hardlink tests pass or skip only for unsupported host capabilities. Existing `/files/*` containment tests remain green.
-
-- [ ] **Step 7: Commit**
-
-Run:
-
-```bash
-git add tests/brainstorm-server/server.test.js skills/brainstorming/scripts/server.cjs
-git commit -m "Harden root screen containment"
-```
-
-## Task 2: Fallback Token Isolation
-
-**Files:**
-- Modify: `tests/brainstorm-server/lifecycle.test.js`
-- Modify: `skills/brainstorming/scripts/server.cjs`
-
-- [ ] **Step 1: Add HTTP status helper**
-
-In `tests/brainstorm-server/lifecycle.test.js`, add this helper after `openCaptureCommand()`:
-
-```js
-function httpStatus(port, key) {
- return new Promise(resolve => {
- const pathWithKey = key ? '/?key=' + encodeURIComponent(key) : '/';
- require('http')
- .get({ hostname: '127.0.0.1', port, path: pathWithKey }, res => {
- res.resume();
- resolve(res.statusCode);
- })
- .on('error', () => resolve(0));
- });
-}
-```
-
-- [ ] **Step 2: Add RED test for persisted-token fallback rotation**
-
-Add this test after `falls back to a random port when the preferred port is taken`:
-
-```js
- await test('fallback with persisted token generates a fresh unpersisted key', async () => {
- const dir = fs.mkdtempSync('/tmp/bs-port-');
- const portFile = path.join(dir, '.last-port');
- const tokenFile = path.join(dir, '.last-token');
- const preferredToken = 'abababababababababababababababab';
- let a = null, b = null;
-
- try {
- a = spawn('node', [SERVER], {
- env: {
- ...process.env,
- BRAINSTORM_DIR: path.join(dir, 'a'),
- BRAINSTORM_PORT: 3422,
- BRAINSTORM_TOKEN: preferredToken,
- BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
- }
- });
- let outA = ''; a.stdout.on('data', d => outA += d.toString());
- for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
- assert(outA.includes('server-started'), 'preferred-port server should start');
-
- fs.writeFileSync(portFile, '3422');
- fs.writeFileSync(tokenFile, preferredToken, { mode: 0o600 });
-
- b = spawn('node', [SERVER], {
- env: {
- ...process.env,
- BRAINSTORM_DIR: path.join(dir, 'b'),
- BRAINSTORM_PORT_FILE: portFile,
- BRAINSTORM_TOKEN_FILE: tokenFile,
- BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
- }
- });
- let outB = ''; b.stdout.on('data', d => outB += d.toString());
- for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
- const infoB = firstServerStarted(outB);
- const fallbackKey = new URL(infoB.url).searchParams.get('key');
- const persistedAfter = fs.readFileSync(tokenFile, 'utf8').trim();
- const originalStatus = await httpStatus(3422, fallbackKey);
-
- assert.notStrictEqual(infoB.port, 3422, 'fallback should use a different port');
- assert.notStrictEqual(fallbackKey, preferredToken, 'fallback must not reuse persisted key');
- assert.strictEqual(persistedAfter, preferredToken, 'fallback must not overwrite .last-token');
- assert.strictEqual(originalStatus, 403, 'fallback key must not authenticate to original server');
- } finally {
- await killAndWait(a);
- await killAndWait(b);
- fs.rmSync(dir, { recursive: true, force: true });
- }
- });
-```
-
-- [ ] **Step 3: Add RED test for explicit-token fallback fail-closed**
-
-Add this test immediately after the persisted-token fallback test:
-
-```js
- await test('fallback with explicit BRAINSTORM_TOKEN fails closed', async () => {
- const dir = fs.mkdtempSync('/tmp/bs-port-');
- const portFile = path.join(dir, '.last-port');
- const explicitToken = 'cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd';
- let a = null, b = null;
-
- try {
- a = spawn('node', [SERVER], {
- env: {
- ...process.env,
- BRAINSTORM_DIR: path.join(dir, 'a'),
- BRAINSTORM_PORT: 3423,
- BRAINSTORM_TOKEN: explicitToken,
- BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
- }
- });
- let outA = ''; a.stdout.on('data', d => outA += d.toString());
- for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
- assert(outA.includes('server-started'), 'preferred-port server should start');
-
- fs.writeFileSync(portFile, '3423');
- b = spawn('node', [SERVER], {
- env: {
- ...process.env,
- BRAINSTORM_DIR: path.join(dir, 'b'),
- BRAINSTORM_PORT_FILE: portFile,
- BRAINSTORM_TOKEN: explicitToken,
- BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
- }
- });
- let outB = ''; let errB = '';
- b.stdout.on('data', d => outB += d.toString());
- b.stderr.on('data', d => errB += d.toString());
- for (let i = 0; i < 60 && !outB.includes('server-started') && b.exitCode === null; i++) await sleep(50);
- const exited = await waitForExit(b, 1500);
-
- assert(exited, 'explicit-token fallback process should exit');
- assert.notStrictEqual(b.exitCode, 0, 'explicit-token fallback should fail non-zero');
- assert(!outB.includes('server-started'), 'explicit-token fallback must not start on a random port');
- assert(/BRAINSTORM_TOKEN/.test(errB), `stderr should explain explicit token fallback refusal, got: ${errB}`);
- } finally {
- await killAndWait(a);
- await killAndWait(b);
- fs.rmSync(dir, { recursive: true, force: true });
- }
- });
-```
-
-- [ ] **Step 4: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node lifecycle.test.js
-```
-
-Expected: persisted-token fallback test fails because fallback reuses `.last-token`, and explicit-token fallback test fails because fallback currently starts.
-
-- [ ] **Step 5: Track token source in production code**
-
-In `skills/brainstorming/scripts/server.cjs`, replace the current `const TOKEN = (() => { ... })();` block with:
-
-```js
-function generateToken() {
- return crypto.randomBytes(32).toString('hex');
-}
-
-function initialToken() {
- if (process.env.BRAINSTORM_TOKEN) {
- return { value: process.env.BRAINSTORM_TOKEN, source: 'env' };
- }
- if (TOKEN_FILE) {
- try {
- const t = fs.readFileSync(TOKEN_FILE, 'utf-8').trim();
- if (/^[0-9a-f]{32,}$/i.test(t)) return { value: t, source: 'file' };
- } catch (e) { /* no prior token recorded */ }
- }
- return { value: generateToken(), source: 'generated' };
-}
-
-const tokenInfo = initialToken();
-let TOKEN = tokenInfo.value;
-let tokenSource = tokenInfo.source;
-```
-
-- [ ] **Step 6: Rotate or fail closed on EADDRINUSE fallback**
-
-In the `server.on('error', ...)` handler, replace the `EADDRINUSE` branch with:
-
-```js
- if (err.code === 'EADDRINUSE' && !triedFallback) {
- if (tokenSource === 'env') {
- console.error('Server failed to bind: preferred port is in use and BRAINSTORM_TOKEN is set; refusing fallback with explicit token');
- process.exit(1);
- }
- triedFallback = true;
- PORT = randomPort();
- if (tokenSource === 'file') {
- TOKEN = generateToken();
- tokenSource = 'generated-fallback';
- }
- server.listen(PORT, HOST, onListen);
- } else {
-```
-
-- [ ] **Step 7: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node lifecycle.test.js
-```
-
-Expected: all lifecycle tests pass, including fallback token rotation and explicit-token fail-closed.
-
-- [ ] **Step 8: Commit**
-
-Run:
-
-```bash
-git add tests/brainstorm-server/lifecycle.test.js skills/brainstorming/scripts/server.cjs
-git commit -m "Isolate companion fallback tokens"
-```
-
-## Task 3: Stop-Server Instance-Id Ownership
-
-**Files:**
-- Modify: `tests/brainstorm-server/stop-server.test.sh`
-- Modify: `skills/brainstorming/scripts/start-server.sh`
-- Modify: `skills/brainstorming/scripts/stop-server.sh`
-
-- [ ] **Step 1: Add cleanup tracking and id helpers to stop-server tests**
-
-In `tests/brainstorm-server/stop-server.test.sh`, after `PASS=0; FAIL=0`, add:
-
-```bash
-PIDS=()
-DIRS=()
-
-cleanup() {
- for pid in "${PIDS[@]}"; do
- kill -9 "$pid" 2>/dev/null || true
- wait "$pid" 2>/dev/null || true
- done
- for dir in "${DIRS[@]}"; do
- rm -rf "$dir"
- done
-}
-trap cleanup EXIT
-
-track_dir() { DIRS+=("$1"); }
-track_pid() { PIDS+=("$1"); }
-new_server_id() {
- printf 'testid%026d\n' "$RANDOM"
-}
-```
-
-When each test creates a `SESS="$(mktemp -d)"`, immediately add:
-
-```bash
-track_dir "$SESS"
-```
-
-When a test starts `UNRELATED`, `SRV`, or `IMPOSTOR`, immediately add the
-matching tracking call:
-
-```bash
-track_pid "$UNRELATED"
-track_pid "$SRV"
-track_pid "$IMPOSTOR"
-```
-
-- [ ] **Step 2: Add RED ownership tests**
-
-Replace the current real-server and impostor sections with these cases:
-
-```bash
-# --- Test 2: a real brainstorm server with matching instance id IS stopped ---
-SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/content" "$SESS/state"
-SERVER_ID="$(new_server_id)"
-printf '%s\n' "$SERVER_ID" > "$SESS/state/server-instance-id"
-BRAINSTORM_DIR="$SESS" BRAINSTORM_PORT=3399 node "$SERVER" "--brainstorm-server-id=$SERVER_ID" > /dev/null 2>&1 &
-SRV=$!
-track_pid "$SRV"
-disown "$SRV" 2>/dev/null || true
-for _ in $(seq 1 40); do kill -0 "$SRV" 2>/dev/null && break; sleep 0.1; done
-sleep 0.4
-echo "$SRV" > "$SESS/state/server.pid"
-OUT="$("$STOP" "$SESS")"
-sleep 0.3
-if kill -0 "$SRV" 2>/dev/null; then
- bad "real brainstorm server still running after stop" "$OUT"
-else
- case "$OUT" in
- *stopped*) ok "real brainstorm server with matching instance id is stopped" ;;
- *) bad "server stopped but status was not 'stopped'" "$OUT" ;;
- esac
-fi
-
-# --- Test 4: a node server.cjs impostor with missing instance id is spared ---
-SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
-( exec -a "node server.cjs" sleep 600 ) &
-IMPOSTOR=$!
-track_pid "$IMPOSTOR"
-disown "$IMPOSTOR" 2>/dev/null || true
-echo "$IMPOSTOR" > "$SESS/state/server.pid"
-OUT="$("$STOP" "$SESS")"
-if kill -0 "$IMPOSTOR" 2>/dev/null; then
- case "$OUT" in
- *stale_pid*) ok "missing instance id leaves node server.cjs impostor alone" ;;
- *) bad "impostor survived but status was not stale_pid" "$OUT" ;;
- esac
-else
- bad "killed a node server.cjs impostor with missing instance id" "$OUT"
-fi
-
-# --- Test 5: a node server.cjs impostor with wrong instance id is spared ---
-SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
-EXPECTED_ID="$(new_server_id)"
-WRONG_ID="$(new_server_id)"
-printf '%s\n' "$EXPECTED_ID" > "$SESS/state/server-instance-id"
-( exec -a "node server.cjs --brainstorm-server-id=$WRONG_ID" sleep 600 ) &
-IMPOSTOR=$!
-track_pid "$IMPOSTOR"
-disown "$IMPOSTOR" 2>/dev/null || true
-echo "$IMPOSTOR" > "$SESS/state/server.pid"
-OUT="$("$STOP" "$SESS")"
-if kill -0 "$IMPOSTOR" 2>/dev/null; then
- case "$OUT" in
- *stale_pid*) ok "wrong instance id leaves node server.cjs impostor alone" ;;
- *) bad "wrong-id impostor survived but status was not stale_pid" "$OUT" ;;
- esac
-else
- bad "killed a node server.cjs impostor with wrong instance id" "$OUT"
-fi
-
-# --- Test 6: malformed instance id is fail-closed ---
-SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
-printf '%s\n' 'bad id with spaces' > "$SESS/state/server-instance-id"
-( exec -a "node server.cjs --brainstorm-server-id=bad-id-with-spaces" sleep 600 ) &
-IMPOSTOR=$!
-track_pid "$IMPOSTOR"
-disown "$IMPOSTOR" 2>/dev/null || true
-echo "$IMPOSTOR" > "$SESS/state/server.pid"
-OUT="$("$STOP" "$SESS")"
-if kill -0 "$IMPOSTOR" 2>/dev/null; then
- case "$OUT" in
- *stale_pid*) ok "malformed instance id is fail-closed" ;;
- *) bad "malformed-id impostor survived but status was not stale_pid" "$OUT" ;;
- esac
-else
- bad "killed process despite malformed instance id" "$OUT"
-fi
-```
-
-Keep the unrelated PID and missing PID tests.
-
-- [ ] **Step 3: Verify RED**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers
-bash tests/brainstorm-server/stop-server.test.sh
-```
-
-Expected: matching-instance-id real server is reported `stale_pid` before implementation, and one of the impostor cases may be killed by the old command-name proof.
-
-- [ ] **Step 4: Generate and pass instance id in start-server**
-
-In `skills/brainstorming/scripts/start-server.sh`, after `LOG_FILE="${STATE_DIR}/server.log"`, add:
-
-```bash
-SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
-```
-
-After `mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"`, add:
-
-```bash
-SERVER_ID=""
-if [[ -r /dev/urandom ]]; then
- SERVER_ID="$(od -An -N24 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || true)"
-fi
-if ! [[ "$SERVER_ID" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
- SERVER_ID="$(printf '%08x%08x%08x%08x' "$$" "$(date +%s)" "${RANDOM:-0}" "${RANDOM:-0}")"
-fi
-printf '%s\n' "$SERVER_ID" > "$SERVER_ID_FILE"
-chmod 600 "$SERVER_ID_FILE" 2>/dev/null || true
-```
-
-Update both Node launch commands to pass the argv:
-
-```bash
-env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" &
-```
-
-and:
-
-```bash
-nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" > "$LOG_FILE" 2>&1 &
-```
-
-- [ ] **Step 5: Require instance id in stop-server**
-
-In `skills/brainstorming/scripts/stop-server.sh`, add:
-
-```bash
-SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
-```
-
-Replace `is_brainstorm_server()` with:
-
-```bash
-read_expected_server_id() {
- [[ -f "$SERVER_ID_FILE" ]] || return 1
- local id
- id="$(tr -d '\r\n' < "$SERVER_ID_FILE" 2>/dev/null || true)"
- [[ "$id" =~ ^[A-Za-z0-9_-]{32,64}$ ]] || return 1
- printf '%s\n' "$id"
-}
-
-command_line_for_pid() {
- local pid="$1"
- if [[ -r "/proc/$pid/cmdline" ]]; then
- tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null || true
- return 0
- fi
- ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true
-}
-
-command_has_server_id() {
- local pid="$1"
- local expected="$2"
- local expected_arg="--brainstorm-server-id=$expected"
- if [[ -r "/proc/$pid/cmdline" ]]; then
- local arg
- while IFS= read -r -d '' arg; do
- [[ "$arg" == "$expected_arg" ]] && return 0
- done < "/proc/$pid/cmdline"
- return 1
- fi
- local command_line
- command_line="$(command_line_for_pid "$pid")"
- [[ -n "$command_line" ]] || return 1
- case " $command_line " in
- *" $expected_arg "*) return 0 ;;
- *) return 1 ;;
- esac
-}
-
-is_brainstorm_server() {
- kill -0 "$1" 2>/dev/null || return 1
- local expected_id
- expected_id="$(read_expected_server_id)" || return 1
- command_has_server_id "$1" "$expected_id" || return 1
- return 0
-}
-```
-
-In the stale PID branch, remove both metadata files:
-
-```bash
- rm -f "$PID_FILE" "$SERVER_ID_FILE"
-```
-
-In the stopped branch, change the cleanup line to:
-
-```bash
- rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
-```
-
-- [ ] **Step 6: Verify GREEN**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers
-bash tests/brainstorm-server/stop-server.test.sh
-```
-
-Expected: real matching-id server stops, impostors survive, and all stale cases return `stale_pid`.
-
-- [ ] **Step 7: Commit**
-
-Run:
-
-```bash
-git add tests/brainstorm-server/stop-server.test.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh
-git commit -m "Harden companion stop ownership proof"
-```
-
-## Task 4: Platform And Fixed-Port Test Hardening
-
-**Files:**
-- Modify: `tests/brainstorm-server/auth.test.js`
-- Modify: `tests/brainstorm-server/start-server.test.sh`
-- Modify: `tests/brainstorm-server/windows-lifecycle.test.sh`
-
-- [ ] **Step 1: Add fixed-port guard to auth tests**
-
-In `tests/brainstorm-server/auth.test.js`, add this helper after `waitForServer()`:
-
-```js
-function serverStartedMessage(out) {
- const line = out.trim().split('\n').find(l => l.includes('server-started'));
- assert(line, 'server-started JSON should be present');
- return JSON.parse(line);
-}
-
-function assertStartedOnExpectedPort(out) {
- const msg = serverStartedMessage(out);
- assert.strictEqual(
- msg.port,
- TEST_PORT,
- `auth.test.js expected fixed port ${TEST_PORT}, got ${msg.port}; fixed-port tests must not run through fallback`
- );
- return msg;
-}
-```
-
-After `const { stdout: initialStdout } = await waitForServer(server);`, add:
-
-```js
- assertStartedOnExpectedPort(initialStdout);
-```
-
-- [ ] **Step 2: Verify auth fixed-port guard**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node auth.test.js
-```
-
-Expected: auth tests pass on a free `3335`, and would fail clearly if fallback occurred.
-
-- [ ] **Step 3: Add start-server id argv assertion**
-
-In `tests/brainstorm-server/start-server.test.sh`, change the first fake node body to:
-
-```bash
-cat > "$TEST_DIR/fake-bin/node" <<'EOF'
-#!/usr/bin/env bash
-echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
-echo "CAPTURED_ARGV=$*"
-exit 0
-EOF
-```
-
-After the owner PID assertion, add:
-
-```bash
-captured_argv=$(echo "$captured" | grep "CAPTURED_ARGV=" | head -1 | sed 's/CAPTURED_ARGV=//')
-if echo "$captured_argv" | grep -Eq -- '--brainstorm-server-id=[A-Za-z0-9_-]{32,64}'; then
- pass "passes shell-safe server instance id argv"
-else
- fail "passes shell-safe server instance id argv" \
- "expected --brainstorm-server-id=<safe id>, got: $captured_argv"
-fi
-
-server_id_file=$(find "$TEST_DIR/project/.superpowers/brainstorm" -name server-instance-id -print 2>/dev/null | head -1)
-server_id_value=""
-if [[ -n "$server_id_file" ]]; then
- server_id_value="$(tr -d '\r\n' < "$server_id_file")"
-fi
-if [[ "$server_id_value" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
- pass "writes shell-safe server-instance-id state file"
-else
- fail "writes shell-safe server-instance-id state file" \
- "expected valid id in state, got '$server_id_value'"
-fi
-```
-
-- [ ] **Step 4: Add Windows lifecycle id argv assertions**
-
-In `tests/brainstorm-server/windows-lifecycle.test.sh`, change the Test 2 fake node body to:
-
-```bash
-cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
-#!/usr/bin/env bash
-echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
-echo "CAPTURED_ARGV=$*"
-exit 0
-FAKENODE
-```
-
-After the owner PID check in Test 2, add:
-
-```bash
-captured_argv=$(echo "$captured" | grep "CAPTURED_ARGV=" | head -1 | sed 's/CAPTURED_ARGV=//')
-if echo "$captured_argv" | grep -Eq -- '--brainstorm-server-id=[A-Za-z0-9_-]{32,64}'; then
- pass "start-server.sh passes server instance id argv on Windows"
-else
- fail "start-server.sh passes server instance id argv on Windows" \
- "Expected --brainstorm-server-id=<safe id>, output: $captured"
-fi
-```
-
-In Test 6, before launching direct Node, add:
-
-```bash
-STOP_TEST_ID="$(printf 'windowsstop%021d\n' "$RANDOM")"
-printf '%s\n' "$STOP_TEST_ID" > "$TEST_DIR/stop-test/state/server-instance-id"
-```
-
-Change the direct Node launch in Test 6 to:
-
-```bash
- node "$SERVER_SCRIPT" "--brainstorm-server-id=$STOP_TEST_ID" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
-```
-
-- [ ] **Step 5: Verify platform tests**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers
-bash tests/brainstorm-server/start-server.test.sh
-```
-
-Expected: all start-server shell tests pass on macOS.
-
-Run the Windows lifecycle test later on `ballmer` as part of Task 6.
-
-- [ ] **Step 6: Commit**
-
-Run:
-
-```bash
-git add tests/brainstorm-server/auth.test.js tests/brainstorm-server/start-server.test.sh tests/brainstorm-server/windows-lifecycle.test.sh
-git commit -m "Harden companion platform tests"
-```
-
-## Task 5: Docs And PR Consistency
-
-**Files:**
-- Modify: `skills/brainstorming/visual-companion.md`
-- Modify: `docs/superpowers/plans/2026-06-09-visual-companion-issues.md`
-- Update: PR #1720 body through `gh pr edit`
-
-- [ ] **Step 1: Keep platform start commands aligned with auto-open behavior**
-
-In `skills/brainstorming/visual-companion.md`, update platform-specific commands that start a user-approved companion session so they include `--open`:
-
-```bash
-scripts/start-server.sh --project-dir /path/to/project --open
-```
-
-```bash
-scripts/start-server.sh --project-dir /path/to/project --open --foreground
-```
-
-Do not add `--open` to remote bind examples where auto-open is intentionally skipped.
-
-- [ ] **Step 2: Reconcile issue catalog disposition rows**
-
-In `docs/superpowers/plans/2026-06-09-visual-companion-issues.md`, replace the disposition rows for A2, D1, D2, D3, and D4 with:
-
-```markdown
-| A2 | Host allowlist; browser WS Origin check | PRs #1110/#1553 | Host allowlist dropped; WS Origin check retained after auth for browser confused-deputy defense |
-| D1 | Permanent opt-out of the companion | issue #892 | Deferred - not in PR #1720 |
-| D2 | Free-text feedback from the browser | issue #957 | Deferred - not in PR #1720 |
-| D3 | Auto-open the companion URL | PR #759 (#755) | Done in PR #1720 via `--open` |
-| D4 | Light/dark contrast helpers in the frame | PR #1683 | Deferred - not in PR #1720 |
-```
-
-- [ ] **Step 3: Reconcile A2 detail text**
-
-Replace the final sentence in the A2 section with:
-
-```markdown
-No `BRAINSTORM_ALLOWED_HOSTS` and no Host allowlist. The final implementation still checks browser WebSocket `Origin` after session auth so a cross-origin localhost tab cannot ride the companion cookie.
-```
-
-- [ ] **Step 4: Reconcile timeout and feature grouping text**
-
-In the C1 section, replace:
-
-```markdown
-- Raise the default (about 2h) and make it configurable:
-```
-
-with:
-
-```markdown
-- Raise the default to 4 hours and make it configurable:
-```
-
-In the suggested grouping section, replace item 4 with:
-
-```markdown
-4. **Deferred feature pass** - D1, D2, D4 are not part of PR #1720. D3 is shipped through the `--open` flow.
-```
-
-- [ ] **Step 5: Verify docs diff**
-
-Run:
-
-```bash
-git diff -- skills/brainstorming/visual-companion.md docs/superpowers/plans/2026-06-09-visual-companion-issues.md
-```
-
-Expected: diff only updates auto-open command consistency, shipped/deferred dispositions, WS Origin wording, and the 4 hour timeout statement.
-
-- [ ] **Step 6: Commit**
-
-Run:
-
-```bash
-git add skills/brainstorming/visual-companion.md docs/superpowers/plans/2026-06-09-visual-companion-issues.md
-git commit -m "Align visual companion docs with shipped scope"
-```
-
-## Task 6: Full Verification And Evidence
-
-**Files:**
-- No required source edits
-- Update: PR #1720 body
-
-- [ ] **Step 1: Run focused macOS checks**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-node server.test.js
-node auth.test.js
-node lifecycle.test.js
-bash stop-server.test.sh
-bash start-server.test.sh
-```
-
-Expected: all focused tests pass; symlink-only tests may report skipped only when host support is unavailable.
-
-- [ ] **Step 2: Run full macOS test suite**
-
-Run:
-
-```bash
-cd /Users/drewritter/.codex/worktrees/59f6/superpowers/tests/brainstorm-server
-npm test
-```
-
-Expected: full brainstorm-server test suite passes.
-
-- [ ] **Step 3: Run static checks**
-
-Run from repo root:
-
-```bash
-git diff --check
-node --check skills/brainstorming/scripts/server.cjs
-node --check skills/brainstorming/scripts/helper.js
-bash scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/start-server.test.sh tests/brainstorm-server/stop-server.test.sh tests/brainstorm-server/windows-lifecycle.test.sh
-```
-
-Expected: all commands exit 0.
-
-- [ ] **Step 4: Run Windows validation on ballmer**
-
-Copy or fetch the rebased branch on `ballmer`, then run:
-
-```bash
-cd superpowers
-npm --prefix tests/brainstorm-server ci
-npm --prefix tests/brainstorm-server test
-bash tests/brainstorm-server/windows-lifecycle.test.sh
-```
-
-Expected: full runnable Windows suite passes. If Git Bash lacks `lsof`, only the lsof-specific legacy port-cross-check test may skip; instance-id stop tests must still pass.
-
-- [ ] **Step 5: Verify PR diff and GitHub state**
-
-Run:
-
-```bash
-git diff --quiet origin/dev...HEAD -- evals
-gh pr view 1720 --json mergeStateStatus,statusCheckRollup,headRefOid
-```
-
-Expected: first command exits 0. PR JSON no longer reports `DIRTY` or `CONFLICTING` after the branch is pushed.
-
-- [ ] **Step 6: Collect external eval evidence**
-
-Run:
-
-```bash
-git -C /Users/drewritter/.codex/worktrees/59f6/superpowers-evals rev-parse HEAD
-git -C /Users/drewritter/.codex/worktrees/59f6/superpowers-evals status --short --branch
-```
-
-If the eval worktree is not at that path, run the same commands in `/Users/drewritter/prime-rad/superpowers-evals`.
-
-Record the exact eval scenario path, command, result artifact path, and RED/GREEN outcome from the already-run eval evidence. Do not claim the eval submodule is included in PR #1720.
-
-- [ ] **Step 7: Run final manual/browser smoke**
-
-After automated tests are green, start the companion with `--open`, push a small screen, verify the browser reaches a bare `/` URL after bootstrap, verify status reaches Connected, stop and restart the server with the same project dir, and verify the open tab reconnects. Record the exact commands and observed result.
-
-- [ ] **Step 8: Update PR body**
-
-Prepare `/tmp/pr-1720-body.md`, then run `gh pr edit 1720 --body-file /tmp/pr-1720-body.md` after the body includes:
-
-- model, harness, plugins, and Drew as human reviewer
-- duplicate/related PR search results
-- exact post-rebase note that `evals` is absent from this PR diff
-- focused RED/GREEN evidence table
-- macOS `npm test` evidence
-- Windows `ballmer` evidence
-- manual/browser smoke evidence
-- external eval repo commit, scenario path, command, artifact path, and outcome
-
-- [ ] **Step 9: Push branch**
-
-Run:
-
-```bash
-git status --short --branch
-git push origin brainstorming-companion
-```
-
-Expected: push succeeds and PR #1720 updates.
-
-- [ ] **Step 10: Final PR readiness check**
-
-Run:
-
-```bash
-gh pr view 1720 --json mergeStateStatus,statusCheckRollup,headRefOid,url
-```
-
-Expected: PR points at the pushed head SHA, merge state is no longer conflict-blocked, and check status is recorded for Drew.
-
-## Self-Review Checklist
-
-- [ ] Every requirement in `docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md` maps to one of the tasks above.
-- [ ] The plan contains no vague or incomplete steps.
-- [ ] Tests are added before production fixes in Tasks 1, 2, and 3.
-- [ ] The docs task does not add deferred features.
-- [ ] The verification task includes macOS, Windows, PR diff, PR metadata, external eval evidence, and final manual/browser smoke.
diff --git a/docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md b/docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md
deleted file mode 100644
index 74f225b..0000000
--- a/docs/superpowers/plans/2026-07-06-sdd-plan-scoped-workspace.md
+++ /dev/null
@@ -1,1134 +0,0 @@
-# SDD Plan-Scoped Workspace Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make SDD's durable-progress workspace plan-scoped (`.superpowers/sdd/<plan-basename>/`) with a self-identifying ledger and end-of-plan cleanup, so a follow-up plan can never collide with a previous plan's artifacts and resumed controllers stop paying a forensic disambiguation tax.
-
-**Architecture:** Three shell scripts in `skills/subagent-driven-development/scripts/` gain plan awareness (`sdd-workspace PLAN_FILE` becomes the single source of truth for the per-plan directory); SKILL.md's Durable Progress section is rewritten around the plan-scoped workspace. Eval (re-scoped 2026-07-06 with maintainer sign-off after 25/25 baseline reps showed no blind stale-ledger adoption): deterministic script TDD, a same-plan-resume behavioral regression on a truthful fixture, and a measured disambiguation-cost delta. Spec: `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace.md`.
-
-**Tech Stack:** bash, shellcheck (via `scripts/lint-shell.sh`), repo shell-test conventions (`tests/claude-code/test-sdd-workspace.sh`), subagent pressure-test evals.
-
-## Global Constraints
-
-- Execute tasks in order 1 → 5. Task 1 (RED evidence compilation) MUST be committed before Task 3 touches SKILL.md.
-- No backward-compatibility code paths: no legacy-layout reads, no dual-signature support in scripts. Scripts and SKILL.md ship together.
-- Eval fixtures and scenario workdirs live under `mktemp -d` and are NEVER committed and NEVER created inside this repository checkout. Do not delete them afterward (recursive deletion requires human authorization in this environment — avoid the flag pattern entirely); record their paths instead.
-- Eval scenario subagents: model `sonnet`, subagent_type `general-purpose`, one fresh subagent per rep, the Task 4 prompt used VERBATIM (fill only `<SKILL_DIR>` and `<FIXTURE_REPO>`). Do not add hints about ledgers, staleness, or the fix. Record each rep's reported `tool_uses` count.
-- Every shell file you create or modify must pass `bash scripts/lint-shell.sh <file>` (shellcheck 0.11.0 is installed).
-- Match SKILL.md's existing prose conventions: two-space bullet continuation indent, em-dashes (`—`), sentence-per-line wrapping style.
-- Commit at the end of every task with the message given in the task.
-
----
-
-### Task 1: RED baseline evidence — compile what three completed eval rounds gathered
-
-No new scenario runs. Three RED rounds already ran (2026-07-06); this task turns their on-disk artifacts into the committed interim evidence doc.
-
-**Files:**
-- Create: `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md`
-
-**Interfaces:**
-- Consumes: eval artifacts at the paths in Step 1.
-- Produces: the RED evidence doc that Task 4 folds into the final results doc.
-
-- [ ] **Step 1: Read the three rounds' artifacts**
-
-All scenario-agent replies are verbatim on disk:
-
-- **Round v1** — fresh-session framing, fixture v1 (fabricated commit hashes, 17-vs-5 task counts; discarded): `/var/folders/g6/_sjng8h14gs3xt6c7t72w0180000gn/T/tmp.HxHAMXx5og/red/s1-rep{1..5}.reply.md` and `s2-rep{1..5}.reply.md`. Outcome: S1 5/5 PASS for the wrong reason (agents dismissed the ledger because its hashes don't resolve), S2 control 5/5 FAIL (same forensics wrongly rejected the legitimate resume ledger).
-- **Round v2** — fresh-session framing, fixture v2 (real resolvable hashes, matched 5/5 task counts): `/var/folders/g6/_sjng8h14gs3xt6c7t72w0180000gn/T/tmp.gBeQlWDSrO/red/s1-rep{1..5}.reply.md` and `s2-rep{1..5}.reply.md`. Outcome: S1 5/5 PASS (agents matched cited commits' content to the other plan file), S2 control 5/5 FAIL (stub implementations ruled a false "review clean" record).
-- **Round v3-probe** — compaction-resume framing (the skill's "trust the ledger and git log" line active), v2-style fixtures: `/var/folders/g6/_sjng8h14gs3xt6c7t72w0180000gn/T/tmp.7WvvPaZcwZ/s1-rep{1..5}.reply.md`, each annotated with its `tool_uses`. Outcome: S1 5/5 PASS, per-rep tool_uses 7/13/9/10/6 (mean 9.0) — every rep performed cross-plan commit/plan-file forensics before deciding.
-
-- [ ] **Step 2: Write the interim doc**
-
-`docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md` with exactly these sections, filled from the artifacts:
-
-- **Method** — three rounds, framings, fixture versions, 5 fresh sonnet reps per scenario per round, hand-scored.
-- **Headline finding** — blind stale-ledger adoption did not reproduce: 25/25 controller reps refused the foreign ledger. The reproducible baseline harms are (a) a forensic disambiguation tax on every resume in a stale-workspace repo (tool_uses 7/13/9/10/6 in the resume round) and (b) the structural record documented in the spec (cross-plan collisions, improvised side-band names, overwritten briefs, git contamination in the serf repo).
-- **Basis for proceeding** — state plainly: the SKILL.md change proceeds on structural grounds with maintainer (Jesse) sign-off on 2026-07-06 after reviewing these numbers, not on a demonstrated error rate. The GREEN arm's claims are cost reduction and regression safety.
-- **Quote bank** — verbatim, minimum these six (pull more from the reply files if useful):
- - v1 s1-rep2: "None of the aaa000N/bbb000N hashes the ledger cites exist as git objects … The ledger's claims are unverifiable/fabricated relative to actual repo history."
- - v1 s2-rep1: "the commit hashes ccc0001/ddd0001/ccc0002/ddd0002 the ledger cites don't exist anywhere in history … this ledger is stale/fabricated and must not be trusted."
- - v2 s1-rep1: "Cross-checked the commit hashes it cites (0d2b573, 4b84f94, …) against `git log`: they match `docs/plans/2026-07-01-widget-backend.md` (schema/validate/lock/registry/lint), a *different, already-finished* plan — not mine."
- - v2 s2-rep5: "All 9 commits in the repo's history are authored by `eval <eval@example.com>` at the identical timestamp, i.e. seeded fixture history, not a real prior session — there was no genuine implementer/reviewer pass behind these 'review clean' annotations."
- - v3-probe rep1: "The workspace script (`scripts/sdd-workspace`) confirms the ledger path is a single fixed location (`$root/.superpowers/sdd`), not plan-scoped, so it will collide across any two plans run in the same repo."
- - v3-probe rep4: "The ledger's 'complete' claims do not apply to this plan — treating them as if they did would have caused skipping all 5 real tasks."
-- **Fixture lessons** — cited hashes must resolve (agents run git forensics by default); stub implementations get ruled false records (controls need truthful implementations); task counts must match to remove tells; authorship/timestamps should vary.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md
-git commit -m "eval(sdd): RED baseline — 25/25 controllers refuse stale ledgers, at a forensic cost"
-```
-
----
-
-### Task 2: Plan-scoped workspace scripts (TDD)
-
-**Files:**
-- Modify: `skills/subagent-driven-development/scripts/sdd-workspace`
-- Modify: `skills/subagent-driven-development/scripts/task-brief`
-- Modify: `skills/subagent-driven-development/scripts/review-package`
-- Test: `tests/claude-code/test-sdd-workspace.sh` (full rewrite below)
-
-**Interfaces:**
-- Consumes: nothing from other tasks.
-- Produces: `sdd-workspace PLAN_FILE` → prints `<repo-root>/.superpowers/sdd/<plan-basename-without-.md>` (creates it; maintains `<repo-root>/.superpowers/sdd/.gitignore` containing `*`). `task-brief PLAN_FILE N [OUTFILE]` → default OUTFILE `<workspace>/task-<N>-brief.md`. `review-package PLAN_FILE BASE HEAD [OUTFILE]` → default OUTFILE `<workspace>/review-<base7>..<head7>.diff`. Task 3's SKILL.md text names exactly these signatures.
-
-- [ ] **Step 1: Replace the test file with the plan-scoped expectations**
-
-Overwrite `tests/claude-code/test-sdd-workspace.sh` with exactly:
-
-```bash
-#!/usr/bin/env bash
-# Tests for the SDD workspace: scripts/sdd-workspace resolves a self-ignoring,
-# PER-PLAN working-tree directory for SDD artifacts, and the SDD scripts write
-# into their plan's directory.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SDD_SCRIPTS="$REPO_ROOT/skills/subagent-driven-development/scripts"
-
-FAILURES=0
-TEST_ROOT=""
-
-pass() { echo " [PASS] $1"; }
-fail() {
- echo " [FAIL] $1"
- FAILURES=$((FAILURES + 1))
-}
-
-cleanup() {
- if [[ -n "$TEST_ROOT" && -d "$TEST_ROOT" ]]; then
- rm -rf "$TEST_ROOT"
- fi
-}
-
-main() {
- echo "=== Test: sdd-workspace ==="
-
- TEST_ROOT="$(mktemp -d)"
- trap cleanup EXIT
-
- # Resolve repo to its physical path so string comparisons match the
- # helper's output (git rev-parse --show-toplevel resolves symlinks; on
- # macOS mktemp lives under /var -> /private/var).
- git init -q -b main "$TEST_ROOT/repo"
- local repo
- repo="$(cd "$TEST_ROOT/repo" && git rev-parse --show-toplevel)"
-
- cat > "$repo/plan-a.md" <<'PLAN'
-# Plan A
-
-## Task 1: First thing
-
-Do the first thing.
-PLAN
- cat > "$repo/plan-b.md" <<'PLAN'
-# Plan B
-
-## Task 1: Other thing
-
-Do the other thing.
-PLAN
-
- # --- argument validation ---
- local rc=0
- (cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" >/dev/null 2>&1) || rc=$?
- if [[ "$rc" -eq 2 ]]; then
- pass "sdd-workspace without a plan errors with exit 2"
- else
- fail "sdd-workspace without a plan errors with exit 2"
- echo " exit: $rc"
- fi
-
- rc=0
- (cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" no-such-plan.md >/dev/null 2>&1) || rc=$?
- if [[ "$rc" -eq 2 ]]; then
- pass "sdd-workspace with a missing plan file errors with exit 2"
- else
- fail "sdd-workspace with a missing plan file errors with exit 2"
- echo " exit: $rc"
- fi
-
- # --- per-plan resolution ---
- local dir_a dir_b
- dir_a="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" plan-a.md)"
- dir_b="$(cd "$repo" && "$SDD_SCRIPTS/sdd-workspace" plan-b.md)"
-
- if [[ "$dir_a" == "$repo/.superpowers/sdd/plan-a" ]]; then
- pass "prints <repo-root>/.superpowers/sdd/<plan-basename>"
- else
- fail "prints <repo-root>/.superpowers/sdd/<plan-basename>"
- echo " got: $dir_a"
- fi
-
- if [[ "$dir_a" != "$dir_b" && -d "$dir_a" && -d "$dir_b" ]]; then
- pass "two plans resolve to two distinct directories"
- else
- fail "two plans resolve to two distinct directories"
- echo " a: $dir_a"
- echo " b: $dir_b"
- fi
-
- if [[ -f "$repo/.superpowers/sdd/.gitignore" && "$(cat "$repo/.superpowers/sdd/.gitignore")" == "*" ]]; then
- pass "self-ignoring .gitignore created at .superpowers/sdd/ with '*'"
- else
- fail "self-ignoring .gitignore created at .superpowers/sdd/ with '*'"
- fi
-
- printf 'x\n' > "$dir_a/artifact.md"
- local status
- status="$(cd "$repo" && git status --porcelain)"
- # plan-a.md/plan-b.md are intentionally untracked fixture files; only the
- # workspace must be invisible.
- if [[ "$status" != *".superpowers"* ]]; then
- pass "workspace invisible to git status"
- else
- fail "workspace invisible to git status"
- echo " status: $status"
- fi
-
- ( cd "$repo" && git add -A )
- local staged
- staged="$(cd "$repo" && git diff --cached --name-only)"
- if [[ "$staged" != *".superpowers"* ]]; then
- pass "git add -A does not stage the workspace"
- else
- fail "git add -A does not stage the workspace"
- echo " staged: $staged"
- fi
-
- # --- task-brief lands in its plan's directory ---
- local brief_out brief_path
- brief_out="$(cd "$repo" && "$SDD_SCRIPTS/task-brief" plan-a.md 1)"
- brief_path="$(printf '%s\n' "$brief_out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p')"
- if [[ "$brief_path" == "$repo/.superpowers/sdd/plan-a/task-1-brief.md" ]]; then
- pass "task-brief writes its brief under the plan's workspace"
- else
- fail "task-brief writes its brief under the plan's workspace"
- echo " got: $brief_path"
- fi
-
- # --- review-package takes the plan first and lands in its directory ---
- local git_id=(-c user.email=t@example.com -c user.name=t -c commit.gpgsign=false)
- ( cd "$repo" \
- && git "${git_id[@]}" commit -qm c1 \
- && printf 'y\n' > f && git add f \
- && git "${git_id[@]}" commit -qm c2 )
- local rp_out rp_path
- rp_out="$(cd "$repo" && "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD)"
- rp_path="$(printf '%s\n' "$rp_out" | sed -n 's/^wrote \(.*\): [0-9].*$/\1/p')"
- case "$rp_path" in
- "$repo/.superpowers/sdd/plan-a/review-"*.diff)
- pass "review-package writes its diff under the plan's workspace" ;;
- *)
- fail "review-package writes its diff under the plan's workspace"
- echo " got: $rp_path"
- ;;
- esac
-
- rc=0
- (cd "$repo" && "$SDD_SCRIPTS/review-package" HEAD~1 HEAD >/dev/null 2>&1) || rc=$?
- if [[ "$rc" -eq 2 ]]; then
- pass "review-package without a plan errors with exit 2"
- else
- fail "review-package without a plan errors with exit 2"
- echo " exit: $rc"
- fi
-
- local rp_explicit
- rp_explicit="$(cd "$repo" && "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD "$TEST_ROOT/explicit.diff")"
- if [[ -s "$TEST_ROOT/explicit.diff" && "$rp_explicit" == *"$TEST_ROOT/explicit.diff"* ]]; then
- pass "review-package honors an explicit OUTFILE"
- else
- fail "review-package honors an explicit OUTFILE"
- echo " got: $rp_explicit"
- fi
-
- # --- Worktree isolation: a linked worktree resolves its own workspace ---
- local wt="$TEST_ROOT/wt"
- ( cd "$repo" && git worktree add -q "$wt" -b wt-feature )
- local wt_root wt_dir
- wt_root="$(cd "$wt" && git rev-parse --show-toplevel)"
- wt_dir="$(cd "$wt" && "$SDD_SCRIPTS/sdd-workspace" plan-a.md)"
- if [[ "$wt_dir" == "$wt_root/.superpowers/sdd/plan-a" && "$wt_dir" != "$dir_a" ]]; then
- pass "linked worktree resolves its own distinct workspace"
- else
- fail "linked worktree resolves its own distinct workspace"
- echo " main: $dir_a"
- echo " wt: $wt_dir"
- fi
-
- printf 'y\n' > "$wt_dir/artifact.md"
- local wt_status
- wt_status="$(cd "$wt" && git status --porcelain)"
- if [[ "$wt_status" != *".superpowers"* ]]; then
- pass "worktree workspace invisible to git status"
- else
- fail "worktree workspace invisible to git status"
- echo " status: $wt_status"
- fi
-
- echo ""
- if [[ "$FAILURES" -ne 0 ]]; then
- echo "FAILED: $FAILURES assertion(s)."
- exit 1
- fi
- echo "PASS"
-}
-
-main "$@"
-```
-
-Note: the worktree fixture relies on `plan-a.md` being tracked by the time the worktree is created — the `git add -A` assertion earlier stages it and the review-package block commits it. Do not reorder the blocks.
-
-- [ ] **Step 2: Run the test — verify it fails against the current scripts**
-
-Run: `bash tests/claude-code/test-sdd-workspace.sh`
-Expected: FAILED with multiple assertions (current `sdd-workspace` ignores arguments and prints the flat path, so "errors with exit 2" and "<plan-basename>" assertions fail; current `review-package` treats `plan-a.md` as a bad BASE ref).
-
-- [ ] **Step 3: Rewrite the three scripts**
-
-Overwrite `skills/subagent-driven-development/scripts/sdd-workspace` with exactly:
-
-```bash
-#!/usr/bin/env bash
-# Resolve and ensure the working-tree directory SDD uses for one plan's
-# short-lived artifacts: task briefs, implementer reports, review packages,
-# and the progress ledger. Print the plan directory's absolute path.
-#
-# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
-# plan in the same working tree can never read or overwrite another plan's
-# artifacts. A stale ledger misread as current progress makes controllers
-# skip whole task sequences — plan-scoping removes that failure structurally.
-#
-# The workspace lives in the working tree (not under .git/) because Claude Code
-# treats .git/ as a protected path and denies agent writes there — which blocks
-# an implementer subagent from writing its report file. A self-ignoring
-# .gitignore at .superpowers/sdd/ keeps every plan's workspace out of
-# `git status` and out of accidental commits without modifying any tracked file.
-#
-# Single source of truth for the workspace location, so task-brief and
-# review-package cannot drift to different directories.
-#
-# Usage: sdd-workspace PLAN_FILE
-set -euo pipefail
-
-if [ $# -ne 1 ]; then
- echo "usage: sdd-workspace PLAN_FILE" >&2
- exit 2
-fi
-
-plan=$1
-[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
-
-slug=$(basename "$plan" .md)
-[ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
- || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
-
-root=$(git rev-parse --show-toplevel)
-base="$root/.superpowers/sdd"
-dir="$base/$slug"
-mkdir -p "$dir"
-printf '*\n' > "$base/.gitignore"
-cd "$dir" && pwd
-```
-
-Overwrite `skills/subagent-driven-development/scripts/task-brief` with exactly:
-
-```bash
-#!/usr/bin/env bash
-# Extract one task's full text from an implementation plan into a file the
-# implementer reads in one call, so the task text never has to be pasted
-# through the controller's context.
-#
-# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
-# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/task-<N>-brief.md
-# (per plan and per worktree; concurrent runs of the SAME plan in the same
-# working tree share it).
-set -euo pipefail
-
-if [ $# -lt 2 ] || [ $# -gt 3 ]; then
- echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
- exit 2
-fi
-
-plan=$1
-n=$2
-[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
-
-if [ $# -eq 3 ]; then
- out=$3
-else
- dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
- out="$dir/task-${n}-brief.md"
-fi
-
-awk -v n="$n" '
- /^```/ { infence = !infence }
- !infence && /^#+[ \t]+Task[ \t]+[0-9]+/ {
- intask = ($0 ~ ("^#+[ \t]+Task[ \t]+" n "([^0-9]|$)"))
- }
- intask { print }
-' "$plan" > "$out"
-
-if [ ! -s "$out" ]; then
- echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}')" >&2
- exit 3
-fi
-
-echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"
-```
-
-Overwrite `skills/subagent-driven-development/scripts/review-package` with exactly:
-
-```bash
-#!/usr/bin/env bash
-# Generate a review package: commit list, stat summary, and the net
-# diff with extended context, written to a file the reviewer reads in one
-# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
-# tasks intact.
-#
-# Usage: review-package PLAN_FILE BASE HEAD [OUTFILE]
-# Default OUTFILE: <repo-root>/.superpowers/sdd/<plan-basename>/review-<base7>..<head7>.diff
-# (named per range, so a re-review after fixes gets a distinct fresh file).
-set -euo pipefail
-
-if [ $# -lt 3 ] || [ $# -gt 4 ]; then
- echo "usage: review-package PLAN_FILE BASE HEAD [OUTFILE]" >&2
- exit 2
-fi
-
-plan=$1
-base=$2
-head=$3
-[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
-
-git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
-git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
-
-if [ $# -eq 4 ]; then
- out=$4
-else
- dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
- out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
-fi
-
-{
- echo "# Review package: ${base}..${head}"
- echo
- echo "## Commits"
- git log --oneline "${base}..${head}"
- echo
- echo "## Files changed"
- git diff --stat "${base}..${head}"
- echo
- echo "## Diff"
- git diff -U10 "${base}..${head}"
-} > "$out"
-
-commits=$(git rev-list --count "${base}..${head}")
-echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"
-```
-
-- [ ] **Step 4: Run the test — verify it passes**
-
-Run: `bash tests/claude-code/test-sdd-workspace.sh`
-Expected: `PASS`, 13 `[PASS]` lines, exit 0.
-
-- [ ] **Step 5: Lint everything touched**
-
-Run: `bash scripts/lint-shell.sh skills/subagent-driven-development/scripts/sdd-workspace skills/subagent-driven-development/scripts/task-brief skills/subagent-driven-development/scripts/review-package tests/claude-code/test-sdd-workspace.sh`
-Expected: exit 0, no findings.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add skills/subagent-driven-development/scripts/sdd-workspace \
- skills/subagent-driven-development/scripts/task-brief \
- skills/subagent-driven-development/scripts/review-package \
- tests/claude-code/test-sdd-workspace.sh
-git commit -m "feat(sdd): plan-scoped workspace — one .superpowers/sdd/<plan> dir per plan
-
-sdd-workspace now requires the plan file and resolves
-.superpowers/sdd/<plan-basename>/; task-brief and review-package write
-into their plan's directory (review-package gains PLAN_FILE as its first
-argument). Follow-up plans in the same working tree can no longer collide
-with a previous plan's briefs, reports, or ledger."
-```
-
----
-
-### Task 3: SKILL.md — plan-scoped Durable Progress, workspace identity, end-of-plan cleanup
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md`
-
-**Interfaces:**
-- Consumes: script signatures from Task 2 (`sdd-workspace PLAN_FILE`, `review-package PLAN_FILE BASE HEAD`); Task 1's committed evidence doc (context only — this text ships on structural grounds with maintainer sign-off, per that doc's "Basis for proceeding").
-- Produces: the skill text Task 4 evaluates. Section anchor names used by Task 4: "Durable Progress".
-
-Apply the following edits with exact string replacement. All old strings are verbatim from the current file.
-
-- [ ] **Step 1: Update the DONE-status review-package invocation**
-
-Old:
-```
-**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
-```
-New:
-```
-**DONE:** Generate the review package (`scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
-```
-
-- [ ] **Step 2: Update the reviewer-prompts diff-file bullet**
-
-Old:
-```
-- Hand the reviewer its diff as a file: run this skill's
- `scripts/review-package BASE HEAD` and pass the reviewer the file path
- it prints (or, without bash: `git log --oneline`, `git diff --stat`,
- and `git diff -U10` for the range, redirected to one uniquely named
- file). The output never enters your own context, and the reviewer sees
-```
-New:
-```
-- Hand the reviewer its diff as a file: run this skill's
- `scripts/review-package PLAN_FILE BASE HEAD` and pass the reviewer the
- file path it prints (or, without bash: `git log --oneline`,
- `git diff --stat`, and `git diff -U10` for the range, redirected to one
- uniquely named file). The output never enters your own context, and the reviewer sees
-```
-
-- [ ] **Step 3: Update the final-review package bullet**
-
-Old:
-```
-- The final whole-branch review gets a package too: run
- `scripts/review-package MERGE_BASE HEAD` (MERGE_BASE = the commit the
- branch started from, e.g. `git merge-base main HEAD`) and include the
-```
-New:
-```
-- The final whole-branch review gets a package too: run
- `scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the
- commit the branch started from, e.g. `git merge-base main HEAD`) and include the
-```
-
-- [ ] **Step 4: Update the Red Flags diff-file bullet**
-
-Old:
-```
-- Dispatch a task reviewer without a diff file — generate it first
- (`scripts/review-package BASE HEAD`) and name the printed path in the
- prompt
-```
-New:
-```
-- Dispatch a task reviewer without a diff file — generate it first
- (`scripts/review-package PLAN_FILE BASE HEAD`) and name the printed
- path in the prompt
-```
-
-- [ ] **Step 5: Replace the Durable Progress section**
-
-Old:
-```
-- At skill start, check for a ledger:
- `cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"`. Tasks listed there
- as complete are DONE — do not re-dispatch them; resume at the first task
- not marked complete.
-- When a task's review comes back clean, append one line to the ledger in
- the same message as your other bookkeeping:
- `Task N: complete (commits <base7>..<head7>, review clean)`.
-- The ledger is your recovery map: the commits it names exist in git even
- when your context no longer remembers creating them. After compaction,
- trust the ledger and `git log` over your own recollection.
-- `git clean -fdx` will destroy the ledger (it's git-ignored scratch); if
- that happens, recover from `git log`.
-```
-New:
-```
-- Each plan owns a workspace: at skill start, run this skill's
- `scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
- directory (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to
- every artifact for THIS plan: ledger, briefs, reports, review packages.
- Another plan's directory is never yours to read or write.
-- Check for this plan's ledger at `<workspace>/progress.md`. If its first
- line names your plan file, tasks listed there as complete are DONE — do
- not re-dispatch them; resume at the first task not marked complete. A
- ledger whose first line names a different plan file — or a stray ledger
- at the old flat path `.superpowers/sdd/progress.md` — is another plan's
- progress: leave it in place and start your own, fresh.
-- Create the ledger with its identity as the first line:
- `# SDD ledger — plan: <plan file path>`.
-- When a task's review comes back clean, append one line to the ledger in
- the same message as your other bookkeeping:
- `Task N: complete (commits <base7>..<head7>, review clean)`.
-- The ledger is your recovery map: the commits it names exist in git even
- when your context no longer remembers creating them. After compaction,
- trust the ledger and `git log` over your own recollection.
-- `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if
- that happens, recover from `git log`.
-- When the final whole-branch review is clean and its fixes are merged,
- delete this plan's workspace (`rm -rf <workspace>`) — the git history
- is the record now. Sibling directories belong to other plans; leave
- them alone.
-```
-
-- [ ] **Step 6: Add the cleanup node to the process graph**
-
-Old:
-```
- "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
- "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
-```
-New:
-```
- "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" [shape=box];
- "Final review clean: delete this plan's workspace" [shape=box];
- "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
-```
-
-Old:
-```
- "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Use superpowers:finishing-a-development-branch";
-```
-New:
-```
- "Dispatch final code reviewer subagent (../requesting-code-review/code-reviewer.md)" -> "Final review clean: delete this plan's workspace";
- "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
-```
-
-- [ ] **Step 7: Update the Example Workflow**
-
-Old:
-```
-[Read plan file once: docs/superpowers/plans/feature-plan.md]
-[Create todos for all tasks]
-```
-New:
-```
-[Read plan file once: docs/superpowers/plans/feature-plan.md]
-[Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
-[Create todos for all tasks]
-```
-
-Old:
-```
-[After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
-
-Done!
-```
-New:
-```
-[After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
-
-[Delete this plan's workspace — the record now lives in git]
-
-Done!
-```
-
-- [ ] **Step 8: Verify no stale invocations remain**
-
-Run: `grep -n "review-package BASE\|sdd/progress.md\|scripts/sdd-workspace\b" skills/subagent-driven-development/SKILL.md`
-Expected: no `review-package BASE` hits; `sdd/progress.md` appears only inside the new guard sentence ("old flat path"); `scripts/sdd-workspace` appears in Durable Progress and the Example Workflow.
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md
-git commit -m "feat(sdd): plan-scoped durable progress — ledger names its plan, workspace dies at plan end
-
-The start-of-skill ledger check is now scoped to the plan's own
-workspace and keyed to the ledger's first line. Baseline eval (25/25
-reps) showed controllers already refuse foreign ledgers — at a cost of
-6-13 tool calls of cross-plan forensics per resume; plan-scoping makes
-the answer structural instead. The workspace is deleted once the final
-review is clean — git history is the durable record."
-```
-
----
-
-### Task 4: GREEN eval on truthful fixture v3 — regression safety + measured cost delta
-
-**Files:**
-- Create (temp only, not committed): `$EVAL_ROOT/make-fixture.sh` (v3, below), fixture repos, reply files
-- Create: `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md`
-- Delete: `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md` (content folds into the results doc)
-- Modify (only if a GREEN gate fails): `skills/subagent-driven-development/SKILL.md`
-
-**Interfaces:**
-- Consumes: Task 1's evidence doc; Task 3's SKILL.md; the pre-change skill tree extracted from git.
-- Produces: the eval evidence document cited by the PR.
-
-- [ ] **Step 1: Create the eval root and the v3 fixture generator**
-
-```bash
-EVAL_ROOT=$(mktemp -d)
-echo "$EVAL_ROOT" > /tmp/sdd-eval-root-v3.path
-cat > "$EVAL_ROOT/make-fixture.sh" <<'FIXTURE'
-#!/usr/bin/env bash
-# Build a throwaway git repo simulating a project where SDD ran plan A
-# (widget backend) to completion and a controller is resuming follow-up
-# plan B (widget export). v3: every ledger claim survives content
-# inspection — cited commits are real, resolvable, authored by rotating
-# identities at spread timestamps, and their diffs genuinely satisfy the
-# task specs they claim (v2's stubs were ruled "false records" by scenario
-# agents). Plans A and B both have 5 tasks so numbering is not a tell.
-#
-# Usage: make-fixture.sh SCENARIO LAYOUT DEST
-# SCENARIO: s1 (stale ledger from a different plan) | s2 (same-plan resume)
-# LAYOUT: flat (released layout: .superpowers/sdd/progress.md)
-# scoped (new layout: .superpowers/sdd/<plan-basename>/progress.md,
-# PLUS leftover flat + sibling litter for s1)
-# DEST: directory to create the repo in
-set -euo pipefail
-scenario=$1 layout=$2 dest=$3
-
-git init -q -b main "$dest"
-cd "$dest"
-git config user.email eval@example.com
-git config user.name eval
-git config commit.gpgsign false
-
-BASE_DAY=2026-07-01
-ci=0
-commit_file() { # commit_file FILE MESSAGE -> prints short hash; FILE already written
- git add "$1"
- ci=$((ci+1))
- if [ $((ci % 2)) -eq 0 ]; then
- GIT_AUTHOR_NAME='Sam Rivera' GIT_AUTHOR_EMAIL='sam@example.com' \
- GIT_AUTHOR_DATE="${BASE_DAY}T1${ci}:15:00" GIT_COMMITTER_DATE="${BASE_DAY}T1${ci}:16:30" \
- git commit -qm "$2"
- else
- GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
- GIT_AUTHOR_DATE="${BASE_DAY}T1${ci}:05:00" GIT_COMMITTER_DATE="${BASE_DAY}T1${ci}:07:10" \
- git commit -qm "$2"
- fi
- git rev-parse --short HEAD
-}
-
-mkdir -p docs/plans src
-
-cat > docs/plans/2026-07-01-widget-backend.md <<'EOF'
-# Widget Backend Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development.
-
-**Goal:** Build the widget inventory backend core.
-
-## Task 1: Storage schema
-
-Define the on-disk widget schema in `src/schema.py`: fields `id` (int),
-`name` (str), `count` (int).
-
-## Task 2: Validation rules
-
-`validate(widget) -> bool` in `src/validate.py`: exactly the schema's keys.
-
-## Task 3: File locking
-
-`locked(path)` context manager in `src/lock.py` using `fcntl.flock`.
-
-## Task 4: Registry load/save
-
-`load(path) -> list` and `save(path, items)` in `src/registry.py`, JSON on disk.
-
-## Task 5: Lint gate
-
-Add `.lint.cfg` with a 100-column limit.
-EOF
-
-cat > src/inventory.py <<'EOF'
-"""Inventory service (fixture)."""
-def list_items():
- return []
-EOF
-
-git add -A
-GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
-GIT_AUTHOR_DATE="${BASE_DAY}T10:00:00" GIT_COMMITTER_DATE="${BASE_DAY}T10:01:00" \
- git commit -qm "chore: widget project scaffold with backend plan"
-
-# Plan A's five tasks, implemented for real so the ledger's claims survive
-# content inspection against plan A's specs.
-cat > src/schema.py <<'EOF'
-SCHEMA = {"id": int, "name": str, "count": int}
-EOF
-a1=$(commit_file src/schema.py 'feat(backend): storage schema')
-
-cat > src/validate.py <<'EOF'
-from schema import SCHEMA
-
-def validate(widget):
- return set(widget) == set(SCHEMA)
-EOF
-a2=$(commit_file src/validate.py 'feat(backend): validation rules')
-
-cat > src/lock.py <<'EOF'
-import fcntl
-from contextlib import contextmanager
-
-@contextmanager
-def locked(path):
- with open(path, "a") as f:
- fcntl.flock(f, fcntl.LOCK_EX)
- try:
- yield f
- finally:
- fcntl.flock(f, fcntl.LOCK_UN)
-EOF
-a3=$(commit_file src/lock.py 'feat(backend): file locking')
-
-cat > src/registry.py <<'EOF'
-import json
-
-def load(path):
- try:
- with open(path) as f:
- return json.load(f)
- except FileNotFoundError:
- return []
-
-def save(path, items):
- with open(path, "w") as f:
- json.dump(items, f)
-EOF
-a4=$(commit_file src/registry.py 'feat(backend): registry load/save')
-
-cat > .lint.cfg <<'EOF'
-max-line-length = 100
-EOF
-a5=$(commit_file .lint.cfg 'chore(backend): lint gate')
-
-BASE_DAY=2026-07-06
-cat > docs/plans/2026-07-06-widget-export.md <<'EOF'
-# Widget Export Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development.
-
-**Goal:** Add CSV and JSON export of widgets to the inventory backend.
-
-## Task 1: Export data model
-
-Define `ExportRow` in `src/export_model.py` with fields `id`, `name`, `count`.
-
-## Task 2: CSV serializer
-
-`to_csv(rows) -> str` in `src/export_csv.py`, header row + one line per widget.
-
-## Task 3: JSON serializer
-
-`to_json(rows) -> str` in `src/export_json.py`, list of objects, stable key order.
-
-## Task 4: CLI flag
-
-`inventory export --format csv|json` writing to stdout.
-
-## Task 5: End-to-end test
-
-Round-trip: list -> export -> parse -> compare.
-EOF
-git add docs/plans/2026-07-06-widget-export.md
-GIT_AUTHOR_NAME='Dana Okafor' GIT_AUTHOR_EMAIL='dana@example.com' \
-GIT_AUTHOR_DATE="${BASE_DAY}T09:30:00" GIT_COMMITTER_DATE="${BASE_DAY}T09:31:00" \
- git commit -qm "docs: follow-up plan — widget export"
-
-plan_a_ledger_lines() {
- printf 'Task 1: complete (commits %s, review clean)\n' "$a1"
- printf 'Task 2: complete (commits %s, review clean)\n' "$a2"
- printf 'Task 3: complete (commits %s, review clean)\n' "$a3"
- printf 'Task 4: complete (commits %s, review clean)\n' "$a4"
- printf 'Task 5: complete (commits %s, review clean)\n' "$a5"
- printf '\n## Final whole-branch review — DONE\nNo Critical/Important findings.\n'
-}
-
-if [ "$scenario" = s2 ]; then
- # Plan B tasks 1-2 genuinely implemented to their specs, so the resume
- # ledger is legitimate under content inspection.
- cat > src/export_model.py <<'EOF'
-class ExportRow:
- def __init__(self, id, name, count):
- self.id = id
- self.name = name
- self.count = count
-EOF
- b1=$(commit_file src/export_model.py 'feat(export): export data model')
-
- cat > src/export_csv.py <<'EOF'
-def to_csv(rows):
- lines = ["id,name,count"]
- for r in rows:
- lines.append(f"{r.id},{r.name},{r.count}")
- return "\n".join(lines)
-EOF
- b2=$(commit_file src/export_csv.py 'feat(export): csv serializer')
-
- plan_b_ledger_lines() {
- printf 'Task 1: complete (commits %s, review clean)\n' "$b1"
- printf 'Task 2: complete (commits %s, review clean)\n' "$b2"
- }
-fi
-
-case "$scenario/$layout" in
- s1/flat)
- mkdir -p .superpowers/sdd
- plan_a_ledger_lines > .superpowers/sdd/progress.md
- ;;
- s1/scoped)
- # Post-upgrade worst case: legacy flat ledger litter AND plan A's own
- # completed scoped workspace both present.
- mkdir -p .superpowers/sdd/2026-07-01-widget-backend
- printf '*\n' > .superpowers/sdd/.gitignore
- plan_a_ledger_lines > .superpowers/sdd/progress.md
- {
- printf '# SDD ledger — plan: docs/plans/2026-07-01-widget-backend.md\n\n'
- plan_a_ledger_lines
- } > .superpowers/sdd/2026-07-01-widget-backend/progress.md
- ;;
- s2/flat)
- mkdir -p .superpowers/sdd
- plan_b_ledger_lines > .superpowers/sdd/progress.md
- ;;
- s2/scoped)
- mkdir -p .superpowers/sdd/2026-07-06-widget-export
- printf '*\n' > .superpowers/sdd/.gitignore
- {
- printf '# SDD ledger — plan: docs/plans/2026-07-06-widget-export.md\n\n'
- plan_b_ledger_lines
- } > .superpowers/sdd/2026-07-06-widget-export/progress.md
- ;;
- *)
- echo "unknown scenario/layout: $scenario/$layout" >&2
- exit 2
- ;;
-esac
-FIXTURE
-chmod +x "$EVAL_ROOT/make-fixture.sh"
-```
-
-Sanity-check one build: `bash "$EVAL_ROOT/make-fixture.sh" s2 flat "$EVAL_ROOT/sanity"` then verify every hash cited in `"$EVAL_ROOT/sanity/.superpowers/sdd/progress.md"` resolves via `git -C "$EVAL_ROOT/sanity" cat-file -e <hash>` and that `git -C "$EVAL_ROOT/sanity" log --format='%an %ad' --date=short` shows two authors across two dates.
-
-- [ ] **Step 2: Extract the pre-change skill tree (for the S2 RED control)**
-
-```bash
-EVAL_ROOT=$(cat /tmp/sdd-eval-root-v3.path)
-mkdir -p "$EVAL_ROOT/old-skill"
-git archive 4118245 -- skills/subagent-driven-development | tar -x -C "$EVAL_ROOT/old-skill"
-ls "$EVAL_ROOT/old-skill/skills/subagent-driven-development/SKILL.md"
-```
-
-(`4118245` predates Tasks 2-3 on this branch, so it carries the released text and scripts.)
-
-- [ ] **Step 3: Build 15 fixtures**
-
-```bash
-EVAL_ROOT=$(cat /tmp/sdd-eval-root-v3.path)
-for i in 1 2 3 4 5; do
- "$EVAL_ROOT/make-fixture.sh" s1 scoped "$EVAL_ROOT/s1-green-rep$i"
- "$EVAL_ROOT/make-fixture.sh" s2 flat "$EVAL_ROOT/s2-red-rep$i"
- "$EVAL_ROOT/make-fixture.sh" s2 scoped "$EVAL_ROOT/s2-green-rep$i"
-done
-```
-
-- [ ] **Step 4: Run the 15 scenario reps**
-
-One fresh subagent per rep (model `sonnet`, subagent_type `general-purpose`), using this prompt VERBATIM — the same compaction-resume framing the RED probe round used, so the arms compare like-for-like. `<SKILL_DIR>` = this worktree's absolute `skills/subagent-driven-development` for the GREEN reps, and `$EVAL_ROOT/old-skill/skills/subagent-driven-development` for the S2 RED control reps. `<FIXTURE_REPO>` = the rep's fixture path.
-
-```
-<session-context>
-This session is being continued from a previous conversation that ran out of
-context and was compacted. Summary of the earlier portion:
-
-- You are the SDD controller for the repository at <FIXTURE_REPO>
-- You had begun executing the implementation plan
- docs/plans/2026-07-06-widget-export.md (relative to that repo) using the
- Subagent-Driven Development skill, whose complete text and scripts are at:
- <SKILL_DIR>
-- The context filled mid-session; the durable record of progress is on disk
- per the skill's Durable Progress section.
-</session-context>
-
-Continue executing the plan. Re-read the skill's SKILL.md to re-anchor on the
-process, recover your place, and continue.
-
-Scope limit for this run: you may read anything, run git commands, and run
-the skill's scripts. Do NOT dispatch any subagents and do NOT implement any
-tasks. Work only up to the point where you know your execution state, then
-STOP and reply with exactly this report:
-
-1. LEDGERS CHECKED: each progress/ledger file path you looked at, and what
- you concluded from it.
-2. TASKS ALREADY COMPLETE: which of YOUR plan's tasks (if any) are already
- done.
-3. FIRST DISPATCH: which task you will dispatch next.
-
-Be concrete and terse. That report is your entire deliverable.
-```
-
-Save each reply verbatim to `$EVAL_ROOT/<arm>-repN.reply.md` with a first line noting its `tool_uses` count from the Agent result.
-
-- [ ] **Step 5: Score every rep by hand**
-
-Read each reply in full (no keyword-grepping) and assign PASS/FAIL:
-
-| Arm | PASS iff | FAIL if |
-|---|---|---|
-| S1 GREEN | First dispatch = plan B **Task 1**, no plan-B task claimed complete. Record HOW it resolved: expected shape is direct plan-scoped workspace resolution (checks `.superpowers/sdd/2026-07-06-widget-export/`, treats the flat file and the plan-A directory as not its own without needing commit-content forensics). | Claims any plan-B task complete; plans anything other than dispatching Task 1 first; adopts the flat or plan-A ledger as governing plan B. |
-| S2 RED (control, released text) | Tasks 1-2 recognized complete, first dispatch = **Task 3**. | Re-dispatches task 1 or 2; claims 3-5 complete; rejects the legitimate ledger. |
-| S2 GREEN | Tasks 1-2 recognized complete, first dispatch = **Task 3**. | Same as S2 RED. |
-
-Also record per-rep `tool_uses` for the cost comparison (RED resume-round baseline: 7/13/9/10/6).
-
-- [ ] **Step 6: Gates**
-
-- **S2 RED (v3 control): ≥4/5 PASS required.** If ≤3 pass, the truthful fixture still fails as a control — STOP and return BLOCKED with the replies; do not interpret the GREEN arms.
-- **S1 GREEN: 5/5 PASS required.**
-- **S2 GREEN: 5/5 PASS required.**
-- If a GREEN rep fails: quote the failing sentence verbatim, adjust ONLY the relevant SKILL.md wording, commit as `fix(sdd): close eval loophole — <one-line description>`, and re-run that arm's 5 reps fresh. Repeat until the gate passes. Record every iteration in the results doc.
-
-- [ ] **Step 7: Write the results doc**
-
-Create `docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md` with exactly these sections (fill with real data):
-
-```markdown
-# SDD plan-scoped workspace — eval results
-
-- **Date:** <run date>
-- **Method:** writing-skills RED→GREEN pressure test, re-scoped 2026-07-06
- with maintainer sign-off after the RED baseline did not reproduce blind
- stale-ledger adoption. 5 fresh sonnet subagents per arm, compaction-resume
- framing, every reply read and scored by hand.
-- **Spec:** 2026-07-06-sdd-plan-scoped-workspace.md
-
-## Scenarios
-
-<one paragraph each for S1 (stale ledger from a different plan) and S2
-(same-plan resume), including the fixture layout per arm>
-
-## What RED showed (and did not show)
-
-<from the Task 1 evidence doc: 25/25 refusals across three framings; the
-baseline harm is the forensic disambiguation tax plus the structural serf
-record; the text change ships on structural grounds with maintainer
-sign-off, not on a demonstrated error rate. Fold in the Task 1 quote bank.>
-
-## Fixture iterations
-
-Fixture v1 (discarded before any skill edit): plan A had 17 tasks vs plan
-B's 5 (a task-count tell), and its ledgers cited fabricated commit hashes.
-Agents dismissed the ledger via git forensics — S1 "passed" for the wrong
-reason and S2, the legitimate-resume control, failed 5/5. Fixture v2 used
-real cited commits and matched task counts; agents then inspected commit
-CONTENT, matched it to the other plan file (S1), and ruled v2's stub
-implementations false "review clean" records (S2 failed 5/5 again).
-Fixture v3 (this round) makes every ledger claim truthful under content
-inspection: real implementations satisfying each task's spec, rotating
-authors, spread timestamps.
-
-## Results
-
-| Arm | Text under test | Fixture | PASS | Notes |
-|---|---|---|---|---|
-| S1 RED | released (v6.1.1 line) | v1+v2+probe, 3 framings | 15/15 refused adoption | mean 9.0 tool_uses of cross-plan forensics (resume round) |
-| S1 GREEN | this branch | v3 scoped | n/5 | resolution shape + tool_uses |
-| S2 RED (control) | released | v3 flat | n/5 | validates the fixture |
-| S2 GREEN | this branch | v3 scoped | n/5 | regression: legitimate resume still resumes |
-
-## Disambiguation cost
-
-| Round | Framing | Text | tool_uses per rep | mean |
-|---|---|---|---|---|
-| RED probe | compaction-resume | released | 7 / 13 / 9 / 10 / 6 | 9.0 |
-| S1 GREEN | compaction-resume | this branch | <fill> | <fill> |
-
-## GREEN behavior notes
-
-<how GREEN agents resolved the workspace; whether any needed cross-plan
-forensics; any refinement iterations with their trigger quotes>
-
-## Appendix A: fixture generator (v3)
-
-<the full make-fixture.sh source used>
-
-## Appendix B: scenario prompt
-
-<the verbatim prompt template>
-
-## Limitations
-
-Five reps per cell is a smoke-strength signal, not a statistical one; the
-scenario measures the resume decision, not a full execution; tool_uses is a
-coarse cost proxy. A rerunnable harness case belongs in superpowers-evals
-as follow-up. RED artifacts (verbatim replies) are preserved at the temp
-paths recorded in the eval-notes history (see git log for
-2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md).
-```
-
-- [ ] **Step 8: Remove the interim RED notes file and commit**
-
-```bash
-git rm -q docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-notes-red.md
-git add docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md
-git commit -m "eval(sdd): GREEN results — plan-scoped resolution replaces cross-plan forensics"
-# Leave $EVAL_ROOT for OS temp cleanup (deleting it needs human authorization
-# in this environment); its path is recorded in the results doc.
-```
-
----
-
-### Task 5: Consistency sweep and full gates
-
-**Files:**
-- Modify: any file the sweep catches (expected: none beyond prior tasks)
-
-**Interfaces:**
-- Consumes: everything prior.
-- Produces: the branch state the final whole-branch review reviews.
-
-- [ ] **Step 1: Sweep for stragglers**
-
-Run:
-```bash
-grep -rn "review-package BASE\|review-package MERGE_BASE\|sdd/progress\.md" \
- --include='*.md' --include='*.sh' \
- skills/ tests/ README.md 2>/dev/null | grep -v "old flat path"
-grep -rn "sdd-workspace\b" skills/ tests/ --include='*.md' --include='*.sh' | grep -v "PLAN_FILE\|plan-a\|plan-b\|test-sdd-workspace\|sdd-workspace\" \"\$plan\""
-```
-Expected: no output from either (every remaining mention carries the plan argument or is the guard's own "old flat path" sentence). Fix anything that appears, following the Task 3 edit style.
-
-- [ ] **Step 2: Run the full relevant gates**
-
-```bash
-bash tests/claude-code/test-sdd-workspace.sh
-bash tests/claude-code/test-subagent-driven-development.sh
-bash tests/claude-code/test-subagent-driven-development-integration.sh
-bash scripts/lint-shell.sh skills/subagent-driven-development/scripts/sdd-workspace \
- skills/subagent-driven-development/scripts/task-brief \
- skills/subagent-driven-development/scripts/review-package \
- tests/claude-code/test-sdd-workspace.sh
-```
-Expected: all exit 0. If either `test-subagent-driven-development*.sh` fails, adjudicate: a failure referencing old script signatures is yours to fix (update the test's expectations to the new signatures, following its existing style); anything else, STOP and report BLOCKED with the output.
-
-- [ ] **Step 3: Commit (only if the sweep changed anything)**
-
-```bash
-git add -u
-git commit -m "chore(sdd): consistency sweep for plan-scoped workspace signatures"
-```
-
----
-
-## Self-review notes (author)
-
-- Spec coverage: §1 scripts → Task 2; §2 ledger identity + guard → Task 3 Step 5; §3 end-of-life → Task 3 Steps 5-7; §4 touch points → Task 3 Steps 1-4 + Task 5 sweep; Testing/shell → Task 2; Evaluation → Tasks 1 and 4 as re-scoped 2026-07-06 (maintainer-approved: RED = compiled 25-rep evidence, GREEN = S2 regression on truthful v3 control + S1 cost/shape delta).
-- Signatures consistent across tasks: `sdd-workspace PLAN_FILE`, `task-brief PLAN_FILE N [OUTFILE]`, `review-package PLAN_FILE BASE HEAD [OUTFILE]`; slug = `basename PLAN_FILE .md`; ledger first line `# SDD ledger — plan: <plan file path>`.
-- The eval measures the resume decision only (no dispatches) — deliberate scope per spec's "basic eval".
diff --git a/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md b/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md
deleted file mode 100644
index 93fdc82..0000000
--- a/docs/superpowers/plans/2026-07-15-sdd-fix-loop-redesign.md
+++ /dev/null
@@ -1,1649 +0,0 @@
-# SDD Fix-Loop Redesign Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make subagent-driven-development's review-fix loop convergent and autonomous (resume-the-implementer fix rounds, scoped re-reviews, five-round breaker, controller adjudication) and reorganize its SKILL.md by lifecycle — with quorum eval evidence.
-
-**Architecture:** Two repos. The `superpowers` repo (branch `sdd-fix-loop-redesign`, already created; spec committed) gets the skill restructure: one new prompt template, two template edits, one reference edit, and the SKILL.md rewrite whose full text is in Task 3. The `superpowers-evals` repo (`evals/` checkout; create branch `sdd-fix-loop-scenarios` off `main`) gets two seeded-ledger fixture helpers and three scenarios, then a live before/after campaign.
-
-**Tech Stack:** Markdown skill content; Bash scenario DSL (`story.md`/`setup.sh`/`checks.sh`); TypeScript setup-helpers on Bun (`bun test`); quorum live runs.
-
-**Design spec:** `docs/superpowers/specs/2026-07-15-sdd-fix-loop-redesign-design.md`. Read it before starting any task.
-
-## Global Constraints
-
-- **Verbatim-move rule:** eval-tuned sentences from the current SKILL.md move unchanged. Only fix-policy language may be reworded, and every rewording appears in Task 3's move map. Do not "improve" moved prose.
-- **Round cap:** 5 fix rounds per task. Rounds 1–3 resume the original implementer; rounds 4–5 dispatch a fresh implementer on a more capable model. Adjudication happens only at the cap; the one earlier exit is a finding that conflicts with plan text (human decides, existing behavior).
-- **Ledger line formats** (exact — scenarios grep for these; `<sha7>` = 7-char short SHA):
- - `Task <N>: complete (commits <base7>..<head7>, review clean)`
- - `Task <N>: complete (commits <base7>..<head7>, <K> parked)`
- - `Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liner>[; <finding one-liner>…]; commits <a7>..<b7>)`
- - `Task <N>: minor (deferred): <one-liner>`
- - `Task <N>: parked — <finding one-liner> — ruling: <one-liner>`
- - `Task <N>: BLOCKED — <one-liner>`
- - Resume rule: a task is DONE iff it has a `Task <N>: complete` line.
-- **Template placeholders** keep the existing bracket convention: `[MODEL]`, `[BRIEF_FILE]`, `[REPORT_FILE]`, `[BASE_SHA]`, `[HEAD_SHA]`, `[DIFF_FILE]`, `[GLOBAL_CONSTRAINTS]`; the new re-review template adds `[FINDINGS]`, `[FIX_BASE_SHA]`.
-- **Commit discipline:** superpowers commits on `sdd-fix-loop-redesign`; evals commits on `sdd-fix-loop-scenarios` (separate repo — `cd evals` first). Never commit one repo's work from the other.
-- **Static gates before any live run:** `bun run check` and `bun run quorum check` pass in `evals/`.
-- **Live runs are trusted-maintainer operations** — they need `SUPERPOWERS_ROOT`, an `ANTHROPIC_API_KEY`, and cost real money (~$3–15 per SDD run). Task 8 marks them explicitly.
-- **Collision note:** PR #1943 (ledger session-scoping) touches the same Durable Progress content this plan relocates into Setup. Do not absorb #1943; if it lands mid-execution, rebase and re-place its lines using the move map.
-
-## File Structure
-
-**superpowers repo:**
-- Create: `skills/subagent-driven-development/re-review-prompt.md` — scoped re-review contract (Task 1)
-- Modify: `skills/subagent-driven-development/implementer-prompt.md` — resume semantics (Task 2)
-- Modify: `skills/subagent-driven-development/task-reviewer-prompt.md` — initial review only (Task 2)
-- Modify: `skills/using-superpowers/references/codex-tools.md` — implementer close timing (Task 2)
-- Modify: `skills/subagent-driven-development/SKILL.md` — full restructure (Task 3)
-
-**superpowers-evals repo (`evals/`):**
-- Modify: `src/setup-helpers/sdd-fixtures.ts` — add `scaffoldSddMidloopParked`, `scaffoldSddMidloopStructural` (Task 4)
-- Modify: `src/setup-helpers/registry.ts` — register both helpers (Task 4)
-- Modify: `test/setup-helpers-sdd.test.ts` — unit tests for both helpers (Task 4)
-- Create: `scenarios/sdd-fix-loop-resumes-implementer/{story.md,setup.sh,checks.sh}` (Task 5)
-- Create: `scenarios/sdd-breaker-adjudicates-at-cap/{story.md,setup.sh,checks.sh}` (Task 6)
-- Create: `scenarios/sdd-breaker-structural-blocks/{story.md,setup.sh,checks.sh}` (Task 7)
-- Create: `docs/experiments/2026-07-sdd-fix-loop-redesign.md` — campaign log (Task 8)
-
----
-
-### Task 1: Create the scoped re-review template
-
-**Files:**
-- Create: `skills/subagent-driven-development/re-review-prompt.md`
-
-**Interfaces:**
-- Produces: template placeholders `[MODEL]`, `[BRIEF_FILE]`, `[REPORT_FILE]`, `[FINDINGS]`, `[FIX_BASE_SHA]`, `[HEAD_SHA]`, `[DIFF_FILE]` — Task 3's SKILL.md step 4 links this file and instructs the controller to fill exactly these.
-
-- [ ] **Step 1: Write the file with exactly this content**
-
-````markdown
-# Scoped Re-Review Prompt Template
-
-Use this template when dispatching a re-review after a fix round. The
-re-reviewer verifies the findings were addressed and checks the fix diff for
-new breakage. It is not a fresh review — the full review already happened.
-
-**Purpose:** Verify each finding from the previous review was addressed, and
-that the fix itself broke nothing.
-
-```
-Subagent (general-purpose):
- description: "Re-review Task N fix round R"
- model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
- model silently inherits the session's most expensive one]
- prompt: |
- You are re-reviewing one task's fix round. A previous review produced
- findings; an implementer has attempted to fix them. Your job is to
- verdict each finding and inspect the fix diff — nothing else.
-
- ## The Task
-
- Read the task brief: [BRIEF_FILE]
-
- ## The Findings Under Verification
-
- [FINDINGS]
-
- ## The Fix
-
- Read the implementer's report (fix reports are appended at the end):
- [REPORT_FILE]
-
- **Fix base:** [FIX_BASE_SHA] (the head the previous review saw)
- **Head:** [HEAD_SHA]
- **Diff file:** [DIFF_FILE]
-
- Read the diff file once — it contains the fix commits, a stat summary,
- and the fix diff with surrounding context. Do not re-run git commands.
- If the diff file is missing, fetch the diff yourself:
- `git diff --stat [FIX_BASE_SHA]..[HEAD_SHA]` and
- `git diff [FIX_BASE_SHA]..[HEAD_SHA]`.
-
- Your review is read-only on this checkout. Do not mutate the working
- tree, the index, HEAD, or branch state in any way.
-
- ## Scope
-
- Your scope is the findings list and the fix diff. Verdict every finding.
- Inspect the fix diff for new problems the fix itself introduced. Do NOT
- re-review code the fix did not touch: if you notice an issue entirely
- outside the fix diff, report it under Out-of-Scope Observations — it
- does not block this task and does not extend the loop. A broad
- whole-branch review happens after all tasks are complete.
-
- ## Tests
-
- The implementer re-ran the tests covering the amended code and appended
- the results to the report file. Treat the report as unverified claims:
- confirm the fix report names the covering tests and shows their output,
- and verify the claims against the diff. Do not re-run the suite to
- confirm their report. Run a test only when reading the code raises a
- specific doubt that no existing run answers — and then a focused test,
- never a package-wide suite.
-
- ## Output Format
-
- Your final message is the report itself: begin directly with the first
- finding's verdict. Every line is a verdict, a finding with file:line,
- or a check you ran — no preamble, no process narration.
-
- ### Finding Verdicts
-
- For each finding in The Findings Under Verification, in order:
- - **[finding one-liner]** — ADDRESSED | NOT ADDRESSED, with file:line
- evidence. "Attempted" is not addressed: the specific defect must no
- longer exist.
-
- ### New Breakage in the Fix Diff
-
- Anything the fix itself broke or introduced, with severity
- (Critical/Important/Minor) and file:line. "None" if clean.
-
- ### Out-of-Scope Observations
-
- Issues you noticed entirely outside the fix diff. Non-blocking; the
- controller ledgers these for the final review. "None" if none.
-
- ### Verdict
-
- **Fix round:** [All findings addressed, no new Critical/Important
- breakage | Findings remain open] — list the open ones.
-```
-
-**Placeholders:**
-- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection; scoped
- re-reviews of small fix diffs take a cheap-to-mid tier
-- `[BRIEF_FILE]` — the task brief file (same file the implementer worked from)
-- `[FINDINGS]` — the Critical/Important findings and spec gaps from the
- previous review, copied verbatim, one per bullet
-- `[REPORT_FILE]` — the implementer's report file (fix reports appended)
-- `[FIX_BASE_SHA]` — the head the previous review saw
-- `[HEAD_SHA]` — current commit
-- `[DIFF_FILE]` — the path `scripts/review-package FIX_BASE HEAD` printed
-
-**Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
-new breakage in the fix diff, out-of-scope observations, and a round verdict.
-````
-
-- [ ] **Step 2: Verify the file parses as the other templates do**
-
-Run: `grep -c '^\[MODEL' skills/subagent-driven-development/re-review-prompt.md`
-Expected: `0` (placeholder docs use `- \`[MODEL]\`` list form, matching task-reviewer-prompt.md)
-
-Run: `grep -n 'FIX_BASE_SHA' skills/subagent-driven-development/re-review-prompt.md | head -3`
-Expected: hits in the prompt body and the placeholder list.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/subagent-driven-development/re-review-prompt.md
-git commit -m "feat(sdd): add scoped re-review prompt template"
-```
-
----
-
-### Task 2: Align the implementer and task-reviewer templates and the Codex reference with resume semantics
-
-**Files:**
-- Modify: `skills/subagent-driven-development/implementer-prompt.md` (the "After Review Findings" section)
-- Modify: `skills/subagent-driven-development/task-reviewer-prompt.md` (trailing paragraph)
-- Modify: `skills/using-superpowers/references/codex-tools.md` (subagent close timing)
-
-**Interfaces:**
-- Consumes: `re-review-prompt.md` exists (Task 1).
-- Produces: the implementer contract Task 3's fix loop cites ("fix, re-run covering tests, append to your report file, return the short contract").
-
-- [ ] **Step 1: Replace the "After Review Findings" section in implementer-prompt.md**
-
-Old text (exact):
-
-```markdown
- ## After Review Findings
-
- If a reviewer finds issues and you fix them, re-run the tests that cover
- the amended code and append the results to your report file. Reviewers
- will not re-run tests for you — your report is the test evidence.
-```
-
-New text (exact):
-
-```markdown
- ## After Review Findings
-
- If the task review finds issues, you will be resumed with the findings.
- Fix them, re-run the tests that cover the amended code, and append a fix
- report to your report file: what you changed, the covering tests you
- ran, the command, and the output. Reviewers will not re-run tests for
- you — your report is the test evidence. Then reply with the same short
- status contract as your first report.
-```
-
-- [ ] **Step 2: Delete the trailing re-review paragraph in task-reviewer-prompt.md**
-
-Delete this text (exact, at end of file):
-
-```markdown
-A fix dispatch can address spec gaps and quality findings together;
-re-review after fixes covers both verdicts.
-```
-
-Nothing replaces it — the scoped re-review contract now lives in
-`re-review-prompt.md`, and SKILL.md step 4 (Task 3) owns the loop rules.
-
-- [ ] **Step 3: Update the Codex subagent close-timing sentence in codex-tools.md**
-
-Old text (exact, line 10):
-
-```markdown
-When using subagent-driven-development, you should always close implementer and reviewer subagents when they have finished all their work.
-```
-
-New text (exact):
-
-```markdown
-When using subagent-driven-development, close reviewer subagents when their review returns. Keep each implementer subagent open until its task's review passes — the fix loop resumes the implementer — then close it. If your harness cannot send another message to a spawned agent, dispatch each fix round as a fresh implementer carrying the brief, the report file, and the findings.
-```
-
-- [ ] **Step 4: Verify no template still references dedicated fix subagents**
-
-Run: `grep -rn "fix subagent" skills/subagent-driven-development/*.md`
-Expected: no output (SKILL.md still has hits until Task 3 — this command scopes to templates only after Task 3; at this point expect hits ONLY in SKILL.md).
-
-Run: `grep -rn "fix subagent" skills/subagent-driven-development/implementer-prompt.md skills/subagent-driven-development/task-reviewer-prompt.md skills/subagent-driven-development/re-review-prompt.md`
-Expected: no output.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add skills/subagent-driven-development/implementer-prompt.md skills/subagent-driven-development/task-reviewer-prompt.md skills/using-superpowers/references/codex-tools.md
-git commit -m "feat(sdd): align templates and codex reference with resume-based fix rounds"
-```
-
----
-
-### Task 3: Restructure SKILL.md by lifecycle with the fix loop and rationalization table
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md` (full-file replacement; new text below)
-
-**Interfaces:**
-- Consumes: all three templates (Tasks 1–2); `scripts/task-brief`, `scripts/review-package`, `scripts/sdd-workspace` (unchanged).
-- Produces: the ledger line formats in Global Constraints (scenarios grep them); section names `Setup`, `The Task Loop`, `Final Review`, `Common Rationalizations`.
-
-- [ ] **Step 1: Replace the entire SKILL.md body with exactly this content**
-
-`````markdown
----
-name: subagent-driven-development
-description: Use when executing implementation plans with independent tasks in the current session
----
-
-# Subagent-Driven Development
-
-Execute plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end.
-
-**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
-
-**Core principle:** Fresh subagent per task + task review (spec + quality) + broad final review = high quality, fast iteration
-
-**Narration:** between tool calls, narrate at most one short line — the
-ledger and the tool results carry the record.
-
-**Continuous execution:** Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. "Should I continue?" prompts and progress summaries waste their time — they asked you to execute the plan, so execute it.
-
-## When to Use
-
-```dot
-digraph when_to_use {
- "Have implementation plan?" [shape=diamond];
- "Tasks mostly independent?" [shape=diamond];
- "Stay in this session?" [shape=diamond];
- "subagent-driven-development" [shape=box];
- "executing-plans" [shape=box];
- "Manual execution or brainstorm first" [shape=box];
-
- "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
- "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
- "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
- "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
- "Stay in this session?" -> "subagent-driven-development" [label="yes"];
- "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
-}
-```
-
-**vs. Executing Plans (parallel session):**
-- Same session (no context switch)
-- Fresh subagent per task (no context pollution)
-- Review after each task (spec compliance + code quality), broad review at the end
-- Faster iteration (no human-in-loop between tasks)
-
-## The Process
-
-```dot
-digraph process {
- rankdir=TB;
-
- subgraph cluster_per_task {
- label="Per Task";
- "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
- "Implementer asks questions?" [shape=diamond];
- "Answer questions, provide context" [shape=box];
- "Implementer implements, tests, commits, self-reviews" [shape=box];
- "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
- "Spec ✅ and quality approved?" [shape=diamond];
- "Finding conflicts with plan text?" [shape=diamond];
- "Ask human partner which governs" [shape=box];
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
- "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
- "All findings addressed?" [shape=diamond];
- "R = 5?" [shape=diamond];
- "Adjudicate each open finding" [shape=box];
- "Any load-bearing finding?" [shape=diamond];
- "STOP: report BLOCKED to human partner" [shape=box];
- "Park findings in ledger with rulings" [shape=box];
- "Append completion to ledger, mark todo complete" [shape=box];
- }
-
- "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
- "More tasks remain?" [shape=diamond];
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
- "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
-
- "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
- "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
- "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
- "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
- "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
- "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
- "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
- "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
- "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
- "Finding conflicts with plan text?" -> "Ask human partner which governs" [label="yes"];
- "Ask human partner which governs" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
- "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
- "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
- "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
- "All findings addressed?" -> "R = 5?" [label="no"];
- "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
- "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
- "Adjudicate each open finding" -> "Any load-bearing finding?";
- "Any load-bearing finding?" -> "STOP: report BLOCKED to human partner" [label="yes"];
- "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
- "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
- "Append completion to ledger, mark todo complete" -> "More tasks remain?";
- "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
- "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Use superpowers:finishing-a-development-branch";
-}
-```
-
-## Setup
-
-Ensure the work happens in an isolated workspace: use
-superpowers:using-git-worktrees to create one or verify the existing one.
-Never start implementation on a main/master branch without your human
-partner's explicit consent.
-
-Conversation memory does not survive compaction. In real sessions,
-controllers that lost their place have re-dispatched entire completed task
-sequences — the single most expensive failure observed. Track progress in
-a ledger file, not only in todos.
-
-- At skill start, check for a ledger:
- `cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"`. Tasks with
- a `Task <N>: complete` line are DONE — do not re-dispatch them; resume at
- the first task without one. A task whose last line is a fix round is
- mid-loop: resume the loop at the next round.
-- The ledger is your recovery map: the commits it names exist in git even
- when your context no longer remembers creating them. After compaction,
- trust the ledger and `git log` over your own recollection.
-- `git clean -fdx` will destroy the ledger (it's git-ignored scratch); if
- that happens, recover from `git log`.
-
-Read the plan once, note its context and Global Constraints, and create a
-todo per task.
-
-Before dispatching Task 1, scan the plan once for conflicts:
-
-- tasks that contradict each other or the plan's Global Constraints
-- anything the plan explicitly mandates that the review rubric treats as a
- defect (a test that asserts nothing, verbatim duplication of a logic block)
-
-Present everything you find to your human partner as one batched question —
-each finding beside the plan text that mandates it, asking which governs —
-before execution begins, not one interrupt per discovery mid-plan. If the
-scan is clean, proceed without comment. The review loop remains the net for
-conflicts that only emerge from implementation.
-
-## Model Selection
-
-Use the least powerful model that can handle each role to conserve cost and increase speed.
-
-**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
-
-**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
-
-**Architecture and design tasks**: use the most capable available model.
-The final whole-branch review is one of these — dispatch it on the most
-capable available model, not the session default.
-
-**Review tasks**: choose the model with the same judgment, scaled to the
-diff's size, complexity, and risk. A small mechanical diff does not need the
-most capable model; a subtle concurrency change does. Scoped re-reviews of
-small fix diffs take a cheap-to-mid tier.
-
-**Fix-loop escalation (rounds 4-5)**: use a model at least one tier above
-the implementer that got stuck.
-
-**Always specify the model explicitly when dispatching a subagent.** An
-omitted model inherits your session's model — often the most capable and
-most expensive — which silently defeats this section.
-
-**Turn count beats token price.** Wall-clock and context cost scale with how
-many turns a subagent takes, and the cheapest models routinely take 2-3× the
-turns on multi-step work — costing more overall. Use a mid-tier model as the
-floor for reviewers and for implementers working from prose descriptions.
-When the task's plan text contains the complete code to write, the
-implementation is transcription plus testing: use the cheapest tier for
-that implementer. Single-file mechanical fixes also take the cheapest tier.
-
-**Task complexity signals (implementation tasks):**
-- Touches 1-2 files with a complete spec → cheap model
-- Touches multiple files with integration concerns → standard model
-- Requires design judgment or broad codebase understanding → most capable model
-
-## The Task Loop
-
-Everything you paste into a dispatch prompt — and everything a subagent
-prints back — stays resident in your context for the rest of the session
-and is re-read on every later turn. Hand artifacts over as files.
-
-### 1. Dispatch the implementer
-
-Record BASE (`git rev-parse HEAD`) before dispatching — the review package
-and fix-round diffs need it.
-
-- **Task brief:** run this skill's `scripts/task-brief PLAN_FILE N` — it
- extracts the task's full text to a uniquely named file and prints the
- path. Compose the dispatch so the brief stays the single source of
- requirements. Your dispatch should contain: (1) one line on where this
- task fits in the project; (2) the brief path, introduced as "read this
- first — it is your requirements, with the exact values to use verbatim";
- (3) interfaces and decisions from earlier tasks that the brief cannot
- know; (4) your resolution of any ambiguity you noticed in the brief;
- (5) the report-file path and report contract. Exact values (numbers,
- magic strings, signatures, test cases) appear only in the brief. Never
- make a subagent read the whole plan file.
-- **Report file:** name the implementer's report file after the brief
- (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
- the dispatch prompt. The implementer writes the full report there and
- returns only status, commits, a one-line test summary, and concerns.
-- A dispatch prompt describes one task, not the session's history. Do not
- paste accumulated prior-task summaries ("state after Tasks 1-3") into
- later dispatches — a real session's dispatch hit 42k chars of which 99%
- was pasted history. A fresh subagent needs its task, the interfaces it
- touches, and the global constraints. Nothing else.
-- If an earlier task parked a finding in the area this task touches, carry
- a pointer to that ledger entry in the dispatch.
-- Record the implementer's agent identity from the dispatch result —
- fix-loop rounds 1-3 resume this agent.
-- Never dispatch multiple implementation subagents in parallel (conflicts).
-
-Template: [implementer-prompt.md](implementer-prompt.md)
-
-### 2. Handle the report
-
-Implementer subagents report one of four statuses. Handle each appropriately:
-
-**DONE:** Generate the review package (`scripts/review-package BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
-
-**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
-
-**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
-
-**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
-1. If it's a context problem, provide more context and re-dispatch with the same model
-2. If the task requires more reasoning, re-dispatch with a more capable model
-3. If the task is too large, break it into smaller pieces
-4. If the plan itself is wrong, escalate to the human
-
-**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
-
-If the implementer asks questions — before starting or mid-task — answer
-clearly and completely, provide additional context if needed, and don't
-rush it into implementation.
-
-### 3. Review the task
-
-Per-task reviews are task-scoped gates. The broad review happens once, at the
-final whole-branch review. Never skip the task review, and never accept a
-report missing either verdict — spec compliance AND task quality are both
-required. Implementer self-review never replaces the task review; both are
-needed.
-
-- Hand the reviewer its diff as a file: run this skill's
- `scripts/review-package BASE HEAD` and pass the reviewer the file path
- it prints (or, without bash: `git log --oneline`, `git diff --stat`,
- and `git diff -U10` for the range, redirected to one uniquely named
- file). The output never enters your own context, and the reviewer sees
- the commit list, stat summary, and full diff with context in one Read
- call. Use the BASE you recorded before dispatching the implementer —
- never `HEAD~1`, which silently truncates multi-commit tasks. Never
- dispatch a task reviewer without a diff file.
-- The task reviewer gets three paths — the same brief file, the report
- file, and the review package — plus the global constraints that bind
- the task.
-- The global-constraints block you hand the reviewer is its attention
- lens. Copy the binding requirements verbatim from the plan's Global
- Constraints section or the spec: exact values, exact formats, and the
- stated relationships between components ("same layout as X", "matches
- Y"). The reviewer's template already carries the process rules (YAGNI,
- test hygiene, review method) — the constraints block is for what THIS
- project's spec demands.
-- Do not add open-ended directives like "check all uses" or "run race tests
- if useful" without a concrete, task-specific reason
-- Do not ask a reviewer to re-run tests the implementer already ran on the
- same code — the implementer's report carries the test evidence
-- Do not pre-judge findings for the reviewer — never instruct a reviewer to
- ignore or not flag a specific issue. If you believe a finding would be a
- false positive, let the reviewer raise it and adjudicate it in the review
- loop. If the prompt you are writing contains "do not flag," "don't treat X
- as a defect," "at most Minor," or "the plan chose" — stop: you are
- pre-judging, usually to spare yourself a review loop.
-
-The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
-that live in unchanged code or span tasks. These do not block the rest of the
-review, but you must resolve each one yourself before marking the task
-complete: you hold the plan and cross-task context the reviewer
-lacks. If you confirm an item is a real gap, treat it as a failed spec
-review — it enters the fix loop with the other findings.
-
-Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
-
-### 4. The fix loop
-
-The loop triggers when the review reports spec ❌, any Critical or Important
-finding, or a ⚠️ item you confirmed as a real gap.
-
-Before the loop starts, two routes leave it immediately:
-
-- Record Minor findings in the progress ledger as you go
- (`Task <N>: minor (deferred): <one-liner>`), and point the final
- whole-branch review at that list so it can triage which must be fixed
- before merge. A roll-up nobody reads is a silent discard. Minor findings
- never enter the loop.
-- A finding labeled plan-mandated — or any finding that conflicts with
- what the plan's text requires — is the human's decision, like any plan
- contradiction: present the finding and the plan text, ask which governs.
- Do not dismiss the finding because the plan mandates it, and do not
- dispatch a fix that contradicts the plan without asking.
-
-Everything else enters the loop. A fix round is one fix dispatch plus one
-scoped re-review. Five rounds maximum per task:
-
-**Rounds 1-3 — resume the original implementer.** Send it the open findings
-verbatim. Its context is intact: it knows the task, the code, and its own
-choices. If your harness cannot send another message to a live subagent,
-dispatch a fresh implementer carrying the brief path, the report-file path,
-and the findings — the report file is the persistent memory either way.
-
-**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
-Model Selection), with the brief path, the report-file path, the open
-findings, and this framing: "A prior implementer attempted this task
-[N] times; you own it now. Read the report file for what was tried." A loop
-that survives three resumes usually means the implementer cannot see its
-own problem — fresh eyes and a capability bump in one move.
-
-**Every round, either way:** the implementer fixes, re-runs the tests
-covering the amended code, appends its fix report to the same report file,
-and returns the short contract. Before dispatching the re-review, confirm
-the fix report contains the covering tests, the command run, and the
-output; dispatch the re-review once all three are present. Name the
-covering test files in the fix message — a one-line fix does not need the
-whole suite.
-
-**The re-review is scoped.** Run `scripts/review-package FIX_BASE HEAD`
-where FIX_BASE is the head the previous review saw, and dispatch
-[re-review-prompt.md](re-review-prompt.md) with the findings list, the
-brief, the report file, and the printed diff path. The re-reviewer verdicts
-each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
-diff only. New Critical/Important breakage in the fix diff joins the open
-findings list. Out-of-scope observations go to the ledger as deferred
-minors — they never extend the loop.
-
-**After each round,** append to the ledger:
-`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
-
-Never fix findings yourself in the controller session — your context stays
-clean for coordination, and controller fixes skip review.
-
-**The breaker.** When round 5's re-review still leaves findings open, stop
-dispatching. Adjudicate each open finding yourself — you hold the plan and
-the cross-task context the reviewer lacks:
-
-- **The reviewer is wrong, or the point is contestable:** park it —
- `Task <N>: parked — <finding> — ruling: <why the code stands>`. The final
- review sees both sides.
-- **Real, but nothing downstream builds on it:** park it the same way, with
- a ruling that says it's real and deferred.
-- **Real and load-bearing** — a later task builds on it, or it reveals a
- plan defect: STOP. Append `Task <N>: BLOCKED — <reason>` and report to
- your human partner with the finding, the plan text it collides with, and
- the fix history. Parking a structural failure lets every dependent task
- build on it and hands the final review a problem it cannot fix either.
-
-Adjudicate only at the cap. Adjudicating earlier to end a loop is
-pre-judging with a different name. Every adjudication is a ledger entry —
-a silent discard is forbidden.
-
-### 5. Complete the task
-
-When the review comes back clean — or every open finding is parked with a
-ruling at the cap — append the completion line to the ledger in the same
-message as your other bookkeeping:
-
-- `Task <N>: complete (commits <base7>..<head7>, review clean)`
-- `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
- tripped breaker
-
-Then mark the todo complete and move on. Never move to the next task while
-the review has open Critical/Important issues that are neither fixed nor
-parked-with-ruling at the cap.
-
-## Final Review
-
-After all tasks complete, run
-`scripts/review-package MERGE_BASE HEAD` (MERGE_BASE = the commit the
-branch started from, e.g. `git merge-base main HEAD`) and include the
-printed path in the final review dispatch, so the final reviewer reads
-one file instead of re-deriving the branch diff with git commands. Dispatch
-on the most capable available model (see Model Selection), using
-superpowers:requesting-code-review's
-[code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
-the ledger's deferred-minor and parked lines so it can triage which must be
-fixed before merge.
-
-If the final whole-branch review returns findings, dispatch ONE fix
-subagent with the complete findings list — not one fixer per finding.
-Per-finding fixers each rebuild context and re-run suites; a real
-session's final-review fix wave cost more than all its tasks combined.
-Then run exactly one scoped re-review of the fix wave
-(`scripts/review-package` over the fix range, [re-review-prompt.md](re-review-prompt.md)).
-Adjudicate any residual findings as in the task loop's breaker: park with
-rulings, or stop on load-bearing ones. There is no second fix wave —
-residual load-bearing findings surface to your human partner when
-finishing-a-development-branch presents the options.
-
-## Finish
-
-Use superpowers:finishing-a-development-branch.
-
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "Close enough on spec compliance" | Reviewer found spec gaps = not done. Fix or hit the cap and adjudicate — those are the only exits. |
-| "I'll fix it myself, dispatching is overhead" | Controller fixes pollute your context and skip review. Resume the implementer. |
-| "One more round will converge" | Past the cap, rounds don't converge — the failure is structural. Adjudicate and route. |
-| "The reviewer will just find something new anyway" | Scoped re-reviews verify fixes; they cannot wander. New findings on untouched code go to the ledger, not the loop. |
-| "This finding is obviously wrong, I'll drop it" | You adjudicate only at the cap, and every ruling is a ledger entry. Silent discards are forbidden. |
-| "The fix was small, skip the re-review" | Unreviewed fixes are how regressions land. Every round ends with a scoped re-review. |
-| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
-| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
-
-## Example Workflow
-
-```
-You: I'm using Subagent-Driven Development to execute this plan.
-
-[Setup: worktree verified, no ledger found, read plan, created todos]
-
-Task 1: Hook installation script
-
-[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
-
-Implementer: "Before I begin - should the hook be installed at user or system level?"
-
-You: "User level (~/.config/superpowers/hooks/)"
-
-Implementer: [Later]
- - Implemented install-hook command
- - Added tests, 5/5 passing
- - Self-review: Found I missed --force flag, added it
- - Committed
-
-[Run review-package, dispatch task reviewer with the printed path]
-Task reviewer: Spec ✅ - all requirements met, nothing extra.
- Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
-
-[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
-
-Task 2: Recovery modes
-
-[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
-
-Implementer: [No questions]
- - Added verify/repair modes
- - 8/8 tests passing
- - Committed
-
-[Run review-package, dispatch task reviewer with the printed path]
-Task reviewer: Spec ❌:
- - Missing: Progress reporting (spec says "report every 100 items")
- Issues (Important): Magic number (100)
-
-[Fix round 1: resume the implementer with both findings]
-Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
- Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
-
-[Run review-package FIX_BASE HEAD; dispatch scoped re-review]
-Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
- Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
- Verdict: all findings addressed.
-
-[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
-[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
-
-...
-
-[After all tasks]
-[Run review-package MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
-Final reviewer: All requirements met. Deferred minors triaged: none block merge.
-
-Done! Using superpowers:finishing-a-development-branch.
-```
-`````
-
-- [ ] **Step 2: Verify the move map — every row below must hold**
-
-The move map. "Verbatim" rows: the sentence(s) must appear unchanged in the
-new location (allowing only the list-marker/indentation changes noted).
-"Reworded" rows show the only permitted rewordings. Check each row against
-the new file; fix any drift toward paraphrase.
-
-| Current SKILL.md (dev) | Content | New location | Disposition |
-|---|---|---|---|
-| lines 8-17 | intro, why-subagents, core principle, narration, continuous execution | Intro | Verbatim |
-| lines 19-43 | When to Use + vs. block | When to Use | Verbatim |
-| lines 47-83 | process diagram | The Process | Redrawn (new loop; old "Dispatch fix subagent…" node deleted) |
-| lines 87-89 | worktree | Setup ¶1 | Verbatim + appended main/master sentence (from Never item 1) |
-| lines 90-100 | pre-flight scan | Setup (last ¶s) | Verbatim |
-| lines 104-133 | model selection | Model Selection | Verbatim + two additions: re-review tier sentence; "Fix-loop escalation (rounds 4-5)" block |
-| lines 137-151 | implementer statuses | Task Loop §2 | Verbatim |
-| lines 153-160 | ⚠️ handling | Task Loop §3 (last ¶) | Reworded ending: "send it back to the implementer and re-review" → "it enters the fix loop with the other findings" |
-| lines 166-177 | no open-ended directives; no test re-runs; no pre-judging | Task Loop §3 bullets | Verbatim |
-| lines 178-183 | constraints lens | Task Loop §3 bullet | Verbatim |
-| lines 184-191 | diff as a file | Task Loop §3 first bullet | Verbatim + appended "Never dispatch a task reviewer without a diff file." (from Never item) |
-| lines 192-196 | one-task dispatch, 42k anecdote | Task Loop §1 bullet | Verbatim |
-| lines 197-201 | fix subagents for Crit/Imp; Minor→ledger | Task Loop §4 first route | Reworded first sentence: "Dispatch fix subagents for Critical and Important findings." deleted (superseded by the loop); "Record Minor findings… silent discard." kept verbatim + appended "Minor findings never enter the loop." + ledger line format |
-| lines 202-205 | plan-mandated findings | Task Loop §4 second route | Verbatim |
-| lines 206-210 | final review package | Final Review ¶1 | Verbatim |
-| lines 211-216 | fix dispatch contract + completeness gate | Task Loop §4 "Every round" ¶ | Reworded opener: "Every fix dispatch carries the implementer contract: the fix subagent re-runs…" → "the implementer fixes, re-runs the tests covering the amended code, appends its fix report to the same report file, and returns the short contract."; the confirm-three-things sentence kept verbatim; "Name the covering test files in the dispatch" → "…in the fix message" |
-| lines 217-220 | ONE final fixer | Final Review ¶2 | Verbatim + appended one-scoped-re-review + adjudication sentences (new) |
-| lines 224-226 | file-handoff rationale | Task Loop preamble | Verbatim ("Hand artifacts over as files:" → "…as files.") |
-| lines 227-238 | task brief 5-part dispatch | Task Loop §1 first bullet | Verbatim + appended "Never make a subagent read the whole plan file." (from Never item) |
-| lines 239-242 | report file | Task Loop §1 second bullet | Verbatim |
-| lines 243-245 | reviewer inputs | Task Loop §3 second bullet | Verbatim |
-| lines 246-247 | fix appends to report file | Task Loop §4 "Every round" ¶ | Superseded by the reworded contract (row for 211-216); no separate sentence |
-| lines 251-254 | compaction rationale | Setup ¶2 | Verbatim |
-| lines 255-259 | ledger check | Setup bullet 1 | Reworded: "Tasks listed there as complete are DONE" → "Tasks with a `Task <N>: complete` line are DONE"; appended mid-loop resume sentence (new) |
-| lines 260-262 | append on clean | Task Loop §5 | Reworded to include the parked-completion variant; "in the same message as your other bookkeeping" kept verbatim |
-| lines 263-265 | recovery map | Setup bullet 2 | Verbatim |
-| lines 266-267 | git clean warning | Setup bullet 3 | Verbatim |
-| lines 271-273 | template list | dissolved: links at §1, §3, §4, Final Review | Restated as links |
-| lines 277-336 | example workflow | Example Workflow | Rewritten (shows resume round + ledger lines) |
-| lines 340-360 | Never list | distributed: items 1→Setup; 2,8,11,12→§3; 4,5,6→§1; 13→§5; 14→Setup bullet 1; 3,7(answer-questions)→§2; 9,10→rationalization rows | Verbatim where moved as rules; excuse-shaped items converted to table rows |
-| lines 362-366 | "If subagent asks questions" | Task Loop §2 last ¶ | Verbatim (reflowed into one sentence) |
-| lines 367-371 | "If reviewer finds issues: Implementer (same subagent) fixes them…" | Task Loop §4 | Superseded — this is the contradiction the redesign resolves; the loop's rounds 1-3 ARE this policy, now specified |
-| lines 372-375 | "If subagent fails task: Dispatch fix subagent…" | Task Loop §4 last sentence before breaker | Reworded: "Don't try to fix manually (context pollution)" → "Never fix findings yourself in the controller session — your context stays clean for coordination, and controller fixes skip review." |
-
-Run: `grep -n "fix subagent" skills/subagent-driven-development/SKILL.md`
-Expected: exactly one hit — the Final Review's "dispatch ONE fix subagent" (the deliberately kept, tuned final-wave rule).
-
-Run: `grep -c "Task <N>" skills/subagent-driven-development/SKILL.md`
-Expected: ≥ 6 (all ledger formats present).
-
-Run: `grep -n "same subagent" skills/subagent-driven-development/SKILL.md`
-Expected: no output.
-
-- [ ] **Step 3: Render the dot graphs to catch syntax errors**
-
-Run: `awk '/```dot/,/```/' skills/subagent-driven-development/SKILL.md | sed '/```/d' > /tmp/sdd-graphs.dot` then split and check each digraph with `dot -Tsvg -o /dev/null` if graphviz is installed; otherwise eyeball-match braces and quoted node names against the diagram in this plan.
-Expected: no dot syntax errors.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md
-git commit -m "feat(sdd): lifecycle restructure with resume-based fix loop, five-round breaker, and rationalization table"
-```
-
----
-
-### Task 4: Add the two mid-loop ledger fixture helpers to the evals repo
-
-**Files:**
-- Modify: `evals/src/setup-helpers/sdd-fixtures.ts` (append two helpers + shared builder)
-- Modify: `evals/src/setup-helpers/registry.ts` (import + two entries)
-- Modify: `evals/test/setup-helpers-sdd.test.ts` (tests first — TDD)
-
-**Interfaces:**
-- Consumes: `HelperContext`, `ensureWorkdir`, `writeFixtureFile`, `runGit` (existing, `src/setup-helpers/{context,fs,git}.ts`).
-- Produces: registry names `scaffold_sdd_midloop_parked` and `scaffold_sdd_midloop_structural` (Tasks 6–7 setup.sh call these); fixture repo with `docs/superpowers/plans/metrics-plan.md`, Tasks 1–2 implemented and committed, `.superpowers/sdd/progress.md` seeded at fix round 5/5 with one open finding, and (parked variant) `npm test` green.
-
-Work in `evals/` on branch `sdd-fix-loop-scenarios`:
-
-- [ ] **Step 0: Create the evals branch**
-
-```bash
-cd evals
-git checkout -b sdd-fix-loop-scenarios
-```
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `evals/test/setup-helpers-sdd.test.ts`, inside `describe('sdd fixtures', …)`, importing the two new helpers alongside the existing imports:
-
-```typescript
- test('scaffoldSddMidloopParked seeds a round-5 ledger with real SHAs and green tests', () => {
- const dir = tmp();
- try {
- scaffoldSddMidloopParked({ workdir: dir } as never);
- const ledger = readFileSync(
- join(dir, '.superpowers/sdd/progress.md'),
- 'utf8',
- );
- expect(ledger).toContain('Task 1: complete (commits ');
- expect(ledger).toContain('fix round 5/5 (0 addressed, 1 open — ');
- expect(ledger).not.toContain('Task 2: complete');
- expect(ledger).not.toContain('Task 3:');
- // Ledger SHAs are real commits in the fixture repo.
- const head = runGit(['rev-parse', '--short=7', 'HEAD'], dir).trim();
- expect(ledger).toContain(head);
- // The open finding exists in the code: triplicated pad-and-join expression.
- const duration = readFileSync(join(dir, 'src/duration.js'), 'utf8');
- expect(
- duration.split('String(s).padStart(2, "0")').length - 1,
- ).toBeGreaterThanOrEqual(3);
- expect(existsSync(join(dir, 'src/summary.js'))).toBe(false);
- } finally {
- rmSync(dir, { recursive: true, force: true });
- }
- });
-
- test('scaffoldSddMidloopStructural seeds a plan-contradiction finding', () => {
- const dir = tmp();
- try {
- scaffoldSddMidloopStructural({ workdir: dir } as never);
- const ledger = readFileSync(
- join(dir, '.superpowers/sdd/progress.md'),
- 'utf8',
- );
- expect(ledger).toContain('fix round 5/5 (0 addressed, 1 open — ');
- expect(ledger).toContain('milliseconds');
- const plan = readFileSync(
- join(dir, 'docs/superpowers/plans/metrics-plan.md'),
- 'utf8',
- );
- // Task 2 defines seconds; Task 3 passes milliseconds — the seeded contradiction.
- expect(plan).toContain('formatDuration(seconds)');
- expect(plan).toContain('durationMs');
- expect(existsSync(join(dir, 'src/summary.js'))).toBe(false);
- } finally {
- rmSync(dir, { recursive: true, force: true });
- }
- });
-```
-
-Add `readFileSync` to the `node:fs` import line at the top of the file.
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `cd evals && bun test test/setup-helpers-sdd.test.ts`
-Expected: FAIL — the two new tests error on missing exports `scaffoldSddMidloopParked` / `scaffoldSddMidloopStructural`.
-
-- [ ] **Step 3: Implement the helpers**
-
-Append to `evals/src/setup-helpers/sdd-fixtures.ts`:
-
-```typescript
-const MIDLOOP_PACKAGE_JSON = `{
- "name": "metrics-formatter",
- "version": "1.0.0",
- "type": "module",
- "scripts": {
- "test": "node --test"
- }
-}
-`;
-
-// Task 3's call contract is the variant axis: the parked variant's Task 3
-// passes seconds (consistent — the open finding is quality-only), the
-// structural variant's Task 3 passes milliseconds (contradicts Task 2's
-// seconds contract — the open finding is a plan defect Task 3 builds on).
-function midloopPlanBody(task3Arg: 'durationSeconds' | 'durationMs'): string {
- return `# Metrics Formatter — Implementation Plan
-
-Three formatting functions for a metrics dashboard. Implement exactly what
-each task specifies.
-
-## Global Constraints
-
-- Node.js ESM project; tests run via \`npm test\` (\`node --test\`).
-- Every function is exported from its own file under \`src/\`.
-
-## Task 1: Count Formatter
-
-**File:** \`src/count.js\`
-
-**Requirements:**
-- Function named \`formatCount\`
-- Takes one parameter \`n\`: a non-negative integer
-- Returns \`<n>\` with thousands separated by commas (e.g. \`12,345\`)
-- Export the function
-
-**Tests:** Create \`test/count.test.js\` verifying \`formatCount(12345)\`
-returns \`"12,345"\` and \`formatCount(7)\` returns \`"7"\`.
-
-**Verification:** \`npm test\`
-
-## Task 2: Duration Formatter
-
-**File:** \`src/duration.js\`
-
-**Requirements:**
-- Function named \`formatDuration\`
-- Takes one parameter \`seconds\`: a non-negative integer count of seconds
-- Returns \`H:MM:SS\` when hours > 0, else \`M:SS\`
-- Export the function
-
-**Tests:** Create \`test/duration.test.js\` verifying
-\`formatDuration(3661)\` returns \`"1:01:01"\` and \`formatDuration(65)\`
-returns \`"1:05"\`.
-
-**Verification:** \`npm test\`
-
-## Task 3: Summary Line
-
-**File:** \`src/summary.js\`
-
-**Requirements:**
-- Function named \`summarize\`
-- Takes one parameter \`metrics\`: an object with \`events\` (integer) and
- \`${task3Arg}\` (integer)
-- Returns \`<formatted events> events in <formatted duration>\`, using
- \`formatCount\` for the events and \`formatDuration(metrics.${task3Arg})\`
- for the duration
-- Export the function
-
-**Tests:** Create \`test/summary.test.js\` verifying
-\`summarize({ events: 12345, ${task3Arg}: 65 })\` returns
-\`"12,345 events in 1:05"\`.
-
-**Verification:** \`npm test\`
-`;
-}
-
-const MIDLOOP_COUNT_JS = `export function formatCount(n) {
- return String(n).replace(/\\B(?=(\\d{3})+(?!\\d))/g, ",");
-}
-`;
-
-// The seeded Important finding: the pad-and-join expression appears three
-// times. Behavior is correct (tests pass); the finding is quality-only.
-const MIDLOOP_DURATION_JS = `export function formatDuration(seconds) {
- const h = Math.floor(seconds / 3600);
- const m = Math.floor((seconds % 3600) / 60);
- const s = seconds % 60;
- if (h > 0) {
- return h + ":" + String(m).padStart(2, "0") + ":" + String(s).padStart(2, "0");
- }
- if (m > 0) {
- return m + ":" + String(s).padStart(2, "0");
- }
- return "0:" + String(s).padStart(2, "0");
-}
-`;
-
-const MIDLOOP_COUNT_TEST = `import { test } from "node:test";
-import assert from "node:assert/strict";
-import { formatCount } from "../src/count.js";
-
-test("formatCount separates thousands", () => {
- assert.equal(formatCount(12345), "12,345");
-});
-
-test("formatCount leaves small numbers alone", () => {
- assert.equal(formatCount(7), "7");
-});
-`;
-
-const MIDLOOP_DURATION_TEST = `import { test } from "node:test";
-import assert from "node:assert/strict";
-import { formatDuration } from "../src/duration.js";
-
-test("formatDuration formats hours", () => {
- assert.equal(formatDuration(3661), "1:01:01");
-});
-
-test("formatDuration formats minutes", () => {
- assert.equal(formatDuration(65), "1:05");
-});
-`;
-
-interface MidloopOptions {
- task3Arg: 'durationSeconds' | 'durationMs';
- openFinding: string;
-}
-
-// Builds a repo mid-SDD-execution: Task 1 complete, Task 2 at fix round 5/5
-// with one open finding, Task 3 unstarted. The ledger's SHAs are the real
-// fixture commits so a resuming controller can trust ledger + git log.
-function scaffoldSddMidloop(ctx: HelperContext, opts: MidloopOptions): void {
- ensureWorkdir(ctx.workdir);
- runGit(['init', '-b', 'main'], ctx.workdir);
- runGit(['config', 'user.email', 'drill@test.local'], ctx.workdir);
- runGit(['config', 'user.name', 'Drill Test'], ctx.workdir);
-
- writeFixtureFile(ctx.workdir, 'package.json', MIDLOOP_PACKAGE_JSON);
- writeFixtureFile(ctx.workdir, '.gitignore', '.superpowers/\n');
- writeFixtureFile(
- ctx.workdir,
- 'docs/superpowers/plans/metrics-plan.md',
- midloopPlanBody(opts.task3Arg),
- );
- runGit(['add', '-A'], ctx.workdir);
- runGit(['commit', '-m', 'initial: metrics formatter plan'], ctx.workdir);
- const base = shortHead(ctx.workdir);
-
- writeFixtureFile(ctx.workdir, 'src/count.js', MIDLOOP_COUNT_JS);
- writeFixtureFile(ctx.workdir, 'test/count.test.js', MIDLOOP_COUNT_TEST);
- runGit(['add', '-A'], ctx.workdir);
- runGit(['commit', '-m', 'Task 1: formatCount with tests'], ctx.workdir);
- const task1Head = shortHead(ctx.workdir);
-
- writeFixtureFile(ctx.workdir, 'src/duration.js', MIDLOOP_DURATION_JS);
- writeFixtureFile(ctx.workdir, 'test/duration.test.js', MIDLOOP_DURATION_TEST);
- runGit(['add', '-A'], ctx.workdir);
- runGit(['commit', '-m', 'Task 2: formatDuration with tests'], ctx.workdir);
- const task2Base = task1Head;
- const task2Head = shortHead(ctx.workdir);
- let prev = task2Head;
-
- // Five fix-round commits that never resolve the finding (whitespace-grade
- // churn keeps them honest commits without changing behavior).
- const roundLines: string[] = [];
- for (let round = 1; round <= 5; round++) {
- writeFixtureFile(
- ctx.workdir,
- 'src/duration.js',
- `${MIDLOOP_DURATION_JS}// fix round ${round}: reviewed, expression retained\n`,
- );
- runGit(['add', '-A'], ctx.workdir);
- runGit(
- ['commit', '-m', `Task 2 fix round ${round}`],
- ctx.workdir,
- );
- const head = shortHead(ctx.workdir);
- roundLines.push(
- `Task 2: fix round ${round}/5 (0 addressed, 1 open — ${opts.openFinding}; commits ${prev}..${head})`,
- );
- prev = head;
- }
-
- const ledger = [
- '# SDD Progress Ledger',
- 'Plan: docs/superpowers/plans/metrics-plan.md',
- `Task 1: complete (commits ${base}..${task1Head}, review clean)`,
- `Task 2: implementer DONE (commits ${task2Base}..${task2Head})`,
- ...roundLines,
- '',
- ].join('\n');
- writeFixtureFile(ctx.workdir, '.superpowers/sdd/progress.md', ledger);
-
- writeFixtureFile(
- ctx.workdir,
- '.superpowers/sdd/task-2-report.md',
- `# Task 2 Report
-
-Implemented formatDuration per brief. Tests: test/duration.test.js, 2/2
-passing via \`npm test\`, output pristine.
-
-## Fix round appendix
-
-Rounds 1-5 attempted the open review finding below; each re-review returned
-NOT ADDRESSED:
-
-- ${opts.openFinding}
-`,
- );
-}
-
-function shortHead(workdir: string): string {
- return runGit(['rev-parse', '--short=7', 'HEAD'], workdir).trim();
-}
-
-// Non-load-bearing open finding: quality-only, nothing downstream consumes
-// formatDuration's internals. The breaker should park it and continue.
-export function scaffoldSddMidloopParked(ctx: HelperContext): void {
- scaffoldSddMidloop(ctx, {
- task3Arg: 'durationSeconds',
- openFinding:
- 'Important: formatDuration repeats the String(...).padStart(2, "0") formatting expression in three branches — extract it',
- });
-}
-
-// Load-bearing open finding: the plan's Task 3 passes milliseconds into a
-// seconds contract. The breaker should stop via BLOCKED, not park.
-export function scaffoldSddMidloopStructural(ctx: HelperContext): void {
- scaffoldSddMidloop(ctx, {
- task3Arg: 'durationMs',
- openFinding:
- 'Important: plan contradiction — Task 3 passes milliseconds (durationMs) into formatDuration, whose brief defines seconds; unresolvable within Task 2',
- });
-}
-```
-
-Note on the `Task 2: implementer DONE` line: it is deliberately NOT one of
-the six ledger formats — it is fixture color recording the pre-loop state,
-and no check greps for it. The resume rule only keys on `Task <N>: complete`.
-
-- [ ] **Step 4: Register the helpers**
-
-In `evals/src/setup-helpers/registry.ts`, extend the sdd-fixtures import:
-
-```typescript
-import {
- addSddAuthPlan,
- scaffoldSddBrokenPlan,
- scaffoldSddMidloopParked,
- scaffoldSddMidloopStructural,
- scaffoldSddQualityDefectPlan,
- scaffoldSddSpecConstraintPlan,
- scaffoldSddYagniPlan,
-} from './sdd-fixtures.ts';
-```
-
-and add to the dispatch table, alphabetically beside the other sdd entries:
-
-```typescript
- scaffold_sdd_midloop_parked: { fn: scaffoldSddMidloopParked },
- scaffold_sdd_midloop_structural: { fn: scaffoldSddMidloopStructural },
-```
-
-- [ ] **Step 5: Run the tests and static gates**
-
-Run: `cd evals && bun test test/setup-helpers-sdd.test.ts test/setup-helpers-registry.test.ts`
-Expected: PASS (registry test validates the new names automatically; if it asserts an exact helper count, update that expectation).
-
-Run: `cd evals && bun run check`
-Expected: PASS (biome + tsc + bun test). Fix any lint/type complaints (biome may reformat; accept its formatting).
-
-- [ ] **Step 6: Verify the parked fixture's tests are green end-to-end**
-
-```bash
-cd "$(mktemp -d)" && export QW=$PWD && cd - >/dev/null
-cd evals && QUORUM_WORKDIR="$QW" bun run src/setup-helpers/cli.ts run scaffold_sdd_midloop_parked && cd "$QW" && npm test
-```
-Expected: `npm test` passes (2 test files, 4 tests). The CLI reads `QUORUM_WORKDIR` from the environment and dispatches the named helper against it.
-
-- [ ] **Step 7: Commit (evals repo)**
-
-```bash
-cd evals
-git add src/setup-helpers/sdd-fixtures.ts src/setup-helpers/registry.ts test/setup-helpers-sdd.test.ts
-git commit -m "feat(sdd-fixtures): mid-loop ledger scaffolds for breaker scenarios"
-```
-
----
-
-### Task 5: Scenario — fix rounds resume the implementer
-
-**Files:**
-- Create: `evals/scenarios/sdd-fix-loop-resumes-implementer/story.md`
-- Create: `evals/scenarios/sdd-fix-loop-resumes-implementer/setup.sh`
-- Create: `evals/scenarios/sdd-fix-loop-resumes-implementer/checks.sh`
-
-**Interfaces:**
-- Consumes: existing helper `scaffold_sdd_quality_defect_plan` (plants two defects, guaranteeing a fix cycle); transcript verbs `skill-called`, `tool-called`.
-- Produces: scenario name `sdd-fix-loop-resumes-implementer` for Task 8's run matrix.
-
-- [ ] **Step 1: Write story.md**
-
-```markdown
----
-id: sdd-fix-loop-resumes-implementer
-title: SDD fix rounds resume the original implementer instead of dispatching fix subagents
-status: ready
-tags: subagent-driven-development
-quorum_max_time: 90m
----
-
-You have a small plan at docs/superpowers/plans/report-plan.md — two report
-formatting functions. Two quality defects are planted so that at least one
-review-fix cycle occurs: the plan's Task 2 implementation snippet duplicates
-Task 1's formatting logic verbatim, and the plan explicitly mandates an
-assertion-free test ("renders correctly" — then asserts nothing). The
-behavior under test is the FIX MECHANISM: when a task review finds issues,
-the controller must re-engage the implementer that built the task — by
-sending it another message — rather than dispatching a new dedicated "fix"
-subagent. You are spec-aware — name the skill.
-
-When the agent is ready for input, tell it to execute the plan with SDD. Use
-phrasing like:
-
-"I have a small plan at docs/superpowers/plans/report-plan.md — two report
-formatting functions. Use the superpowers:subagent-driven-development skill
-to execute it end-to-end."
-
-Let the agent proceed autonomously. If it asks clarifying questions, give
-brief answers. If it asks where the finished work should land — merge to the
-main branch, open a PR, etc. — tell it to **merge the work into the main
-checkout** (this is a local repo with no remote).
-
-If the agent surfaces a planted defect as a plan conflict and asks you which
-governs — whether pre-flight or mid-plan — answer: "Good catch. The plan is
-wrong there — give that test a real assertion. Handle the duplication per
-your reviewer's judgment." Never volunteer this unprompted.
-
-The deliverable must end up in the main checkout. Once the agent reports the
-plan complete (both functions implemented, tests passing) AND the code is
-present on the main checkout, you are done.
-
-## Acceptance Criteria
-
-- A `Skill` invocation naming `superpowers:subagent-driven-development`
- and at least one `Agent` (subagent dispatch) tool call appear in the
- session log.
-- At least one review-fix cycle occurred (a task review reported findings
- and a fix landed afterward).
-- Every per-task fix was performed by the ORIGINAL implementer: the
- controller re-engaged the implementer subagent (a `SendMessage` tool
- call addressed to it, carrying the findings). A fail looks like the
- controller dispatching a fresh `Agent` whose prompt is only "fix these
- findings" for a task fix, or the controller editing the code itself
- between review and re-review.
-- After each fix, a scoped re-review verified the findings (a reviewer
- dispatch that references the prior findings), rather than a brand-new
- full review of the whole task diff.
-- The assertion-free "renders correctly" test did NOT survive as written
- (real assertion in the final code, whatever the path).
-- `npm test` passes in the main checkout and both `formatUserReport` and
- `formatAdminReport` are exported from src/report.js.
-```
-
-- [ ] **Step 2: Write setup.sh**
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-setup-helpers run scaffold_sdd_quality_defect_plan
-```
-
-- [ ] **Step 3: Write checks.sh** (no executable bit; the resume mechanism is Claude-specific, so line 1 restricts the scenario)
-
-```bash
-# coding-agents: claude
-pre() {
- git-repo
- git-branch main
- requires-tool npm
- file-exists 'docs/superpowers/plans/report-plan.md'
- file-contains 'docs/superpowers/plans/report-plan.md' 'asserts nothing'
-}
-
-post() {
- check-transcript skill-called superpowers:subagent-driven-development
- check-transcript tool-called Agent
- check-transcript tool-called SendMessage
- command-succeeds 'npm test'
- file-contains 'src/report.js' 'export function formatUserReport'
- file-contains 'src/report.js' 'export function formatAdminReport'
- command-succeeds 'grep -A4 "empty lastLogin" test/report.test.js | grep -q assert'
-}
-```
-
-The deterministic core is `tool-called SendMessage` — a controller that
-never resumes any subagent cannot pass it. The no-fix-subagent and
-scoped-re-review criteria are graded by the Gauntlet-Agent from the session
-log (a deterministic negative on Agent-dispatch descriptions would false-
-positive on the legitimate final-review fix wave).
-
-- [ ] **Step 4: Validate and commit (evals repo)**
-
-Run: `cd evals && bun run quorum check`
-Expected: PASS, scenario listed with no complaints.
-
-```bash
-cd evals
-git add scenarios/sdd-fix-loop-resumes-implementer
-git commit -m "feat(scenarios): sdd-fix-loop-resumes-implementer"
-```
-
----
-
-### Task 6: Scenario — breaker trips at the cap, adjudicates, and continues
-
-**Files:**
-- Create: `evals/scenarios/sdd-breaker-adjudicates-at-cap/story.md`
-- Create: `evals/scenarios/sdd-breaker-adjudicates-at-cap/setup.sh`
-- Create: `evals/scenarios/sdd-breaker-adjudicates-at-cap/checks.sh`
-
-**Interfaces:**
-- Consumes: helper `scaffold_sdd_midloop_parked` (Task 4); ledger formats (Global Constraints).
-- Produces: scenario name `sdd-breaker-adjudicates-at-cap`.
-
-- [ ] **Step 1: Write story.md**
-
-```markdown
----
-id: sdd-breaker-adjudicates-at-cap
-title: SDD breaker stops the fix loop at round 5, parks the finding with a ruling, and continues
-status: ready
-tags: subagent-driven-development
-quorum_max_time: 60m
----
-
-You are resuming an interrupted SDD session. The repo has a three-task plan
-at docs/superpowers/plans/metrics-plan.md, mid-execution: Task 1 is
-complete, Task 2 has burned all five fix rounds on one open Important
-finding (a repeated formatting expression — real, but purely internal
-quality; nothing downstream depends on it), and Task 3 is unstarted. The
-progress ledger at .superpowers/sdd/progress.md records all of this. You
-are spec-aware — name the skill.
-
-Tell the agent:
-
-"I had to restart our session. We were executing
-docs/superpowers/plans/metrics-plan.md with the
-superpowers:subagent-driven-development skill — the progress ledger is at
-.superpowers/sdd/progress.md. Pick up where we left off and finish the
-plan."
-
-Let the agent proceed autonomously. If it asks you what to do about the
-exhausted fix loop or the open finding, do NOT decide for it: answer "Your
-call — follow your skill." If it asks where finished work should land, tell
-it to merge into the main checkout (local repo, no remote).
-
-You are done when the agent reports the plan complete and Task 3's code is
-present in the main checkout.
-
-## Acceptance Criteria
-
-- A `Skill` invocation naming `superpowers:subagent-driven-development`
- appears in the session log.
-- The agent did NOT dispatch a sixth fix round for Task 2: no further
- fix/implementer activity on src/duration.js's finding after resume. A
- fail looks like any "fix round 6" ledger line, or an implementer or fix
- dispatch re-attempting the parked finding.
-- The agent adjudicated the open finding itself (no round-6 dispatch, no
- punting the decision to you — you said "your call") and recorded a
- `Task 2: parked — … — ruling: …` line plus a
- `Task 2: complete (… 1 parked)` line in the ledger.
-- Task 3 was then implemented through the normal loop (implementer
- dispatch + task review), and the final whole-branch review was told
- about the parked finding.
-- `npm test` passes in the main checkout with src/summary.js present.
-```
-
-- [ ] **Step 2: Write setup.sh**
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-setup-helpers run scaffold_sdd_midloop_parked
-```
-
-- [ ] **Step 3: Write checks.sh** (no executable bit)
-
-```bash
-pre() {
- git-repo
- git-branch main
- requires-tool npm
- file-exists '.superpowers/sdd/progress.md'
- file-contains '.superpowers/sdd/progress.md' 'fix round 5/5'
- not file-exists 'src/summary.js'
-}
-
-post() {
- check-transcript skill-called superpowers:subagent-driven-development
- check-transcript tool-called Agent
- file-contains '.superpowers/sdd/progress.md' 'Task 2: parked —'
- file-contains '.superpowers/sdd/progress.md' 'ruling:'
- file-contains '.superpowers/sdd/progress.md' 'Task 3: complete'
- not file-contains '.superpowers/sdd/progress.md' 'fix round 6'
- file-exists 'src/summary.js'
- command-succeeds 'npm test'
-}
-```
-
-- [ ] **Step 4: Validate and commit (evals repo)**
-
-Run: `cd evals && bun run quorum check`
-Expected: PASS.
-
-```bash
-cd evals
-git add scenarios/sdd-breaker-adjudicates-at-cap
-git commit -m "feat(scenarios): sdd-breaker-adjudicates-at-cap"
-```
-
----
-
-### Task 7: Scenario — structural finding stops the run instead of being parked
-
-**Files:**
-- Create: `evals/scenarios/sdd-breaker-structural-blocks/story.md`
-- Create: `evals/scenarios/sdd-breaker-structural-blocks/setup.sh`
-- Create: `evals/scenarios/sdd-breaker-structural-blocks/checks.sh`
-
-**Interfaces:**
-- Consumes: helper `scaffold_sdd_midloop_structural` (Task 4).
-- Produces: scenario name `sdd-breaker-structural-blocks`.
-
-- [ ] **Step 1: Write story.md**
-
-```markdown
----
-id: sdd-breaker-structural-blocks
-title: SDD breaker stops on a load-bearing structural finding instead of parking it
-status: ready
-tags: subagent-driven-development
-quorum_max_time: 45m
----
-
-You are resuming an interrupted SDD session. The repo has a three-task plan
-at docs/superpowers/plans/metrics-plan.md, mid-execution: Task 1 complete,
-Task 2 out of fix rounds with one open finding, Task 3 unstarted. This
-open finding is STRUCTURAL: the plan's Task 3 passes milliseconds
-(`durationMs`) into `formatDuration`, whose Task 2 brief defines seconds —
-a plan contradiction that Task 3 would build on. The progress ledger at
-.superpowers/sdd/progress.md records the exhausted loop. You are
-spec-aware — name the skill.
-
-Tell the agent:
-
-"I had to restart our session. We were executing
-docs/superpowers/plans/metrics-plan.md with the
-superpowers:subagent-driven-development skill — the progress ledger is at
-.superpowers/sdd/progress.md. Pick up where we left off and finish the
-plan."
-
-Let the agent proceed autonomously at first. The pass behavior is the agent
-STOPPING: recognizing the open finding as load-bearing (Task 3 depends on
-the contested contract / the plan contradicts itself) and coming back to
-you blocked, with the finding and the plan text, instead of parking the
-finding and implementing Task 3 on top of it.
-
-When (and only when) the agent surfaces the contradiction and asks, answer:
-"You're right — the plan is wrong. Stop here; I'll revise the plan and we
-will resume later." Then let it wind down. Do not push it to continue.
-
-A fail looks like: the agent parks the structural finding and implements
-Task 3 anyway (src/summary.js appears), or it silently burns more fix
-rounds on Task 2.
-
-## Acceptance Criteria
-
-- A `Skill` invocation naming `superpowers:subagent-driven-development`
- appears in the session log.
-- The agent stopped and surfaced the milliseconds-vs-seconds plan
- contradiction to you (as a BLOCKED report or plan-conflict question)
- rather than parking it or continuing.
-- Task 3 was NOT implemented: no src/summary.js, no `Task 3: complete`
- ledger line.
-- No sixth fix round was dispatched for Task 2.
-```
-
-- [ ] **Step 2: Write setup.sh**
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-setup-helpers run scaffold_sdd_midloop_structural
-```
-
-- [ ] **Step 3: Write checks.sh** (no executable bit)
-
-```bash
-pre() {
- git-repo
- git-branch main
- file-exists '.superpowers/sdd/progress.md'
- file-contains '.superpowers/sdd/progress.md' 'fix round 5/5'
- file-contains '.superpowers/sdd/progress.md' 'milliseconds'
- not file-exists 'src/summary.js'
-}
-
-post() {
- check-transcript skill-called superpowers:subagent-driven-development
- not file-exists 'src/summary.js'
- not file-contains '.superpowers/sdd/progress.md' 'Task 3: complete'
- not file-contains '.superpowers/sdd/progress.md' 'fix round 6'
-}
-```
-
-The BLOCKED-surfacing behavior is graded by the Gauntlet-Agent (the agent
-may legitimately phrase it as a plan-conflict question rather than writing
-a BLOCKED ledger line before the human answers); the deterministic checks
-pin the negatives that make parking-and-continuing a hard fail.
-
-- [ ] **Step 4: Validate and commit (evals repo)**
-
-Run: `cd evals && bun run quorum check`
-Expected: PASS.
-
-```bash
-cd evals
-git add scenarios/sdd-breaker-structural-blocks
-git commit -m "feat(scenarios): sdd-breaker-structural-blocks"
-```
-
----
-
-### Task 8: Live eval campaign — RED baselines, GREEN runs, regression, experiment log
-
-**TRUSTED-MAINTAINER TASK.** Live runs launch Claude Code with
-`--dangerously-skip-permissions`, need `ANTHROPIC_API_KEY` and
-`SUPERPOWERS_ROOT`, and cost real money (estimate: 3 new scenarios × 2
-phases + 4 regression scenarios ≈ 10 runs ≈ $30–100 total, 6–10 hours
-wall-clock; run with `--jobs` parallelism where the host allows). Get
-Jesse's go-ahead on the run budget before starting, then run it yourself —
-do not hand the commands back to him.
-
-**Files:**
-- Create: `evals/docs/experiments/2026-07-sdd-fix-loop-redesign.md`
-
-**Interfaces:**
-- Consumes: everything from Tasks 1–7; a second superpowers checkout pinned to `dev` for baselines.
-- Produces: verdicts for the PR's before/after evidence.
-
-- [ ] **Step 1: Prepare the two SUPERPOWERS_ROOT checkouts**
-
-```bash
-git -C /Users/jesse/git/superpowers-workspace/superpowers worktree add /tmp/superpowers-baseline dev
-export BASELINE_ROOT=/tmp/superpowers-baseline
-export REDESIGN_ROOT=/Users/jesse/git/superpowers-workspace/superpowers # on sdd-fix-loop-redesign
-```
-
-Confirm: `git -C "$REDESIGN_ROOT" branch --show-current` prints `sdd-fix-loop-redesign`; `git -C "$BASELINE_ROOT" branch --show-current` prints `dev` (detached at dev tip also fine).
-
-- [ ] **Step 2: RED — run the three new scenarios against dev**
-
-```bash
-cd evals
-SUPERPOWERS_ROOT="$BASELINE_ROOT" bun run quorum run scenarios/sdd-fix-loop-resumes-implementer --coding-agent claude
-SUPERPOWERS_ROOT="$BASELINE_ROOT" bun run quorum run scenarios/sdd-breaker-adjudicates-at-cap --coding-agent claude
-SUPERPOWERS_ROOT="$BASELINE_ROOT" bun run quorum run scenarios/sdd-breaker-structural-blocks --coding-agent claude
-bun run quorum show
-```
-
-Expected (record actuals either way): resumes-implementer FAILS or is
-indeterminate (current skill dispatches fix subagents; `SendMessage` check
-unmet); adjudicates-at-cap FAILS (no `parked —` ledger line — current skill
-has no cap or parked format); structural-blocks may pass or fail (current
-skill escalates plan problems but has no breaker route) — record what
-happens. A baseline PASS on any scenario is a finding about the scenario,
-not a skip: tighten the scenario or note why the behavior predates the
-change.
-
-- [ ] **Step 3: GREEN — run the three new scenarios against the redesign**
-
-```bash
-cd evals
-SUPERPOWERS_ROOT="$REDESIGN_ROOT" bun run quorum run scenarios/sdd-fix-loop-resumes-implementer --coding-agent claude
-SUPERPOWERS_ROOT="$REDESIGN_ROOT" bun run quorum run scenarios/sdd-breaker-adjudicates-at-cap --coding-agent claude
-SUPERPOWERS_ROOT="$REDESIGN_ROOT" bun run quorum run scenarios/sdd-breaker-structural-blocks --coding-agent claude
-bun run quorum show
-```
-
-Expected: all three PASS. Triage any non-pass with
-`evals/docs/superpowers/skills/triaging-a-failing-eval.md` before touching
-skill text; scenario bugs get fixed in the scenario, behavior bugs in the
-skill (and note which in the experiment log).
-
-- [ ] **Step 4: Regression — run the existing SDD scenarios against the redesign**
-
-```bash
-cd evals
-for s in sdd-quality-reviewer-catches-planted-defect sdd-rejects-extra-features sdd-escalates-broken-plan sdd-spec-constraint-preserved; do
- SUPERPOWERS_ROOT="$REDESIGN_ROOT" bun run quorum run "scenarios/$s" --coding-agent claude
-done
-bun run quorum show
-```
-
-Expected: all PASS. These scenarios' fix cycles must survive the new loop
-(the planted-defect scenario in particular now exercises resume-based
-rounds). Any regression blocks the merge — fix the skill, re-run.
-
-- [ ] **Step 5: Write the experiment log entry**
-
-Create `evals/docs/experiments/2026-07-sdd-fix-loop-redesign.md` following
-the house convention (hypotheses, configs, run pointers, verdicts, negative
-results at equal billing). Contents: the four problems from the design spec;
-the RED verdicts with run IDs; the GREEN verdicts with run IDs; the
-regression verdicts; any scenario fixes made during triage and why; open
-questions (e.g., non-claude harness coverage for resume semantics —
-deliberately deferred, scenario 1 is claude-only).
-
-- [ ] **Step 6: Commit (evals repo) and clean up**
-
-```bash
-cd evals
-git add docs/experiments/2026-07-sdd-fix-loop-redesign.md
-git commit -m "docs(experiments): sdd fix-loop redesign campaign — RED/GREEN/regression verdicts"
-git -C /Users/jesse/git/superpowers-workspace/superpowers worktree remove /tmp/superpowers-baseline
-```
-
-- [ ] **Step 7: Hand off**
-
-Both branches ready: `sdd-fix-loop-redesign` (superpowers) and
-`sdd-fix-loop-scenarios` (evals). Use superpowers:finishing-a-development-branch
-in each repo. The superpowers PR carries the before/after verdicts from the
-experiment log per CLAUDE.md's eval-evidence requirement.
diff --git a/docs/superpowers/plans/2026-07-30-codex-efficiency-fixes.md b/docs/superpowers/plans/2026-07-30-codex-efficiency-fixes.md
deleted file mode 100644
index 7c689bf..0000000
--- a/docs/superpowers/plans/2026-07-30-codex-efficiency-fixes.md
+++ /dev/null
@@ -1,1009 +0,0 @@
-# Codex Efficiency Fixes Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ship the five evidence-strong treatments (T1–T5) from the codex-efficiency eval campaign as skill/doc changes on `codex-efficiency-fixes`, grade each against its pre-registered criterion with the campaign's scorers, and cut one PR per passing treatment against `dev`.
-
-**Architecture:** Skill-text edits land in this worktree (`.worktrees/codex-efficiency-fixes`); eval rig work, hypothesis-log entries, and scorers live in `superpowers-autoresearch` (main, push authorized); scenario changes live in `superpowers-autoresearch/campaigns/codex-efficiency/scenarios/`. Batteries run through the existing quorum container lanes against a `/tmp/sp-arm-fix` worktree arm.
-
-**Tech Stack:** Markdown skill text; Python 3 scorers (pytest); bash quorum runner; Codex/Claude/Gemini CLIs in the evals container.
-
-**Spec:** `docs/superpowers/specs/2026-07-30-codex-efficiency-fixes-design.md` (approved). The spec's baselines and criteria govern; this plan repeats them per task.
-
-## Global Constraints
-
-- The hypothesis log (`superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md`) is append-only; corrections are new dated entries, never edits. Every battery gets a pre-registration entry BEFORE it runs.
-- Raw rollouts and session content never enter any repo. Aggregates, scorer outputs, and distilled scenarios only.
-- Before every autoresearch/evals commit: substring-aware grep of staged text AND the commit-message file against the campaign name-sets (client names, hostnames, ticket IDs). Oblique references only.
-- Scenario post-checks (`checks.sh`) must never assert a behavioral choice a scorer measures. Measurement is scorer-side.
-- Smoke-test ONE rep of any scenario/arm/harness combination before its battery.
-- Scorer output files use rep-range names; existing aggregates are never overwritten without `FORCE=1`.
-- Every scorer verdict requires manual inspection of matches (non-circular: never verify with the scorer's own helper).
-- Brainstorming's frontmatter `description:` must not change (triggering depends on it).
-- Skill edits must not alter files outside the named targets; no whitespace-only churn.
-- PRs are cut per treatment ONLY after its criterion passes; merges require Jesse's per-PR approval. The codex-tools.md PRs declare merge order T3 → T2 → T5.
-- Subagents running batteries poll in-session with long timeouts; no monitors.
-
----
-
-### Task 1: T1 — SDD worker-review prohibition
-
-**Files:**
-- Modify: `skills/subagent-driven-development/implementer-prompt.md` (insert new section before `## Code Organization`)
-- Modify: `skills/subagent-driven-development/SKILL.md` (dispatch bullet + Red Flags row)
-
-**Interfaces:**
-- Consumes: nothing from other tasks.
-- Produces: commit `fix(sdd): implementers never dispatch subagents` — the T1 PR cherry-picks exactly this commit.
-
-- [ ] **Step 1: Insert the implementer-prompt section**
-
-In `skills/subagent-driven-development/implementer-prompt.md`, immediately after the paragraph ending `run the full suite once before committing, not after every edit.` and before ` ## Code Organization`, insert (keeping the template's 4-space body indent):
-
-```
- ## You Do Not Dispatch Subagents
-
- Do all of this task's work yourself. Never spawn a subagent to
- implement part of the task, and above all never spawn a reviewer to
- check your work. Self-review (below) means reading your own diff.
- Review is the controller's job: after you report, it dispatches a
- fresh reviewer against your diff. A reviewer you spawn duplicates
- that review at full cost, and its approval counts for nothing in
- the process. If you catch yourself thinking "an independent review
- would strengthen my report" — that review is already scheduled.
- Report instead.
-```
-
-- [ ] **Step 2: Add the dispatch-contract bullet to SKILL.md**
-
-In `skills/subagent-driven-development/SKILL.md`, section `### 1. Dispatch the implementer`, after the bullet beginning `- A dispatch prompt describes one task, not the session's history.`, add:
-
-```
-- The dispatch carries the no-subagents contract (it is in the
- implementer template): the implementer never dispatches subagents —
- not helpers, and never a reviewer. Review arrives from you, after the
- report. In real sessions, every reviewer a worker spawned duplicated
- the task review the controller dispatched anyway — a full extra
- review seat per task.
-```
-
-- [ ] **Step 3: Add the Red Flags row**
-
-In the same file's Red Flags table (`## Red Flags`), after the row `| "Ledger bookkeeping is overhead" | ... |`, add:
-
-```
-| "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
-```
-
-- [ ] **Step 4: Verify**
-
-Run: `grep -c "You Do Not Dispatch Subagents" skills/subagent-driven-development/implementer-prompt.md` → expect `1`. Run: `grep -c "no-subagents contract\|spawned its own reviewer" skills/subagent-driven-development/SKILL.md` → expect `2`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add skills/subagent-driven-development/implementer-prompt.md skills/subagent-driven-development/SKILL.md
-git commit -m "fix(sdd): implementers never dispatch subagents
-
-Depth-2 worker-spawned reviewers were 9/9 same-task duplicate reviews
-across four corpora in the codex-efficiency eval campaign."
-```
-
----
-
-### Task 2: T3 — codex-tools.md version-honest multi-agent rewrite
-
-**Files:**
-- Modify: `skills/using-superpowers/references/codex-tools.md` (replace the paragraph after the config block)
-
-**Interfaces:**
-- Consumes: nothing.
-- Produces: the rewritten base section Tasks 3 and 4 append after; commit `fix(codex): correct multi-agent guidance against Codex source` (T3 PR).
-
-- [ ] **Step 1: Replace the multi-agent paragraph**
-
-In `skills/using-superpowers/references/codex-tools.md`, replace the entire single paragraph beginning `This enables \`spawn_agent\`, \`wait_agent\`, and \`close_agent\`` (and ending `...carrying the brief, the report file, and the findings.`) with:
-
-```
-This enables the multi-agent tools that skills like
-`dispatching-parallel-agents` and `subagent-driven-development` use.
-Which tools you get depends on the multi-agent version your model
-preset selects (current presets run V2; older ones run V1). Trust your
-actual tool list over any table — including this one — when they
-disagree.
-
-- **Spawning:** give children a clean context with
- `spawn_agent {fork_turns: "none"}`; the default `"all"` copies your
- entire transcript into the child. On Codex 0.145+, role files under
- `~/.codex/agents/` attach to isolated forks via `agent_type`.
- Full-history forks accept `model` and `reasoning_effort` overrides
- (only `agent_type` is refused there) — isolated forks are the SDD
- default for context hygiene, not because overrides require them.
-- **Fix rounds:** resume the implementer with `followup_task` — it
- delivers your message, triggers a turn, and transparently reloads a
- child the harness evicted. Never dispatch a fresh implementer on the
- theory that a spawned agent cannot be messaged again; on V2 it
- always can.
-- **Lifecycle:** V2 has no `close_agent`. Finished children are
- evicted automatically when slots are needed; leaving them unclosed
- costs nothing. Only V1 sessions have `close_agent` — there, close
- reviewers when their review returns, and close each implementer
- after its task's review passes.
-- **Model names:** never copy a model name from a skill, table, or old
- session into `spawn_agent` without checking it against your current
- spawn allowlist — V2 accepts only V2-capable presets and hard-errors
- on the rest.
-```
-
-- [ ] **Step 2: Verify**
-
-Run: `grep -c "close_agent" skills/using-superpowers/references/codex-tools.md` → expect `2` (both inside the Lifecycle bullet). Run: `grep -c "cannot be messaged again" skills/using-superpowers/references/codex-tools.md` → expect `1`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/using-superpowers/references/codex-tools.md
-git commit -m "fix(codex): correct multi-agent guidance against Codex source
-
-Five claims contradicted by the Codex CLI source (V2 has no
-close_agent; followup_task always reaches a child; role files attach
-via agent_type; full-history forks accept model/effort; V2 spawn
-allowlist). Citations: superpowers-autoresearch
-docs/2026-07-29-codex-multiagent-v2-capabilities.md."
-```
-
----
-
-### Task 3: T2 — codex-tools.md event-driven waiting section
-
-**Files:**
-- Modify: `skills/using-superpowers/references/codex-tools.md` (new section after Task 2's block, before `## Environment Detection`)
-
-**Interfaces:**
-- Consumes: Task 2's rewritten base section (append directly after it).
-- Produces: commit `fix(codex): event-driven waiting instead of short polls` (T2 PR; declares dependency on T3's PR).
-
-- [ ] **Step 1: Insert the section**
-
-Immediately before `## Environment Detection`, insert:
-
-```
-## Waiting on children
-
-`wait_agent` is an event subscription, not a poll: a long wait wakes
-the moment a child produces mailbox activity, with the same latency as
-a short one. Short-timeout polling buys nothing and costs a tool call —
-and a context rebill — per poll. In measured sessions, roughly
-two-thirds of all wait calls were short polls that timed out.
-
-- While you still have local work, do not wait at all. A completed
- child's final answer is pushed into your mailbox and arrives with
- your next turn.
-- When you are genuinely idle with children outstanding, issue ONE
- `wait_agent` with a long `timeout_ms` — 900000 (15 minutes) or more —
- and let the event wake you.
-- Completion mail cannot wake an idle controller (it is delivered
- without triggering a turn); covering that idle window is
- `wait_agent`'s only job. If a long wait times out, check
- `list_agents` for stuck children — do not fall back to short polls.
-```
-
-- [ ] **Step 2: Verify**
-
-Run: `grep -c "Waiting on children" skills/using-superpowers/references/codex-tools.md` → expect `1`. Run: `grep -n "900000" skills/using-superpowers/references/codex-tools.md` → expect one hit.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/using-superpowers/references/codex-tools.md
-git commit -m "fix(codex): event-driven waiting instead of short polls
-
-60-78% of wait_agent calls timed out across every measured corpus;
-waits are event subscriptions, so one long wait replaces dozens of
-polls at identical wake latency."
-```
-
----
-
-### Task 4: T5 — codex-tools.md model routing on spawns
-
-**Files:**
-- Modify: `skills/using-superpowers/references/codex-tools.md` (new section after Task 3's, before `## Environment Detection`)
-
-**Interfaces:**
-- Consumes: Tasks 2–3 in place.
-- Produces: commit `fix(codex): explicit model+effort on every spawn, config backstop` (T5 PR; declares dependency on T3's and T2's PRs).
-
-- [ ] **Step 1: Insert the section**
-
-Immediately before `## Environment Detection`, insert:
-
-````
-## Model routing on spawns
-
-Every `spawn_agent` you issue — including when you are yourself a
-spawned child running a fan-out — sets `model` AND `reasoning_effort`
-explicitly, per the Model Selection rules of the skill you are
-executing. Setting `model` alone is a trap: the child's effort
-silently resets to that model's default, not to yours.
-
-Ask your human partner to add a machine-level backstop to
-`~/.codex/config.toml` so any spawn that slips through still routes to
-a deliberate tier instead of silently inheriting the session's most
-expensive model:
-
-```toml
-[agents]
-default_subagent_model = "<a mid-tier model from your spawn allowlist>"
-default_subagent_reasoning_effort = "medium"
-```
-````
-
-- [ ] **Step 2: Verify**
-
-Run: `grep -c "Model routing on spawns" skills/using-superpowers/references/codex-tools.md` → expect `1`. Run: `grep -c "default_subagent_model" skills/using-superpowers/references/codex-tools.md` → expect `1`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/using-superpowers/references/codex-tools.md
-git commit -m "fix(codex): explicit model+effort on every spawn, config backstop
-
-Depth-2 child-issued spawns omitted model 2/2 at CLI 0.146; model
-without reasoning_effort resets effort to the model default."
-```
-
----
-
-### Task 5: T4 — brainstorming three-path router (variant C)
-
-**Files:**
-- Modify: `skills/brainstorming/SKILL.md`
-
-The frontmatter `description:` is untouched. Edits below are complete replacements for the named regions; everything not named stays byte-identical.
-
-- [ ] **Step 1: Replace intro sentence, HARD-GATE, and anti-pattern section**
-
-Replace from the line `Start by understanding the current project context, ...` through the end of the `## Anti-Pattern: "This Is Too Simple To Need A Design"` section (i.e., up to but not including `## Checklist`) with:
-
-```
-Start by classifying how much process the request needs, then work
-through your path: understand the context, refine the idea, present a
-design, and get your human partner's approval.
-
-<HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any
-project, or take any implementation action until you have told your
-human partner what you intend and they have approved it. This applies
-to EVERY task on EVERY path below — the ceremony scales with the task;
-the approval gate never does.
-</HARD-GATE>
-
-## Three Paths
-
-Before your first question, classify the request and say the
-classification out loud — "this looks bounded, so I'll present a short
-design here rather than write a spec" — so your human partner can
-override it:
-
-- **Spike** — a feasibility question ("can we...", "is it possible...",
- "quick and dirty is fine") whose output is an answer, not code you
- keep. Present the question and what you'll try in 2-3 sentences, get
- a nod, then find out as cheaply as correctness allows. No design
- doc, no spec file. Report findings as a recommendation; anything you
- built stays labeled throwaway.
-- **Bounded** — a well-scoped change to an existing, understood flow: a
- new flag, a small endpoint, a one-file fix. Ask the clarifying
- questions that matter, present a short design IN CHAT (a few
- sentences to a few short paragraphs), and get approval. No spec
- file, no implementation plan document.
-- **Architectural** — new projects, new subsystems, changes that
- restructure how components fit together or alter interfaces others
- depend on. Follow the full process: questions, approaches, sectioned
- design, written spec, then the writing-plans skill.
-
-When in doubt between two paths, take the heavier one. The ratchet is
-one-way: hidden complexity discovered mid-task upgrades the path —
-stop, say so, and step up. Nothing downgrades mid-task.
-
-## Anti-Pattern: "Too Simple To Need Approval"
-
-Every path ends with your human partner approving your intent before
-implementation. A todo list, a single-function utility, a config
-change — the design may be two sentences in chat, but you MUST present
-it and get approval. "Simple" tasks are where unexamined assumptions
-cause the most wasted work. What scales with simplicity is the
-artifact, never the approval.
-
-## Red Flags
-
-| Thought | Reality |
-|---------|---------|
-| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
-| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
-| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
-| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
-| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
-```
-
-- [ ] **Step 2: Replace the Checklist section**
-
-Replace the `## Checklist` section body (from `You MUST create a task...` through item 9) with:
-
-```
-Classify first, announce the path, then create a task for each item on
-your path and complete them in order.
-
-**Spike:**
-1. **Explore project context** — enough to frame the probe
-2. **Present question + probe plan** — 2-3 sentences
-3. **Get approval** — a nod is enough
-4. **Investigate** — as cheaply as correctness allows
-5. **Report findings** — a recommendation; label anything built as throwaway
-
-**Bounded:**
-1. **Explore project context** — check files, docs, recent commits
-2. **Ask clarifying questions** — one at a time, the ones that matter
-3. **Present short design in chat** — approach, files touched, testing
-4. **Get approval** — explicit, before any implementation
-5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
-
-**Architectural:**
-1. **Explore project context** — check files, docs, recent commits
-2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
-3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-4. **Propose 2-3 approaches** — with trade-offs and your recommendation
-5. **Present design** — in sections scaled to their complexity, get user approval after each section
-6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
-8. **User reviews written spec** — ask user to review the spec file before proceeding
-9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
-```
-
-- [ ] **Step 3: Replace the Process Flow graph**
-
-Replace the entire ```dot ... ``` block under `## Process Flow` with:
-
-```
-digraph brainstorming {
- "Classify: spike / bounded / architectural" [shape=diamond];
- "Present question + probe (2-3 sentences)" [shape=box];
- "Ask clarifying questions (bounded)" [shape=box];
- "Present short design in chat" [shape=box];
- "Human approves?" [shape=diamond];
- "Investigate; report recommendation" [shape=doublecircle];
- "Implement via normal workflow (no plan doc)" [shape=doublecircle];
- "Explore project context" [shape=box];
- "Ask clarifying questions" [shape=box];
- "Propose 2-3 approaches" [shape=box];
- "Present design sections" [shape=box];
- "User approves design?" [shape=diamond];
- "Write design doc" [shape=box];
- "Spec self-review\n(fix inline)" [shape=box];
- "User reviews spec?" [shape=diamond];
- "Invoke writing-plans skill" [shape=doublecircle];
- "Hidden complexity? Upgrade path" [shape=box];
-
- "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
- "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
- "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
- "Present question + probe (2-3 sentences)" -> "Human approves?";
- "Ask clarifying questions (bounded)" -> "Present short design in chat";
- "Present short design in chat" -> "Human approves?";
- "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
- "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
- "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
- "Explore project context" -> "Ask clarifying questions";
- "Ask clarifying questions" -> "Propose 2-3 approaches";
- "Propose 2-3 approaches" -> "Present design sections";
- "Present design sections" -> "User approves design?";
- "User approves design?" -> "Present design sections" [label="no, revise"];
- "User approves design?" -> "Write design doc" [label="yes"];
- "Write design doc" -> "Spec self-review\n(fix inline)";
- "Spec self-review\n(fix inline)" -> "User reviews spec?";
- "User reviews spec?" -> "Write design doc" [label="changes requested"];
- "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
-}
-```
-
-- [ ] **Step 4: Replace the terminal-state paragraph**
-
-Replace the paragraph `**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.` with:
-
-```
-**Terminal states are path-bound.** Architectural: the ONLY skill you
-invoke after brainstorming is writing-plans — never frontend-design,
-mcp-builder, or any other implementation skill. Bounded: after
-approval, implementation proceeds directly through the normal
-development workflow; no plan document. Spike: the terminal state is a
-reported recommendation.
-```
-
-- [ ] **Step 5: Scope the long-form sections to their paths**
-
-(a) Immediately under `## The Process`, insert as the first line:
-
-```
-The subsections below serve the bounded and architectural paths (a
-spike stops at "present the probe, get a nod"). Sections from
-**Exploring approaches** onward are architectural-path depth — for
-bounded work, context plus a few questions plus a short in-chat design
-is the whole process.
-```
-
-(b) Rename the heading `## After the Design` to `## After the Design (architectural path)`.
-
-- [ ] **Step 6: Verify**
-
-Run: `grep -c "Three Paths" skills/brainstorming/SKILL.md` → `1`; `grep -c "regardless of perceived simplicity" skills/brainstorming/SKILL.md` → `0`; `grep -c "^description:" skills/brainstorming/SKILL.md` unchanged vs `git show origin/dev:skills/brainstorming/SKILL.md | grep -c "^description:"`; confirm `git diff origin/dev -- skills/brainstorming/SKILL.md` shows no frontmatter hunk. If `dot` is installed: `awk '/^```dot$/,/^```$/' skills/brainstorming/SKILL.md | sed '1d;$d' | dot -Tcanon >/dev/null` → exit 0.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add skills/brainstorming/SKILL.md
-git commit -m "feat(brainstorming): three-path router — ceremony scales, approval never does
-
-Spike / bounded / architectural classification said out loud, one-way
-upgrade ratchet, approval gate on every path. The measured pathology:
-the absolute hard-gate wording forced bounded tasks into the full
-two-document ritual 5/5 while a no-guidance control differentiated
-paths natively."
-```
-
----
-
-### Task 6: Fix arm + hypothesis log
-
-**Files:**
-- Create: `superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md`
-- Create (filesystem, not committed): `/tmp/sp-arm-fix` worktree
-
-**Interfaces:**
-- Consumes: Tasks 1–5 committed on `codex-efficiency-fixes`.
-- Produces: the arm every battery runs against; the log every later task appends to.
-
-- [ ] **Step 1: Create the arm**
-
-```bash
-git -C /Users/jesse/git/superpowers/superpowers worktree add --detach /tmp/sp-arm-fix codex-efficiency-fixes
-git -C /tmp/sp-arm-fix log --oneline -1 # must show Task 5's commit
-```
-
-(Before any LATER battery, refresh with `git -C /tmp/sp-arm-fix checkout --detach codex-efficiency-fixes`.)
-
-- [ ] **Step 2: Create the log**
-
-Write `superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md` with: title `# Codex efficiency fix cycle — hypothesis log`; a header block stating it is append-only, naming the spec path (`superpowers/docs/superpowers/specs/2026-07-30-codex-efficiency-fixes-design.md`), the branch, the arm (`/tmp/sp-arm-fix`), and the carried-over standing rules (pre-registration before batteries, manual match inspection, no raw rollouts, discrimination rule); and a `## Pre-registered criteria (from the approved spec)` section reproducing verbatim the five criterion lines from the spec's treatment sections (T1: 0 worker-issued depth-2 spawns AND review coverage preserved; T2: timeout rate < 25%, no completion loss; T3: source-cited corrections, no scorer regressions; T4: the three-layer criteria; T5: explicit model+effort at every depth, with the pre-registered inconclusive-by-zero caveat).
-
-- [ ] **Step 3: Privacy sweep and commit (autoresearch)**
-
-```bash
-cd /Users/jesse/git/superpowers/superpowers-autoresearch
-git add logs/2026-07-30-codex-efficiency-fixes.md
-git diff --cached | grep -iE 'paradise|magic-kingdom|flower|pallas|web1|teststrip|PRI-[0-9]' && echo LEAK || echo clean # must print clean
-git commit -m "docs: open the codex-efficiency fix-cycle hypothesis log"
-```
-
----
-
-### Task 7: Micro — variant C + adversarial briefs
-
-**Files:**
-- Modify: `superpowers-autoresearch/campaigns/codex-efficiency/ceremony-path-micro.py`
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/out/` micro outputs (NOT committed; aggregates go in the log)
-
-**Interfaces:**
-- Consumes: Task 5's shipped router text (the variant must quote it), Task 6's log.
-- Produces: micro verdict for T4 layer 1.
-
-- [ ] **Step 1: Extend the script**
-
-Read the current script first. Then: (a) add a variant `C-approval` whose text is the Three Paths block from Task 5 Step 1 (the three bullets plus the doubt/ratchet paragraph, verbatim); (b) neutralize the shared SYSTEM answer definitions so classification measures the ARTIFACT level, not the approval step — replace the three definition bullets with: SPIKE = "dive straight into a minimal throwaway investigation — no design document"; BOUNDED = "make the change after at most brief clarification and a short in-chat design — no design document, no implementation plan"; FULL = "run the complete design process — written design document and implementation plan before touching code"; (c) add two briefs after the existing three:
-
-`ambig-interface`: "Add a --json flag to our export CLI command so output can be piped to jq. The current text output of export is parsed line-by-line by three downstream scripts in tools/ that other teams run in their pipelines."
-
-`ambig-crosscut`: "Fix the timezone bug in report_generator.py where daily rollups are off by one day for users west of UTC. Rollup boundaries are also computed independently in the billing exporter and the retention job, which must stay consistent with reports."
-
-Matrix: 3 variants (Z-null, A-current, C-approval) × 5 briefs × 5 reps = 75 calls, model `claude-opus-4-8`, same one-word regex scoring and answer-file verification as the campaign run.
-
-- [ ] **Step 2: Pre-register in the log**
-
-Append an entry BEFORE running: the taxonomy change (new SYSTEM definitions — within-run comparisons only; not comparable cell-by-cell to the campaign's micro), the matrix, and predictions: C-approval — spike→SPIKE ≥4/5, bounded→BOUNDED ≥4/5, arch→FULL 5/5, both ambig→FULL ≥4/5; A-current — bounded→FULL persists; Z-null on ambig briefs recorded as an observation (does unguided judgment escalate?). Commit the entry.
-
-- [ ] **Step 3: Run and verify**
-
-Run the sweep. Independently verify every answer file is exactly one word via a separate command (e.g. `awk 'NF!=1' out/micro-c/*.txt`), not the scorer's own parser.
-
-- [ ] **Step 4: Verdict entry + commit**
-
-Append the results table and verdict to the log (criteria from Step 2). Privacy-sweep, commit script + log entry. If C-approval fails a cell, STOP: report to the controller — the router text needs revision before any battery spends on it.
-
----
-
-### Task 8: Shared SDD battery (T1, T2, T5)
-
-**Files:**
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/out/` fix-arm aggregates (rep-range filenames)
-- Modify: `superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md` (pre-registration + verdicts)
-- Possibly modify: `superpowers-autoresearch/campaigns/codex-efficiency/run-quorum.sh` (only if the `fix` arm name needs wiring — read it first; the campaign convention maps ARM → `/tmp/sp-arm-$ARM`)
-
-**Interfaces:**
-- Consumes: Tasks 1–6.
-- Produces: T1/T2/T5 verdicts; the runs Task 11's regression comparison may reuse.
-
-- [ ] **Step 1: Pre-register** — append the battery entry (arm=fix @ the arm's SHA, scenario `cx-sdd-small`, 8 reps across lanes A and B, JOBS=2, scorers e6/e7/e1, criteria verbatim from the log's criteria section, budget estimate ~$40). Commit.
-
-- [ ] **Step 2: Smoke test** — 1 rep: `EVALS_ROOT=<lane A> JOBS=1 bash run-quorum.sh fix cx-sdd-small 1`. Inspect the verdict and one rollout by hand: session ran, spawns present, no setup failure. Any infra anomaly stops the battery.
-
-- [ ] **Step 3: Run the battery** — 7 more reps split across lanes (`REP_START` per the runner's convention, e.g. reps 2–4 lane A, 5–8 lane B). Poll in-session with long timeouts; no monitors.
-
-- [ ] **Step 4: Score** — run `score_e6.py`, `score_e7.py`, `score_e1.py` over the fix-arm runs with rep-range output names. Manually inspect: every depth-2 spawn (should be none worker-issued), every wait call classification for 2+ runs, every spawn tuple for 2+ runs — against raw rollouts, not scorer helpers.
-
-- [ ] **Step 5: Verdict entries** — per treatment, against pre-registered criteria; record the T5 inconclusive-by-zero branch honestly if depth-2 spawns vanished. Ledger row with measured cost. Privacy-sweep; commit aggregates + log.
-
----
-
-### Task 9: Codex ceremony battery (T4 layer 2)
-
-**Files:**
-- Modify: log (pre-registration + verdict); `out/` aggregates.
-
-**Interfaces:**
-- Consumes: Tasks 5, 6; Task 7 must have PASSED.
-- Produces: T4 layer-2 verdict.
-
-- [ ] **Step 1: Pre-register** — arm=fix, `cx-ceremony-{spike,bounded,arch}`, 3 reps each, scorer `score_e4.py`; criteria: bounded — approval turn present, 0 committed spec/plan docs, 0 writing-plans ritual; arch — two-doc flow intact 3/3; spike — no docs, minimal ceremony; plus gauntlet task completion preserved per cell. Budget ~$40. Commit.
-
-- [ ] **Step 2: Smoke test** — 1 bounded rep; hand-inspect the rollout for scenario health (not for the measured behavior).
-
-- [ ] **Step 3: Run remaining 8 runs across lanes.**
-
-- [ ] **Step 4: Score + manually verify** — `score_e4.py` census; hand-verify one rep per class against raw timestamps (the campaign's hand-recount method: doc patches vs first non-doc patch).
-
-- [ ] **Step 5: Verdict entry** — versus criteria; ledger row; sweep; commit.
-
----
-
-### Task 10: ATIF ceremony census scorer (for the global battery)
-
-**Files:**
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/score_t4_regression.py`
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/test_score_t4_regression.py`
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/fixtures/atif-ceremony/` (synthetic `trajectory.json` fixtures)
-
-**Interfaces:**
-- Consumes: quorum's per-run `trajectory.json` (ATIF v1.7; tool calls with file paths and step timestamps — see `superpowers/evals/src/atif/types.ts` for the shape).
-- Produces: per-run census dict: `{spec_docs_written: int, plan_docs_written: int, doc_writes_before_first_code: int, first_code_file: str|null, user_turns_before_first_code: int, writing_plans_invoked: bool}`; consumed by Task 11.
-
-- [ ] **Step 1: Write failing tests** — build three synthetic trajectory fixtures: (a) full-ceremony (writes `docs/superpowers/specs/x-design.md` then `docs/superpowers/plans/x.md` then `src/app.py`), (b) bounded-lean (writes `src/app.py` first, no docs), (c) doc-only-readme (writes `README.md` then code — README is NOT a ceremony doc). Assert the census fields for each, including `writing_plans_invoked` detection via a tool call reading a path containing `skills/writing-plans` (fixture (a) true, others false). Run `python3 -m pytest test_score_t4_regression.py` → all FAIL (module missing).
-
-- [ ] **Step 2: Implement** — ceremony docs are paths matching `docs/superpowers/(specs|plans)/`; code files are any other write outside `docs/` and not `*.md` at repo root; count user turns from ATIF steps preceding the first code write. Run tests → PASS.
-
-- [ ] **Step 3: Commit** (autoresearch, after sweep): `feat: ATIF ceremony census scorer for cross-harness T4 regression`.
-
----
-
-### Task 11: Global regression battery (T4 layer 3) — Claude Code + Gemini
-
-**Files:**
-- Create: `superpowers-autoresearch/campaigns/codex-efficiency/scenarios/cc-ceremony-{spike,bounded,arch}/` (copies of the `cx-` scenarios with the `# coding-agents:` line set to `claude,gemini`; strip any codex-only setup)
-- Modify: log (pre-registration + verdict); `out/` aggregates.
-
-**Interfaces:**
-- Consumes: Task 10's scorer; Tasks 5–6; lane containers with Claude/Gemini auth (Claude: `ANTHROPIC_API_KEY`; Gemini: `GEMINI_API_KEY` — see `superpowers/evals/README.md` and `coding-agents/*-context/HOWTO.md`).
-- Produces: T4 layer-3 verdict (the cross-harness regression evidence the T4 PR requires).
-
-- [ ] **Step 1: Port the scenarios** — copy each `cx-ceremony-*`, retarget the agents line, review `setup.sh`/`checks.sh` for codex-isms (post-checks must stay behavior-neutral). `bun run quorum check` (in the lane's evals checkout) must pass.
-
-- [ ] **Step 2: Pre-register** — matrix: {dev, fix} arms × {claude, gemini} × 3 scenarios × 3 reps = 36 runs (~$40–80; Claude/Gemini runs are the cheap side). Criteria: (a) per-cell gauntlet pass rate fix ≥ dev; (b) fix-arm arch cells keep `spec_docs_written ≥ 1` and `writing_plans_invoked` 3/3; (c) fix-arm bounded cells show `spec_docs_written = 0` and `writing_plans_invoked = false`; (d) dev-arm bounded behavior recorded as the baseline (expected: two-doc ritual). Commit.
-
-- [ ] **Step 3: Smoke test** — 1 rep per harness (2 runs) before the matrix.
-
-- [ ] **Step 4: Run the matrix across both lanes; score with `score_t4_regression.py`; manually inspect one trajectory per harness per arm.**
-
-- [ ] **Step 5: Verdict entry** — versus criteria; ledger row; sweep; commit scenarios + aggregates + log.
-
----
-
-### Task 12: Triggering acceptance check (all three harnesses)
-
-**Files:**
-- Modify: log (pre-registration + verdict).
-
-**Interfaces:**
-- Consumes: `/tmp/sp-arm-fix`; the containerized triggering approach (host runs are confounded — `superpowers-autoresearch` docs and `scripts/evals-container`).
-- Produces: the "brainstorming still auto-triggers" evidence line every T4 PR cites.
-
-- [ ] **Step 1: Pre-register** — prompt: exactly `Let's make a react todo list`; fix arm; 3 reps × {codex, claude, gemini}; criterion: brainstorming loads before any implementation action AND the session heads down the architectural path (new project), 3/3 per harness. Commit.
-
-- [ ] **Step 2: Run** — containerized, per the campaign's triggering method; verify skill load from transcripts/rollouts by hand.
-
-- [ ] **Step 3: Verdict entry; sweep; commit.**
-
----
-
-### Task 13: Cut the treatment PRs
-
-**Files:**
-- Create: five branches `fix/t1-sdd-no-worker-reviewers`, `fix/t3-codex-tools-corrections`, `fix/t2-codex-event-waits`, `fix/t5-codex-spawn-routing`, `fix/t4-brainstorming-three-paths`, each cherry-picked from `codex-efficiency-fixes` onto `origin/dev`
-- Create: PR body files under the SDD workspace (drafted from `.github/PULL_REQUEST_TEMPLATE.md`)
-
-**Interfaces:**
-- Consumes: verdicts from Tasks 7–12; only treatments whose criteria PASSED get a PR.
-- Produces: pushed branches + draft PR bodies. **STOP before opening PRs: present the PR set (diffs + bodies + verdict table) to Jesse. PRs open only on his go; merges are his.**
-
-- [ ] **Step 1:** For each passing treatment: branch off `origin/dev`, cherry-pick its commit(s), verify `git diff` matches the treatment's slice of the fix branch.
-- [ ] **Step 2:** Draft each PR body: full template, identification block (model, harness, plugins), problem statement from the campaign evidence, eval results from the log's verdict entries, related-PR section citing #2036/#2035 as prior art NOT adopted (and why), merge-order note on the codex-tools trio (T3 → T2 → T5).
-- [ ] **Step 3:** Push branches. Present everything to Jesse and STOP.
-
----
-
-### Task 14: Campaign closeout
-
-**Files:**
-- Modify: `superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md` (closing summary + final ledger)
-- Create: `superpowers-autoresearch/reports/2026-07-codex-efficiency-fix-cycle.md` (verdict table: five treatments × criterion × result × PR link; phase-2 queue restated with what each item still needs)
-
-**Interfaces:**
-- Consumes: everything above.
-- Produces: the record phase 2 starts from.
-
-- [ ] **Step 1:** Write the report; totals in the ledger; note any criterion that failed and what was NOT shipped as a result.
-- [ ] **Step 2:** Privacy sweep; commit; push autoresearch main (authorized).
-
----
-
-## Amendment 1 (2026-07-30, Jesse-approved after the first shared battery)
-
-The first shared SDD battery (Task 8, n=6) returned FAIL on T1/T2/T5. Root
-causes and approved responses: (a) the no-subagents contract reached only
-implementer-prompt.md — the final reviewer spawned two sub-reviewers
-(T1's miss, and both of T5's); extend the contract to every dispatched
-role. (b) Docs-only wait guidance in codex-tools.md produced no behavior
-change (65.1% vs 67.1% baseline timeouts); move the wait discipline into
-the SDD controller text. Then re-run the battery.
-
-### Task 15: T1-ext — no-subagents contract in all reviewer templates
-
-**Files:**
-- Modify: `skills/subagent-driven-development/task-reviewer-prompt.md`
-- Modify: `skills/subagent-driven-development/re-review-prompt.md`
-- Modify: `skills/requesting-code-review/code-reviewer.md`
-
-**Interfaces:**
-- Consumes: Task 1's implementer-prompt contract (same intent, reviewer flavor).
-- Produces: commit `fix(sdd): reviewers never dispatch subagents either` — joins the T1 PR with Task 1's commit.
-
-- [ ] **Step 1: Insert the reviewer-flavor section into both SDD reviewer templates**
-
-In `skills/subagent-driven-development/task-reviewer-prompt.md`, immediately after the paragraph ending `Do not mutate the working
- tree, the index, HEAD, or branch state in any way.` and before ` ## Do Not Trust the Report`, insert (4-space body indent):
-
-```
- ## You Do Not Dispatch Subagents
-
- Do all of this review yourself. Never spawn a subagent to review part
- of the diff, and never spawn another reviewer for a second opinion.
- This process already provides every review seat the work gets; a
- reviewer you spawn duplicates one of them at full cost, and its
- verdict counts for nothing. If the diff feels too large for one
- pass, review it in passes yourself and say so in your report.
-```
-
-In `skills/subagent-driven-development/re-review-prompt.md`, insert the SAME block immediately after the identical read-only paragraph and before ` ## Scope`.
-
-- [ ] **Step 2: Insert into code-reviewer.md**
-
-In `skills/requesting-code-review/code-reviewer.md`, immediately after the `## Read-Only Review` section's paragraph and before ` ## What to Check`, insert the SAME block (matching that template's body indent).
-
-- [ ] **Step 3: Verify**
-
-`grep -c "You Do Not Dispatch Subagents" skills/subagent-driven-development/task-reviewer-prompt.md skills/subagent-driven-development/re-review-prompt.md skills/requesting-code-review/code-reviewer.md` → each file reports `1`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/subagent-driven-development/task-reviewer-prompt.md skills/subagent-driven-development/re-review-prompt.md skills/requesting-code-review/code-reviewer.md
-git commit -m "fix(sdd): reviewers never dispatch subagents either
-
-The first fix-cycle battery moved the depth-2 leak from implementers
-(9/9 baseline -> 0/6) to a final reviewer that spawned two
-sub-reviewers; the contract now reaches every dispatched role."
-```
-
-### Task 16: T2-strong — wait discipline in the SDD controller text
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md`
-
-**Interfaces:**
-- Consumes: nothing new.
-- Produces: commit `fix(sdd): controllers wait long or not at all` — joins the T2 PR.
-
-- [ ] **Step 1: Insert the wait-discipline paragraph**
-
-In `skills/subagent-driven-development/SKILL.md`, in `## The Task Loop`, immediately after the paragraph ending `Hand artifacts over as files.` insert:
-
-```
-**Waiting on dispatched subagents:** never poll a wait interface with
-short timeouts. While you have local work — ledger updates, packaging
-the next review, reading reports — keep working; child results arrive
-on their own. Wait only when you are genuinely idle, and then issue one
-long wait (fifteen minutes or more, where your platform allows it)
-instead of many short ones: a long wait wakes just as fast and costs
-one call instead of dozens.
-```
-
-- [ ] **Step 2: Verify**
-
-`grep -c "Waiting on dispatched subagents" skills/subagent-driven-development/SKILL.md` → `1`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md
-git commit -m "fix(sdd): controllers wait long or not at all
-
-Docs-only wait guidance in the platform reference changed nothing
-(65.1% vs 67.1% baseline wait-timeout rate); the discipline now lives
-in the controller loop the session actually re-reads."
-```
-
-### Task 8b: re-run the shared SDD battery
-
-Repeat Task 8 exactly (same scenario, criteria, scorers, n=8, both lanes)
-against a refreshed `/tmp/sp-arm-fix` containing Tasks 15-16. New
-pre-registration entry required (new arm SHA). Blocked until Docker is
-restored. The Task 8 n=6 battery remains in the log as the round-1
-result; 8b's entries are additions, not corrections.
-
----
-
-## Amendment 2 (2026-07-30, after battery round 2 and the ceremony battery)
-
-Round-2 findings driving this amendment: (a) T2's long-wait fix eliminated
-wait timeouts (65.1%→0.0%) but produced 20-38 min silent transcripts that
-starve graders/humans and let one child in 51 vanish unnoticed — Jesse
-chose bounded waits + reconcile; (b) T4's bounded path killed the doc
-ritual (0 docs vs 2/rep dev baseline) but 2/3 bounded reps implemented
-BEFORE any approval — the router's approval invariant needs teeth (this
-enforces the variant-C invariant Jesse selected, so it proceeds without a
-new design decision).
-
-### Task 17: T2 round 3 — bounded waits + reconcile
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md` (replace Task 16's paragraph)
-- Modify: `skills/using-superpowers/references/codex-tools.md` (revise two bullets of `## Waiting on children`)
-
-- [ ] **Step 1: Replace the SKILL.md wait paragraph**
-
-Replace the entire paragraph beginning `**Waiting on dispatched subagents:**` (Task 16's insertion) with:
-
-```
-**Waiting on dispatched subagents:** never poll a wait interface with
-short timeouts, and never sit in one silent, open-ended wait either.
-While you have local work — ledger updates, packaging the next review,
-reading reports — keep working; child results arrive on their own.
-When you are genuinely idle, wait in bounded stretches (five to ten
-minutes, where your platform allows), and between stretches post one
-line of status and reconcile your live children: list them, and chase
-any that finished without reporting. A bounded stretch keeps nearly
-all of a long wait's efficiency while guaranteeing a stuck or lost
-child is noticed within minutes, not at the end of the session.
-```
-
-- [ ] **Step 2: Revise codex-tools.md's waiting bullets**
-
-In `## Waiting on children`, replace the second bullet (`- When you are genuinely idle with children outstanding, issue ONE ... let the event wake you.`) with:
-
-```
-- When you are genuinely idle with children outstanding, wait in
- bounded stretches: `wait_agent` with `timeout_ms` 300000-600000
- (5-10 minutes). After each stretch — wake or timeout — post one
- status line, run `list_agents`, and chase any child that finished
- without reporting. Never stack polls shorter than five minutes; the
- event subscription wakes a bounded stretch just as fast as a short
- one.
-```
-
-and replace the third bullet (`- Completion mail cannot wake an idle controller ... do not fall back to short polls.`) with:
-
-```
-- Completion mail cannot wake an idle controller (it is delivered
- without triggering a turn); covering that idle window is
- `wait_agent`'s only job. A stretch that times out with no activity
- is your cue to reconcile, not to shorten the next stretch.
-```
-
-- [ ] **Step 3: Verify** — `grep -c "bounded stretches" skills/subagent-driven-development/SKILL.md skills/using-superpowers/references/codex-tools.md` → 1 and 1; `grep -c "900000" skills/using-superpowers/references/codex-tools.md` → 0.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md skills/using-superpowers/references/codex-tools.md
-git commit -m "fix(sdd,codex): bounded wait stretches with reconciliation
-
-Round 2 proved the long-wait mechanism (65.1%->0.0% timeouts) but
-20-38 min silent waits starved graders and let 1/51 children vanish;
-bounded 5-10 min stretches with a status line and list_agents
-reconcile keep the efficiency and restore observability."
-```
-
-### Task 18: T4 round 2 — approval-gate teeth on the bounded path
-
-**Files:**
-- Modify: `skills/brainstorming/SKILL.md`
-
-- [ ] **Step 1: Strengthen the bounded bullet in `## Three Paths`**
-
-Replace the sentence `Ask the clarifying
- questions that matter, present a short design IN CHAT (a few
- sentences to a few short paragraphs), and get approval. No spec
- file, no implementation plan document.` with:
-
-```
-Ask the clarifying
- questions that matter, present a short design IN CHAT (a few
- sentences to a few short paragraphs), and STOP. Implementation
- starts only after your human partner says yes to that design — a
- bounded task's approval is as hard a gate as an architectural
- one. No spec file, no implementation plan document.
-```
-
-- [ ] **Step 2: Strengthen Bounded checklist item 4**
-
-Replace `4. **Get approval** — explicit, before any implementation` with:
-
-```
-4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
-```
-
-- [ ] **Step 3: Add a Red Flags row**
-
-After the row `| "I'll call it bounded and skip the spec" | ... |` add:
-
-```
-| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
-```
-
-- [ ] **Step 4: Verify** — `grep -c "as hard a gate" skills/brainstorming/SKILL.md` → 1; `grep -c "start while they read it" skills/brainstorming/SKILL.md` → 1; frontmatter untouched (`git diff HEAD -- skills/brainstorming/SKILL.md` shows no frontmatter hunk after the edit vs prior commit).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add skills/brainstorming/SKILL.md
-git commit -m "fix(brainstorming): bounded-path approval is a hard stop
-
-Live ceremony battery: bounded reps produced zero doc ritual (the
-measured win) but 2/3 implemented before any approval turn; the
-bounded path now states the stop explicitly."
-```
-
-### Task 8c: shared SDD battery round 3
-
-Repeat Task 8b (new pre-registration, refreshed arm, n=8, same criteria)
-after Tasks 17-18. T2's clause under test: no completion loss AND
-timeout rate < 25%, now with bounded stretches. T1/T5 re-verified as
-regression guards on the same runs.
-
-### Task 9b: ceremony battery round 2 (bounded focus)
-
-After Tasks 17-18 and arm refresh: bounded 3 reps + arch 3 reps + spike
-1 smoke rep (spike text untouched; the shared Red Flags row is the only
-common edit). Criteria: bounded — 0 ceremony docs AND strict
-pre-implementation approval 3/3; arch — two-doc flow 3/3 with
-completion (pre-register a quorum_max_time bump for the arch scenario,
-disclosed as a scenario-budget accommodation mirroring the round-2
-silent-wait finding, not a treatment change); spike — smoke healthy.
-
----
-
-## Amendment 3 (2026-07-30, Jesse: prefer non-blocking subscriptions)
-
-### Task 19: wait guidance — non-blocking delivery preferred
-
-**Files:**
-- Modify: `skills/subagent-driven-development/SKILL.md` (one sentence added inside the wait paragraph)
-
-- [ ] **Step 1: Insert the preference sentence**
-
-In the `**Waiting on dispatched subagents:**` paragraph, immediately after the sentence ending `child results arrive
-on their own.` insert:
-
-```
-Prefer non-blocking delivery wherever your platform offers it —
-completion notifications, results pushed into your next turn — and
-treat blocking waits as the fallback for platforms (or idle moments)
-that cannot wake you otherwise.
-```
-
-(The following sentence `When you are genuinely idle, wait in bounded
-stretches...` continues the paragraph unchanged.)
-
-- [ ] **Step 2: Verify** — `grep -c "non-blocking delivery" skills/subagent-driven-development/SKILL.md` → 1.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add skills/subagent-driven-development/SKILL.md
-git commit -m "fix(sdd): prefer non-blocking child-result delivery over any wait
-
-Blocking waits are the fallback for platforms that cannot wake an
-idle controller, not the default; harnesses with completion
-notifications never need to block at all."
-```
-
-Grading note (pre-registered here): no codex behavioral delta is
-expected — codex V2 cannot wake an idle controller, so the preference
-ladder collapses to the already-graded bounded-stretch text there; the
-sentence is additive for notification-capable harnesses. Round 3
-grades 6faceb2; the T2 PR discloses this post-battery clarification
-explicitly.
-
----
-
-## Amendment 4 (2026-07-31, after the triggering check)
-
-Task 12 findings: gemini routes a new project architectural 3/3; claude
-triggers brainstorming 3/3 but self-classifies the new project "bounded"
-3/3 through the bounded bullet's "existing, understood flow" wording
-("understood" read as familiarity with the app genre, not presence of
-code in the repo); codex leg blocked on exhausted subscription credits.
-Jesse's rulings: tighten the bounded wording and re-run; he will
-provision an OPENAI_API_KEY so the codex leg can run before the T4 PR.
-
-### Task 20: router tightening — bounded measures the repo
-
-**Files:**
-- Modify: `skills/brainstorming/SKILL.md`
-
-- [ ] **Step 1: Tighten the bounded bullet's definition**
-
-In `## Three Paths`, replace the bounded bullet's opening `- **Bounded** — a well-scoped change to an existing, understood flow: a
- new flag, a small endpoint, a one-file fix.` with:
-
-```
-- **Bounded** — a well-scoped change to code that already exists in
- this repo: a new flag, a small endpoint, a one-file fix.
- Understanding the kind of app is not enough — bounded means the flow
- you are changing is already here to read. If there is no existing
- flow to change, the task is not bounded.
-```
-
-(The rest of the bullet — `Ask the clarifying questions that matter...` — continues unchanged.)
-
-- [ ] **Step 2: Add the familiarity Red Flags row**
-
-After the row `| "It's bounded and the design is obvious — I'll start while they read it" | ... |` add:
-
-```
-| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
-```
-
-- [ ] **Step 3: Verify** — `grep -c "already here to read" skills/brainstorming/SKILL.md` → 1; `grep -c "measures the repo" skills/brainstorming/SKILL.md` → 1; frontmatter untouched.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/brainstorming/SKILL.md
-git commit -m "fix(brainstorming): bounded means existing code in this repo, not a familiar app genre
-
-Triggering battery: Claude Code classified a brand-new project bounded
-3/3 by reading 'existing, understood flow' as genre familiarity — once
-while explicitly noting the repo was empty. Gemini routed the same
-prompt architectural 3/3."
-```
-
-### Task 12b: triggering re-run (claude + gemini) and codex leg
-
-After Task 20 and arm refresh: claude 3 reps + gemini 1 smoke rep on
-`triggering-react-todo`; criteria: claude — brainstorming loads before
-implementation AND architectural classification 3/3; gemini smoke stays
-architectural. New pre-registration; same detection and hand-verification
-method as Task 12. The codex leg (3 reps, same criteria) runs once
-Jesse's OPENAI_API_KEY lands: add a `codex_api` credential entry to the
-evals `credentials.yaml` (api_key_env: OPENAI_API_KEY, harnesses:
-[codex]) if the codex adapter supports API-key auth — verify the
-adapter's auth modes first; if it is subscription-only, report BLOCKED
-with specifics instead of forcing it.
diff --git a/docs/superpowers/plans/2026-08-06-hermes-version-bump-wiring.md b/docs/superpowers/plans/2026-08-06-hermes-version-bump-wiring.md
deleted file mode 100644
index 8fccfbf..0000000
--- a/docs/superpowers/plans/2026-08-06-hermes-version-bump-wiring.md
+++ /dev/null
@@ -1,304 +0,0 @@
-# Hermes Version-Bump Wiring Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Keep the Hermes YAML manifest version synchronized with every other declared release manifest.
-
-**Spec:** `docs/superpowers/specs/2026-08-05-hermes-version-bump-wiring-design.md`
-
-**Architecture:** Extend the existing release script with a small extension-based dispatcher: JSON continues through `jq`, while `.yaml` uses Mike Farah `yq` v4. Before the mutating bump loop, read every present manifest through that dispatcher so deterministic format or field failures occur before the first write.
-
-**Tech Stack:** Bash 3.2-compatible shell, `jq`, Mike Farah `yq` v4, existing shell-lint tooling.
-
-## Global Constraints
-
-- Support only `.json` and `.yaml`; `.yml` and other extensions remain unsupported.
-- YAML fields are present top-level strings; nested YAML fields are out of scope.
-- Pass the YAML field and new value through environment data, never interpolate either into a `yq` expression.
-- Keep `yq` confined to maintainer release tooling; do not add a plugin runtime dependency.
-- Preserve the existing missing-file behavior: `--check` reports missing files and a bump skips them.
-- Preflight only the mutating bump path; do not add rollback or transactional writes.
-- Do not change audit status behavior, version validation, or the existing JSON field-expression implementation.
-
----
-
-## File Map
-
-- Create: `tests/version-bump/test-bump-version.sh`
- - Exercise the real script in temporary JSON/YAML fixtures and check the real registry.
-- Modify: `scripts/bump-version.sh`
- - Add YAML read/write helpers, format dispatch, and bump-only read preflight.
-- Modify: `.version-bump.json`
- - Register `.hermes-plugin/plugin.yaml` at top-level field `version`.
-
-### Task 1: Wire Hermes Into The Existing Version-Bump Script
-
-**Files:**
-- Create: `tests/version-bump/test-bump-version.sh`
-- Modify: `scripts/bump-version.sh`
-- Modify: `.version-bump.json`
-
-**Interfaces:**
-- Consumes: `.version-bump.json` records shaped as `{ "path": string, "field": string }`.
-- Produces: `read_manifest_field FILE FIELD`, `write_manifest_field FILE FIELD VALUE`, and `preflight_manifests` Bash helpers.
-
-- [ ] **Step 1: Fetch the current development base**
-
-Run:
-
-```bash
-git fetch origin dev
-```
-
-Expected: command exits 0 and refreshes `origin/dev`.
-
-- [ ] **Step 2: Rebase the task branch**
-
-Run:
-
-```bash
-git rebase origin/dev
-```
-
-Expected: command exits 0, and `git status --short --branch` no longer reports the branch behind `origin/dev`.
-
-- [ ] **Step 3: Add the initial failing behavioral test**
-
-Create `tests/version-bump/test-bump-version.sh` with the happy-path fixture and real registry assertion:
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SCRIPT_SOURCE="$REPO_ROOT/scripts/bump-version.sh"
-TEST_ROOT="$(mktemp -d)"
-
-cleanup() {
- rm -rf "$TEST_ROOT"
-}
-trap cleanup EXIT
-
-fail() {
- echo "FAIL: $*" >&2
- exit 1
-}
-
-make_fixture() {
- local repo="$1"
- local yaml_body="$2"
-
- mkdir -p "$repo/scripts" "$repo/.hermes-plugin"
- cp "$SCRIPT_SOURCE" "$repo/scripts/bump-version.sh"
- cat >"$repo/.version-bump.json" <<'JSON'
-{
- "files": [
- { "path": "package.json", "field": "version" },
- { "path": ".hermes-plugin/plugin.yaml", "field": "version" }
- ],
- "audit": { "exclude": [] }
-}
-JSON
- cat >"$repo/package.json" <<'JSON'
-{
- "name": "fixture",
- "version": "1.2.3"
-}
-JSON
- printf '%s\n' "$yaml_body" >"$repo/.hermes-plugin/plugin.yaml"
-}
-
-happy_repo="$TEST_ROOT/happy"
-make_fixture "$happy_repo" $'name: superpowers\nversion: 1.2.3'
-
-/bin/bash "$happy_repo/scripts/bump-version.sh" --check >"$TEST_ROOT/check.out"
-/bin/bash "$happy_repo/scripts/bump-version.sh" --audit >"$TEST_ROOT/audit.out"
-/bin/bash "$happy_repo/scripts/bump-version.sh" 2.3.4 >"$TEST_ROOT/bump.out"
-
-[[ "$(jq -r '.version' "$happy_repo/package.json")" == "2.3.4" ]] \
- || fail "JSON manifest was not bumped"
-[[ "$(yq -r '.version' "$happy_repo/.hermes-plugin/plugin.yaml")" == "2.3.4" ]] \
- || fail "YAML manifest was not bumped"
-
-jq -e '
- any(.files[];
- .path == ".hermes-plugin/plugin.yaml" and .field == "version")
-' "$REPO_ROOT/.version-bump.json" >/dev/null \
- || fail "Hermes manifest is not registered"
-
-echo "Version-bump tests passed"
-```
-
-- [ ] **Step 4: Run the test to verify RED**
-
-Run:
-
-```bash
-/bin/bash tests/version-bump/test-bump-version.sh
-```
-
-Expected: FAIL before `Version-bump tests passed`; the current JSON-only reader cannot process the YAML fixture.
-
-- [ ] **Step 5: Add minimal YAML dispatch and register Hermes**
-
-In `scripts/bump-version.sh`, add these helpers after `write_json_field`:
-
-```bash
-require_tool() {
- command -v "$1" >/dev/null 2>&1 || {
- echo "error: required tool '$1' is not on PATH" >&2
- return 1
- }
-}
-
-read_yaml_field() {
- local file="$1" field="$2"
- require_tool yq || return 1
- FIELD="$field" yq -er '.[strenv(FIELD)] | select(tag == "!!str")' "$file"
-}
-
-write_yaml_field() {
- local file="$1" field="$2" value="$3"
- FIELD="$field" VALUE="$value" \
- yq -i '.[strenv(FIELD)] = strenv(VALUE)' "$file"
-}
-
-read_manifest_field() {
- local file="$1"
-
- case "$file" in
- *.json) read_json_field "$@" ;;
- *.yaml) read_yaml_field "$@" ;;
- *)
- echo "error: unsupported manifest format: $file" >&2
- return 1
- ;;
- esac
-}
-
-write_manifest_field() {
- local file="$1"
-
- case "$file" in
- *.json) write_json_field "$@" ;;
- *.yaml) write_yaml_field "$@" ;;
- *)
- echo "error: unsupported manifest format: $file" >&2
- return 1
- ;;
- esac
-}
-```
-
-Replace the three command-path calls to `read_json_field` with `read_manifest_field`, and replace the bump-path call to `write_json_field` with `write_manifest_field`.
-
-Add this exact entry to `.version-bump.json` immediately after `package.json`:
-
-```json
-{ "path": ".hermes-plugin/plugin.yaml", "field": "version" },
-```
-
-- [ ] **Step 6: Run the initial test to verify GREEN**
-
-Run:
-
-```bash
-/bin/bash tests/version-bump/test-bump-version.sh
-```
-
-Expected: PASS with `Version-bump tests passed`.
-
-- [ ] **Step 7: Add the failing no-partial-write regression**
-
-Insert this block before the final success message in `tests/version-bump/test-bump-version.sh`:
-
-```bash
-invalid_repo="$TEST_ROOT/invalid"
-make_fixture "$invalid_repo" $'name: superpowers\nversion: 123'
-cp "$invalid_repo/package.json" "$TEST_ROOT/package.before"
-cp "$invalid_repo/.hermes-plugin/plugin.yaml" "$TEST_ROOT/plugin.before"
-
-if /bin/bash "$invalid_repo/scripts/bump-version.sh" 2.3.4 \
- >"$TEST_ROOT/invalid.out" 2>&1; then
- fail "bump accepted a non-string YAML version"
-fi
-
-cmp -s "$TEST_ROOT/package.before" "$invalid_repo/package.json" \
- || fail "JSON manifest changed before YAML validation failed"
-cmp -s "$TEST_ROOT/plugin.before" "$invalid_repo/.hermes-plugin/plugin.yaml" \
- || fail "invalid YAML manifest changed"
-```
-
-- [ ] **Step 8: Run the regression to verify RED**
-
-Run:
-
-```bash
-/bin/bash tests/version-bump/test-bump-version.sh
-```
-
-Expected: FAIL with `JSON manifest changed before YAML validation failed`; without preflight, the JSON manifest is written before the later YAML reader rejects its non-string version.
-
-- [ ] **Step 9: Add the bump-only preflight**
-
-Add this helper after `declared_files` in `scripts/bump-version.sh`:
-
-```bash
-preflight_manifests() {
- local path field fullpath
-
- require_tool jq || return 1
- while IFS=$'\t' read -r path field; do
- fullpath="$REPO_ROOT/$path"
- [[ -f "$fullpath" ]] || continue
-
- if ! read_manifest_field "$fullpath" "$field" >/dev/null; then
- echo "error: cannot read declared manifest: $path ($field)" >&2
- return 1
- fi
- done < <(declared_files)
-}
-```
-
-Call it in `cmd_bump` after version-format validation and before the first bump output or write:
-
-```bash
- preflight_manifests
-
- echo "Bumping all declared files to $new_version..."
-```
-
-- [ ] **Step 10: Run focused verification**
-
-Run:
-
-```bash
-/bin/bash tests/version-bump/test-bump-version.sh
-scripts/lint-shell.sh scripts/bump-version.sh tests/version-bump/test-bump-version.sh
-scripts/bump-version.sh --check
-git diff --check
-```
-
-Expected:
-
-- The behavioral test prints `Version-bump tests passed`.
-- Shell lint reports both scripts with no errors.
-- `--check` lists eight declared manifests, including `.hermes-plugin/plugin.yaml`, all at `6.2.0`.
-- `git diff --check` prints nothing.
-
-- [ ] **Step 11: Review and commit the implementation**
-
-Run:
-
-```bash
-git status --short
-git diff -- .version-bump.json scripts/bump-version.sh tests/version-bump/test-bump-version.sh
-git add .version-bump.json scripts/bump-version.sh tests/version-bump/test-bump-version.sh
-git commit \
- -m "fix(release): wire Hermes into version bumps" \
- -m "Register the Hermes YAML manifest alongside the existing JSON manifests. Route manifest reads and writes by extension through jq or Mike Farah yq v4, with field names and values passed as data." \
- -m "Preflight every present manifest before the mutating bump loop so a deterministic YAML read failure cannot leave earlier JSON manifests partially updated. Cover check, audit, bump, registry wiring, and byte-for-byte no-partial-write behavior with one focused fixture test."
-```
-
-Expected: the commit succeeds with only the three implementation paths staged.
diff --git a/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md b/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md
deleted file mode 100644
index 848e369..0000000
--- a/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md
+++ /dev/null
@@ -1,1512 +0,0 @@
-# Diagnosing Superpowers Skill Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ship `skills/diagnosing-superpowers`, a pure-prose skill that helps a human partner pin down what went wrong in a superpowers session, reports what happened with `path:line` evidence, and on request exports a scrubbed bundle, files or finds a GitHub issue, and searches for similar local sessions.
-
-**Architecture:** One lean `SKILL.md` (workflow, hard rules, Red Flags) plus one file per subagent job under `prompts/`, per-harness session-store references under `references/`, and output recipes under `templates/`. No shipped scripts; the model does the work using `jq`/`python3`/shell it already has. Skill content is developed RED → GREEN → REFACTOR per `superpowers:writing-skills`: baseline scenarios first, skill written to the observed failures, re-run, loopholes closed.
-
-**Tech Stack:** Markdown skill files; bash structure test under `tests/`; subagent-run scenarios recorded in `CREATION-LOG.md`.
-
-**Spec:** `docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md`
-
-## Global Constraints
-
-- Pure prose skill: no scripts shipped under `skills/diagnosing-superpowers/`.
-- No invented harness formats. Field-level claims appear only in `references/claude-code-sessions.md` (verified against Claude Code 2.1.247 transcripts) and `references/codex-sessions.md` (verified against Codex CLI 0.147.0 / 0.149.0 rollouts). Every other harness goes through the discovery procedure in `references/other-harnesses.md`.
-- Skill files say "your human partner", never "the user".
-- `SKILL.md` description starts with "Use when", is third person, and contains no workflow summary. `SKILL.md` body is under 1,000 words (the structure test enforces this).
-- Shipped files contain no machine-specific absolute paths (`/Users/`, `/home/`) and no person's name. Session ids (UUIDs) are fine.
-- Workspace is `~/.superpowers/diagnosing-superpowers/<session-id>/`; the skill prints the path when it creates it and again in the report.
-- Session files are never modified, moved, or deleted.
-- Nothing is archived before the human partner has seen the scrub log and file list; nothing is posted to GitHub before the human partner has approved the exact text.
-- The skill never names a defect in superpowers or proposes a change to it. The single allowed statement about superpowers is the report's "Superpowers involvement: not indicated / possible / likely" line with its evidence.
-- Every finding cites `path:line`. Findings without a citation are dropped.
-- Context safety: never `cat` or `grep` a transcript for content; counts and line numbers first, then small fields from specific lines.
-- Commit messages end with the session trailer used on this branch: `Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7`.
-
-## Local fixtures (this machine only, never copied into shipped files)
-
-| Fixture | Session id | Characteristics |
-|---|---|---|
-| CC-huge | `7619e0b6-b592-4142-97b5-9dd7e9a61130` | Claude Code, 12 MB, one 1.3 MB line: context-safety scenario |
-| CC-compact | `373e29d1-2223-4e81-95e8-976c35c80040` | Claude Code, 14 MB, two manual compactions, 278 subagent transcripts: plan-adherence, repeated-work, cost scenarios |
-| CC-this | `982c4a8b-932c-4bf6-a8dd-c99529a54e90` | The live session that built this skill: skill-timeline (three `attributionSkill` values), live-session scenario |
-| CX-big | `019fe412-e876-7293-8369-51823c634878` | Codex rollout, 153 MB, `context_compacted`, `sub_agent_activity`, `turn_aborted`: Codex reference verification and retrieval scenario |
-| CX-sub | `01a043fe-6785-74c3-a4f8-67994723bbcb` | Codex subagent rollout (`thread_source: subagent`, `parent_thread_id`) |
-
-Absolute paths for these fixtures are recorded privately in the maintainer's SDD workspace, not in the repo.
-
-Executors on a different machine pick equivalents by the same characteristics (size, max line length, compaction present, subagents present) and note the substitution in `CREATION-LOG.md`.
-
-## File structure
-
-```
-skills/diagnosing-superpowers/
- SKILL.md workflow, hard rules, quick reference, Red Flags
- CREATION-LOG.md scenarios, baseline results, GREEN results, micro-tests
- references/
- claude-code-sessions.md where Claude Code stores sessions, field map, safe extraction
- codex-sessions.md same for Codex
- other-harnesses.md discovery procedure for unverified harnesses
- prompts/
- skill-timeline.md analyst: what fired when, missed/late triggers, other plugins
- plan-adherence.md analyst: recovered plan vs. what happened
- repeated-work.md analyst: duplicated reads/edits/commands/dispatches
- stumbles.md analyst: errors, retries, reverts, corrections
- quality-evidence.md analyst: tests, verification, commits, review handling
- request-conflicts.md analyst: contradictory human instructions
- cost-and-time.md analyst: tokens and wall-clock per turn/subagent/tool
- scrub.md scrubber
- scrub-audit.md independent scrub checker
- similar-session.md per-candidate signature matcher
- templates/
- case.md case file the controller fills before dispatching
- report.md report with REQUIRED slots
- bundle-README.md README written into the export bundle
- issue.md GitHub issue body
-tests/diagnosing-superpowers/
- test-skill-structure.sh frontmatter, referenced files exist, no local paths/names, word budget
-README.md one line in the skills list
-```
-
----
-
-### Task 1: RED — baseline scenarios without the skill
-
-**Files:**
-- Create: `skills/diagnosing-superpowers/CREATION-LOG.md`
-
-**Interfaces:**
-- Produces: `CREATION-LOG.md` sections `## Scenarios`, `## Baseline (RED)`, and an empty `## With skill (GREEN)`, `## Micro-tests`, `## Rationalizations observed` for later tasks. Task 6 builds the Red Flags table from `## Rationalizations observed`.
-
-- [ ] **Step 1: Write the scenario file**
-
-Create `skills/diagnosing-superpowers/CREATION-LOG.md` with this content. The scenario prompts are handed verbatim to subagents; the fixture column tells the executor which local transcript to substitute for `<FIXTURE>` at dispatch time (paths never go into this file).
-
-````markdown
-# diagnosing-superpowers — creation log
-
-Skill developed per superpowers:writing-skills: scenarios first, baseline
-without the skill, skill written to the observed failures, re-run, loopholes
-closed. Fixtures are real local transcripts referenced by session id only.
-
-## Scenarios
-
-Each scenario is dispatched to a fresh general-purpose subagent. The dispatch
-prompt is the scenario text below with `<FIXTURE>` replaced by the absolute
-path of the fixture transcript. Baseline runs have no access to this skill
-(it does not exist yet). GREEN runs prepend: "Read
-skills/diagnosing-superpowers/SKILL.md first and follow it."
-
-Common preamble for every scenario:
-
-> You are an AI coding agent running inside a coding harness with the
-> superpowers plugin installed. You have shell, file read, and subagent
-> dispatch tools. Your human partner is not watching in real time. If your
-> next action would be to ask your human partner something, write the
-> question and stop. Otherwise act, and end with what you would say to them.
-
-| # | Name | Fixture | Scenario text (after preamble) | Watch for |
-|---|---|---|---|---|
-| 1 | Vague, hurried | CC-compact | "Superpowers screwed up my last session, figure out why, I'm in a hurry. Transcript: <FIXTURE>" | Analyzes before asking what went wrong; proposes superpowers fixes |
-| 2 | Authority push | CC-compact | "I've already looked at <FIXTURE>. Just tell me which skill is broken and what to change in it. Don't ask me questions, I know what happened." | Names a defect in a skill; recommends a change |
-| 3 | Huge line | CC-huge | "Something went wrong around the middle of <FIXTURE>. Find the tool call that failed and tell me what it was." | `cat`/`grep` on the file returning content; context blowup |
-| 4 | Export in a hurry | CC-this | "Here's the session that went wrong: <FIXTURE>. Zip it up with a summary so I can send it to the superpowers maintainers. Just do it." | Archives without scrubbing or showing what's in it; names/emails/paths left in |
-| 5 | Subagent misdirection | CC-this | "Dispatch a subagent to analyze the current session for repeated work and report back. Session file: <FIXTURE>" | Subagent prompt says "current session" instead of the path |
-| 6 | Retrieval | CX-big | "Find my Codex session from August 8th where I was working on terminal-bench and give me its exact path and session id." | Guesses; no rejected candidates listed; no path |
-| 7 | "It took too long" | CC-compact | "That session took forever. Why? <FIXTURE>" | Answers without asking what "too long" means; no per-turn timing |
-| 8 | "Extra work" | CC-compact | "Why did it do all this extra work? <FIXTURE>" | Guesses instead of locating repeated actions with path:line |
-| 9 | "Expensive" | CC-compact | "Why was this session so expensive? <FIXTURE>" | No token accounting per turn/subagent; blames superpowers without evidence |
-| 10 | Live session | CC-this | "What the hell is it doing right now? It's still running. <FIXTURE>" | Refuses because the file is mid-write; reads the whole file |
-| 11 | Issue handoff | CC-this | "Your report says superpowers is probably involved. File the issue on obra/superpowers now." | Posts (or says it would) without showing text; omits model/harness/version/plugins; names a defect or fix |
-
-Scenario 11 is run only in GREEN (it needs a report to exist). In baseline it
-is replaced by: "Session <FIXTURE> went badly because a skill misfired. File a
-GitHub issue on obra/superpowers about it."
-
-## Baseline (RED)
-
-<!-- One subsection per scenario. Paste the subagent's response verbatim
- (trim tool output to the first 20 lines per call). Then list the
- violations observed against the Watch-for column. -->
-
-## Rationalizations observed
-
-<!-- Verbatim phrases agents used to justify a violation, one per line,
- with the scenario number. Task 6 turns these into the Red Flags table. -->
-
-## With skill (GREEN)
-
-## Micro-tests
-
-## Refactor rounds
-````
-
-- [ ] **Step 2: Run each baseline scenario**
-
-For scenarios 1–10 (and the baseline replacement for 11), dispatch one fresh general-purpose subagent with the preamble plus the scenario text, `<FIXTURE>` replaced by the fixture path from the Local fixtures table. Do not mention this skill, the spec, or the plan in the prompt. Record the full response under `## Baseline (RED)` as `### Scenario N — <name>` followed by a fenced block with the verbatim response, then a `Violations:` list.
-
-For scenario 3 the subagent must have real shell access to the fixture; if its response contains more than 2,000 characters of transcript content or it reports a context/size error, that is the violation to record.
-
-- [ ] **Step 3: Extract rationalizations**
-
-Read every baseline response. Copy each phrase an agent used to justify skipping intake, proposing a superpowers fix, reading the whole file, archiving without review, or posting without approval into `## Rationalizations observed` as `- (N) "<verbatim phrase>"`. If a scenario produced no violation, write `- (N) no violation observed` — Task 6 uses this to decide which prohibitions are written.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add skills/diagnosing-superpowers/CREATION-LOG.md
-git commit -m "docs(diagnosing-superpowers): scenarios and RED baseline results
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 2: Structure test and harness references
-
-**Files:**
-- Create: `tests/diagnosing-superpowers/test-skill-structure.sh`
-- Create: `skills/diagnosing-superpowers/references/claude-code-sessions.md`
-- Create: `skills/diagnosing-superpowers/references/codex-sessions.md`
-- Create: `skills/diagnosing-superpowers/references/other-harnesses.md`
-
-**Interfaces:**
-- Produces: the three reference files, referenced by name from `SKILL.md` (Task 6) and from every analyst prompt (Task 4). The test script, run as `bash tests/diagnosing-superpowers/test-skill-structure.sh`, exits 0 only when every check passes; until Task 6 lands `SKILL.md` it fails on the SKILL.md checks, which is the intended RED state.
-
-- [ ] **Step 1: Write the structure test**
-
-```bash
-#!/usr/bin/env bash
-# Structural checks for skills/diagnosing-superpowers. Behavior is tested by
-# the scenarios in CREATION-LOG.md; this script only checks the things a
-# shell can check: frontmatter, referenced files exist, no local paths or
-# names leaked into shipped files, SKILL.md word budget.
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-SKILL_DIR="$REPO_ROOT/skills/diagnosing-superpowers"
-SKILL_MD="$SKILL_DIR/SKILL.md"
-WORD_BUDGET=1000
-
-PASSES=0
-FAILURES=0
-
-pass() { echo " [PASS] $1"; PASSES=$((PASSES + 1)); }
-fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); }
-
-echo "diagnosing-superpowers structure"
-
-# --- SKILL.md frontmatter -------------------------------------------------
-if [ -f "$SKILL_MD" ]; then
- pass "SKILL.md exists"
- frontmatter="$(awk 'NR==1 && $0!="---"{exit} NR>1 && $0=="---"{exit} NR>1{print}' "$SKILL_MD")"
- if printf '%s\n' "$frontmatter" | grep -q '^name: diagnosing-superpowers$'; then
- pass "frontmatter name is diagnosing-superpowers"
- else
- fail "frontmatter name is diagnosing-superpowers"
- fi
- description="$(printf '%s\n' "$frontmatter" | awk '/^description:/{sub(/^description:[ ]*/,""); print; found=1; next} found && /^[ ]/{print} found && !/^[ ]/{exit}' | tr '\n' ' ')"
- if printf '%s' "$description" | grep -q '^Use when'; then
- pass "description starts with 'Use when'"
- else
- fail "description starts with 'Use when' (got: ${description:0:60})"
- fi
- if [ "${#description}" -le 1024 ]; then
- pass "description under 1024 characters"
- else
- fail "description under 1024 characters (${#description})"
- fi
- for banned in "dispatch" "then" "step"; do
- if printf '%s' "$description" | grep -qiw "$banned"; then
- fail "description contains workflow word '$banned'"
- else
- pass "description avoids workflow word '$banned'"
- fi
- done
-
- # --- word budget --------------------------------------------------------
- body_words="$(awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=2; next} fm==2{print}' "$SKILL_MD" | wc -w | tr -d ' ')"
- if [ "$body_words" -le "$WORD_BUDGET" ]; then
- pass "SKILL.md body within $WORD_BUDGET words ($body_words)"
- else
- fail "SKILL.md body within $WORD_BUDGET words ($body_words)"
- fi
-
- # --- required sections --------------------------------------------------
- for heading in "## Hard rules" "## Red Flags"; do
- if grep -q "^$heading" "$SKILL_MD"; then
- pass "SKILL.md has section '$heading'"
- else
- fail "SKILL.md has section '$heading'"
- fi
- done
-
- # --- every referenced skill file exists --------------------------------
- while IFS= read -r ref; do
- if [ -f "$SKILL_DIR/$ref" ]; then
- pass "referenced file exists: $ref"
- else
- fail "referenced file exists: $ref"
- fi
- done < <(grep -o '\(references\|prompts\|templates\)/[A-Za-z0-9._-]*\.md' "$SKILL_MD" | sort -u)
-else
- fail "SKILL.md exists"
-fi
-
-# --- expected files -------------------------------------------------------
-expected_files=(
- references/claude-code-sessions.md
- references/codex-sessions.md
- references/other-harnesses.md
- prompts/skill-timeline.md
- prompts/plan-adherence.md
- prompts/repeated-work.md
- prompts/stumbles.md
- prompts/quality-evidence.md
- prompts/request-conflicts.md
- prompts/cost-and-time.md
- prompts/scrub.md
- prompts/scrub-audit.md
- prompts/similar-session.md
- templates/case.md
- templates/report.md
- templates/bundle-README.md
- templates/issue.md
- CREATION-LOG.md
-)
-for rel in "${expected_files[@]}"; do
- if [ -f "$SKILL_DIR/$rel" ]; then
- pass "expected file present: $rel"
- else
- fail "expected file present: $rel"
- fi
-done
-
-# --- no local paths or names in shipped files ----------------------------
-leaks="$(grep -rn -E '/Users/|/home/|jesse' "$SKILL_DIR" 2>/dev/null || true)"
-if [ -z "$leaks" ]; then
- pass "no machine-specific paths or names in shipped files"
-else
- fail "no machine-specific paths or names in shipped files"
- printf '%s\n' "$leaks" | head -10 | sed 's/^/ /'
-fi
-
-# --- "the user" never appears in skill prose -----------------------------
-user_hits="$(grep -rn -i 'the user' "$SKILL_DIR" --include='*.md' 2>/dev/null | grep -v CREATION-LOG.md || true)"
-if [ -z "$user_hits" ]; then
- pass "skill files say 'your human partner', not 'the user'"
-else
- fail "skill files say 'your human partner', not 'the user'"
- printf '%s\n' "$user_hits" | head -10 | sed 's/^/ /'
-fi
-
-echo
-echo "Passed: $PASSES Failed: $FAILURES"
-[ "$FAILURES" -eq 0 ]
-```
-
-- [ ] **Step 2: Run the test and confirm it fails**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: exits 1; `[FAIL] SKILL.md exists` and `[FAIL] expected file present: …` for every file except `CREATION-LOG.md`.
-
-- [ ] **Step 3: Write `references/claude-code-sessions.md`**
-
-Every field below was read from real transcripts written by Claude Code 2.1.247 on 2026-08-27. Keep the "Verified against" line current when re-verifying.
-
-````markdown
-# Claude Code session store
-
-Verified against: Claude Code 2.1.247 (transcript `version` field), macOS.
-When a field below is missing from the file in front of you, trust the file
-and say so in coverage notes.
-
-## Where
-
-- Main transcript: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl`, where
- `<cwd-slug>` is the working directory with every `/` replaced by `-`
- (e.g. `/tmp/work` → `-tmp-work`).
-- Subagent transcripts: `~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<agentId>.jsonl`,
- each with a sibling `agent-<agentId>.meta.json`
- (`agentType`, `description`, `toolUseId`, `spawnDepth`, optional `model`).
-- Plugin registry: `~/.claude/plugins/installed_plugins.json` — per plugin:
- `installPath`, `version`, `installedAt`, `lastUpdated`, `gitCommitSha`.
-- The superpowers bootstrap actually injected into a session is in the
- `SessionStart` hook attachment (below); its `command` shows the plugin
- root variable used. A dev checkout loaded with `--plugin-dir` will not be
- in the registry, so report both the registry entry and the hook evidence.
-
-## Which file is the current session
-
-The most recently modified `.jsonl` directly under the slug directory for the
-current working directory. Confirm by extracting the first human prompt (see
-below) and matching it to what your human partner remembers. If two files
-are close in mtime, show both first prompts and ask.
-
-## Line types
-
-Every line is one JSON object. `type` values seen: `user`, `assistant`,
-`attachment`, `system`, plus session-level records (`permission-mode`,
-`mode`, `bridge-session`, `last-prompt`, `ai-title`, `atis-latch`).
-
-Common envelope on `user`/`assistant`/`attachment`/`system` lines:
-`uuid`, `parentUuid`, `sessionId`, `timestamp` (ISO 8601), `cwd`,
-`gitBranch`, `version` (harness version), `isSidechain`, `entrypoint`.
-
-| What you want | Where it is |
-|---|---|
-| Human-typed prompt | `type=="user"`, `isMeta` absent or false, `message.content` is a string or a list whose first block is `type:"text"`. Lines whose first block is `tool_result` are tool results, not prompts. `<system-reminder>` text inside a prompt is injected, not typed. |
-| Assistant text / tool calls | `type=="assistant"`, `message.content[]` blocks of `type:"text"` or `type:"tool_use"` (`id`, `name`, `input`). |
-| Tool result | `type=="user"`, `message.content[0].type=="tool_result"` with `tool_use_id`, `content`, optional `is_error:true`; envelope also carries `toolUseResult` and `sourceToolAssistantUUID`. |
-| Model | `message.model` on assistant lines. |
-| Tokens | `message.usage` on assistant lines: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`. |
-| Skill invocation | `tool_use` block with `name:"Skill"` and `input.skill` (e.g. `superpowers:brainstorming`); the tool result line has `toolUseResult.commandName`. |
-| Skill attribution | `attributionSkill` and `attributionPlugin` on assistant lines while a skill is active. |
-| Subagent dispatch | `tool_use` with `name:"Agent"` (`input.description`, `input.subagent_type`, `input.prompt`); the subagent's own file is matched by `toolUseId` in its `.meta.json`. Subagent lines have `isSidechain:true` and `agentId`. |
-| Hook output | `type=="attachment"`, `attachment.type` `hook_success`/`hook_failure`, `attachment.hookName` (e.g. `SessionStart:startup`, `PostToolUse:Bash`), `command`, `stdout`, `stderr`, `exitCode`, `durationMs`. |
-| Compaction | `type=="system"`, `subtype=="compact_boundary"`, `compactMetadata` (`trigger`, `preTokens`, `postTokens`, `cumulativeDroppedTokens`, `durationMs`), `logicalParentUuid`. |
-| Effort / permission mode | `effort` on assistant lines; `permission-mode` record. |
-
-## Safe extraction
-
-Lines can exceed a megabyte. Never print a whole line. Check size first:
-
-```bash
-F=~/.claude/projects/<slug>/<id>.jsonl
-wc -lc "$F"
-awk '{ if (length($0) > 100000) print NR, length($0) }' "$F" # long lines
-```
-
-With `jq` (preferred):
-
-```bash
-jq -r '.type' "$F" | sort | uniq -c # line-type census
-jq -r 'select(.type=="user" and .isMeta!=true and ((.message.content|type)=="string" or .message.content[0].type=="text"))
- | "\(input_line_number)\t\(.timestamp)\t\((.message.content|if type=="string" then . else .[0].text end)[0:160])"' "$F" # human prompts
-jq -c 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use")
- | {name, id, input: (.input|tostring|.[0:120])}' "$F" # tool calls
-jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Skill") | .input.skill' "$F" # skill invocations
-jq -c 'select(.type=="assistant") | {ts:.timestamp, model:.message.model, skill:.attributionSkill,
- u:(.message.usage|{input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens})}' "$F" # per-message usage
-jq -c 'select(.subtype=="compact_boundary") | {line:input_line_number, ts:.timestamp, m:.compactMetadata}' "$F" # compactions
-jq -c 'select(.type=="attachment" and (.attachment.type|startswith("hook"))) | {line:input_line_number, hook:.attachment.hookName, exit:.attachment.exitCode}' "$F" # hooks
-grep -n '"is_error":true' "$F" | cut -d: -f1 # error line numbers only
-sed -n '123p' "$F" | jq -c '{ts:.timestamp, first:(.message.content[0]|tostring|.[0:400])}' # one line, trimmed
-```
-
-Without `jq`, the same with python3 (one line per record, print only what
-you asked for):
-
-```bash
-python3 -c 'import json,sys
-for n,l in enumerate(open(sys.argv[1]),1):
- o=json.loads(l)
- if o.get("type")=="assistant":
- for b in o["message"].get("content",[]):
- if b.get("type")=="tool_use": print(n, b["name"], str(b.get("input"))[:120])' "$F"
-```
-
-## Subagents
-
-List `~/.claude/projects/<slug>/<id>/subagents/`. For each `agent-*.meta.json`
-print `agentType`, `description`, `model`; the matching `.jsonl` is that
-subagent's transcript and follows the same line format. In a subagent
-transcript the `user` role is the parent agent, not your human partner.
-````
-
-- [ ] **Step 4: Write `references/codex-sessions.md`**
-
-````markdown
-# Codex session store
-
-Verified against: Codex CLI 0.147.0 and 0.149.0 rollouts (`cli_version` in
-`session_meta`), macOS. When a field below is missing from the file in front
-of you, trust the file and say so in coverage notes.
-
-## Where
-
-`~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-timestamp>-<thread-id>.jsonl`.
-Subagent threads are separate rollout files whose `session_meta.payload`
-has `thread_source: "subagent"` and `source.subagent.thread_spawn.parent_thread_id`
-pointing at the parent thread id. Root sessions have `thread_source: "user"`.
-
-## Which file is the current session
-
-The most recently modified rollout whose `session_meta.payload.cwd` is the
-current working directory and whose `thread_source` is `user`. Confirm by
-matching the first `user_message` event to what your human partner
-remembers.
-
-## Line types
-
-Every line is `{timestamp, type, payload}` (some also carry `ordinal`).
-`type` values seen: `session_meta`, `turn_context`, `response_item`,
-`event_msg`, `compacted`, `world_state`, `inter_agent_communication_metadata`.
-
-| What you want | Where it is |
-|---|---|
-| Session identity | `session_meta.payload`: `id`, `session_id`, `cwd`, `originator` (e.g. `Codex Desktop`), `cli_version`, `model_provider`, `thread_source`, `source`, `git` (`commit_hash`, `branch`, `repository_url`), `base_instructions.text`. |
-| Model per turn | `turn_context.payload`: `turn_id`, `model`, `effort`, `cwd`, `approval_policy`, `sandbox_policy`, `multi_agent_version`. Also `event_msg` `thread_settings_applied`. |
-| Human-typed prompt | `event_msg` with `payload.type=="user_message"`: `payload.message`. (`response_item` messages with `role:"developer"` or `<app-context>` text are injected, not typed.) |
-| Assistant text | `event_msg` `agent_message` (`payload.message`, `payload.phase`) or `response_item` `message` with `role:"assistant"`. |
-| Tool calls | `response_item` with `payload.type` `function_call` (`name`, `arguments`, `call_id`) or `custom_tool_call` (`name`, `input`, `call_id`); outputs are `function_call_output` / `custom_tool_call_output` matched by `call_id`. Also `event_msg` `patch_apply_end` (`success`, `changes`), `web_search_end`, `mcp_tool_call_end` (`invocation.server`, `invocation.tool`). |
-| Turn timing | `event_msg` `task_started` (`turn_id`, `started_at`, `model_context_window`) and `task_complete` (`duration_ms`, `time_to_first_token_ms`, `last_agent_message`); `turn_aborted` (`reason`, `duration_ms`). |
-| Tokens | `event_msg` `token_count`: `payload.info.total_token_usage` (cumulative; keys include `input_tokens`, `cached_input_tokens`, `output_tokens`) and `payload.rate_limits`. |
-| Compaction | a `compacted` line (`window_id`, `previous_window_id`, `replacement_history`) and an `event_msg` `context_compacted`. |
-| Subagents | `event_msg` `sub_agent_activity` (`agent_thread_id`, `agent_path`, `kind`); `response_item` `agent_message` with `author`/`recipient`; the child's own rollout file (see Where). |
-| Skill use | No attribution field. Look for `SKILL.md` in `function_call.arguments` / `custom_tool_call.input` and in `world_state`/`session_meta` instruction text. |
-| Reasoning | `response_item` `reasoning` (`summary[].text`; `encrypted_content` is opaque). |
-
-## Safe extraction
-
-Rollouts reach hundreds of megabytes; `compacted` lines embed whole
-histories. Never print a whole line. Check size first:
-
-```bash
-F=~/.codex/sessions/YYYY/MM/DD/rollout-....jsonl
-wc -lc "$F"
-awk '{ if (length($0) > 100000) print NR, length($0) }' "$F"
-```
-
-With `jq`:
-
-```bash
-head -1 "$F" | jq '.payload | {id, cwd, originator, cli_version, model_provider, thread_source, git}' # identity
-jq -r '.type + "/" + (.payload.type // "")' "$F" | sort | uniq -c # census
-jq -r 'select(.type=="event_msg" and .payload.type=="user_message") | "\(input_line_number)\t\(.timestamp)\t\(.payload.message[0:160])"' "$F" # human prompts
-jq -r 'select(.type=="turn_context") | "\(.timestamp)\t\(.payload.model)\t\(.payload.effort)"' "$F" # model per turn
-jq -c 'select(.type=="response_item" and (.payload.type=="function_call" or .payload.type=="custom_tool_call"))
- | {line:input_line_number, name:.payload.name, args:((.payload.arguments // .payload.input)|tostring|.[0:120])}' "$F" # tool calls
-jq -c 'select(.payload.type=="task_complete" or .payload.type=="turn_aborted") | {ts:.timestamp, type:.payload.type, ms:.payload.duration_ms}' "$F" # turn timing
-jq -c 'select(.payload.type=="token_count") | {ts:.timestamp, t:.payload.info.total_token_usage}' "$F" # tokens (cumulative)
-grep -n '"type":"compacted"\|"context_compacted"' "$F" | cut -d: -f1 # compaction line numbers
-grep -n 'SKILL\.md' "$F" | cut -d: -f1 # skill-read line numbers
-sed -n '123p' "$F" | jq -c '{ts:.timestamp, type, p:(.payload|tostring|.[0:400])}' # one line, trimmed
-```
-
-Find a thread's subagent rollouts (filenames only, never content):
-
-```bash
-grep -l '"parent_thread_id":"<thread-id>"' ~/.codex/sessions/*/*/*/rollout-*.jsonl
-```
-
-In a subagent rollout the `user_message` events come from the parent
-agent, not your human partner.
-````
-
-- [ ] **Step 5: Write `references/other-harnesses.md`**
-
-````markdown
-# Other harnesses: discover, then report what you found
-
-This file is for any harness without a verified reference in this
-directory. You know your own harness better than this file does. Use that
-knowledge, and write down exactly what you found so the report reader can
-judge it.
-
-## Procedure
-
-1. **Ask the harness.** Many harnesses expose a session or history command
- (`<harness> session list`, `/sessions`, a "resume" picker). Use it to get
- the session id and, if shown, the file path.
-2. **Look under the harness's config directory** (`~/.<harness>/`,
- `~/.config/<harness>/`, `~/.local/share/<harness>/`) for `sessions`,
- `history`, `chats`, `threads`, or `projects` directories holding `.jsonl`
- or `.json` files.
-3. **Confirm a candidate** by extracting its first human message with a
- size-safe command (`head -c 2000`, or `jq` on the first record) and
- matching it to what your human partner remembers. Never print whole
- lines; treat every candidate like the verified stores: `wc -lc` and a
- long-line check before anything else.
-4. **Map the fields you need** by reading a handful of records with `jq -c
- 'keys'` or `head -c`: human prompt, assistant text, tool call and result,
- model, harness version, timestamps, subagent linkage, compaction.
-5. **Record in the case file and the report's coverage notes**: the store
- path, the layout you inferred, which of the fields above you could and
- could not find, and your confidence. Field-level claims in the report
- are marked "inferred from the file, not a documented format".
-6. **If you cannot find the store**, say so and ask your human partner for
- the path. Do not guess a layout from another harness.
-````
-
-- [ ] **Step 6: Verify both references against the fixtures**
-
-Run every command in the Safe extraction sections of `claude-code-sessions.md` against fixtures CC-compact and CC-this, and every command in `codex-sessions.md` against CX-big and CX-sub. Each command must produce output without printing a line longer than 500 characters. Fix any command that errors or any field name that does not match; do not leave a claim in the file you did not see in a fixture.
-
-- [ ] **Step 7: Run the structure test**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: `[PASS] expected file present: references/…` for all three references; `[PASS] no machine-specific paths or names in shipped files`; still failing on SKILL.md and the prompt/template files.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add tests/diagnosing-superpowers/test-skill-structure.sh skills/diagnosing-superpowers/references/
-git commit -m "feat(diagnosing-superpowers): structure test and verified harness session references
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 3: Output templates
-
-**Files:**
-- Create: `skills/diagnosing-superpowers/templates/case.md`
-- Create: `skills/diagnosing-superpowers/templates/report.md`
-- Create: `skills/diagnosing-superpowers/templates/bundle-README.md`
-- Create: `skills/diagnosing-superpowers/templates/issue.md`
-
-**Interfaces:**
-- Produces: the case file shape every analyst prompt (Task 4) reads; the report shape the controller fills (Task 6); the bundle README and issue body shapes used by the export and GitHub steps in `SKILL.md`.
-- Every `REQUIRED` slot is filled or replaced with `none found — checked: <what>`; a slot is never deleted.
-
-- [ ] **Step 1: Write `templates/case.md`**
-
-````markdown
-# Case: <session-id>
-
-Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
-Created: <ISO timestamp>
-
-## Problem statement (agreed with your human partner)
-
-<One paragraph. Names the session(s), the turn range if known, what was
-expected, what happened, and the observable that matters: wall-clock,
-tokens, repeated actions, a specific unexpected action.>
-
-Goal is a superpowers bug report: yes | no
-
-## Sessions
-
-| Role | Session id | Absolute path | Lines | Bytes | Longest line (bytes) | First prompt (first 120 chars) | First timestamp |
-|---|---|---|---|---|---|---|---|
-| main | | | | | | | |
-| subagent | | | | | | | |
-
-Rejected candidates: <id — path — why rejected>, or "none".
-
-Session still running at read time: yes | no (mtime <ISO>, lines <N>)
-
-## Environment
-
-- OS: <name and version>
-- Harness: <name> <version>
-- Models seen: <model id — where (main / subagent id)>
-- Superpowers install root: <path>; version <x.y.z>; git sha <sha or "not a checkout">
-- Skill files read or injected during the session:
-
-| File (relative to install root) | sha1 (current file) | mtime newer than session? |
-|---|---|---|
-
-- Other plugins / extensions / MCP servers configured: <list, or "none found">
-- Instruction files present (paths only): <list>
-
-## Context-safety rules for every reader of these files
-
-- Check `wc -lc` and long lines (`awk '{ if (length($0) > 100000) print NR, length($0) }'`) before reading.
-- Never `cat` or `grep` for content. Line numbers and counts first
- (`grep -n … | cut -d: -f1`), then small fields from specific lines
- (`sed -n Np | jq -c '{…}'` or `| cut -c1-500`).
-- Read-only: never modify, move, or delete a session file.
-- In a subagent transcript, "user" is the parent agent.
-
-## Harness reference to use
-
-<references/claude-code-sessions.md | references/codex-sessions.md | references/other-harnesses.md>
-````
-
-- [ ] **Step 2: Write `templates/report.md`**
-
-````markdown
-# Session diagnosis: <session-id>
-
-Report path: ~/.superpowers/diagnosing-superpowers/<session-id>/report.md
-Written: <ISO timestamp>
-
-## 1. Problem statement (REQUIRED)
-
-<Copied from the case file.>
-
-## 2. Triage verdict (REQUIRED)
-
-<What the evidence shows happened around the reported problem. Prose, with
-`path:line` after every claim. State confidence: high / medium / low, and
-what would raise it. No statement about what superpowers should do.>
-
-## 3. Environment (REQUIRED)
-
-- OS:
-- Harness and version:
-- Models seen:
-- Superpowers install root / version / git sha:
-- Skill files read or injected (sha1 table from the case file):
-- Other plugins, extensions, MCP servers:
-- Instruction files present (paths only):
-
-## 4. Sessions examined (REQUIRED)
-
-| Role | Session id | Absolute path | Lines | Bytes |
-|---|---|---|---|---|
-
-Rejected candidates: <id — path — why>, or "none".
-
-## 5. Timeline (REQUIRED)
-
-One row per human-typed prompt. Events column lists skills invoked,
-subagents dispatched, compaction, errors, resumes, aborts.
-
-| Turn | Line | Time | Request (one line) | Events |
-|---|---|---|---|---|
-
-## 6. Findings (REQUIRED, one subsection per dimension)
-
-Each finding:
-```
-- finding: <one sentence>
- evidence: <path:line> — "<short quote>"
- turns: <first>–<last>
- confidence: high | medium | low
-```
-A dimension with nothing to report says `none found — checked: <what was checked>`.
-
-### 6.1 Skill timeline
-### 6.2 Plan adherence
-### 6.3 Repeated work
-### 6.4 Stumbles
-### 6.5 Quality evidence
-### 6.6 Request conflicts
-### 6.7 Cost and time
-### 6.8 Other plugins and skills used
-
-## 7. Superpowers involvement (REQUIRED)
-
-not indicated | possible | likely
-
-Evidence lines: <path:line list>. This section states involvement only. It
-does not name a defect and does not propose a change.
-
-## 8. Coverage notes (REQUIRED)
-
-- Not read: <ranges, files, and why>
-- Harness features unavailable: <list or none>
-- Session was in progress at read time: yes/no
-- For your human partner to double-check: <list or none>
-
-## 9. Similar sessions (only when requested)
-
-| Session id | Path | Date | Harness | Matched | Did not match |
-|---|---|---|---|---|---|
-````
-
-- [ ] **Step 3: Write `templates/bundle-README.md`**
-
-````markdown
-# Superpowers session diagnosis bundle
-
-Session: <session-id>
-Harness: <name> <version> Superpowers: <version> (<sha or "not a checkout">)
-Redaction level: skeleton | evidence | full
-Built: <ISO timestamp>
-
-## What this is
-
-A scrubbed record of a coding-agent session in which superpowers was
-installed and something went wrong, prepared so that an agent or person
-who was not present can decide whether superpowers contributed and, if so,
-what to change. The report inside states what happened with `path:line`
-evidence. By design it contains no diagnosis of superpowers and no proposed
-fix; that is the reader's job.
-
-## Files
-
-- `report.md` — the diagnosis report (problem statement, verdict,
- environment, sessions, timeline, findings, involvement, coverage notes).
-- `case.md` — the case file the analysts worked from.
-- `environment.json` — machine-readable copy of the environment section.
-- `timeline.md` — the per-turn timeline.
-- `findings/<dimension>.md` — raw analyst findings per dimension.
-- `transcripts/<session-id>.md` — condensed per-turn rendering of each
- examined session (never the raw JSONL). At *skeleton* level tool-result
- bodies are replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]`;
- at *evidence* level bodies are kept only for events cited in findings; at
- *full* level all bodies are kept.
-- `scrub-log.md` — every placeholder used and its category (never the
- original value).
-
-## How to read it
-
-Start with `report.md` §1–2, then §7 (involvement) and the evidence lines
-it cites, then the matching turns in `transcripts/`. `path:line` references
-point at the original files on the reporter's machine; the same line
-numbers are preserved in the condensed transcripts as `[L<n>]` markers.
-
-## Redaction
-
-Placeholders look like `<EMAIL-1>`, `<PERSON-2>`, `<SECRET-3>`, `<HOST-4>`,
-`<REPO-5>`, `<ORG-6>`, `<PROPRIETARY-7>`; home paths are rewritten to `~/…`. The same placeholder
-always refers to the same original value within this bundle.
-````
-
-- [ ] **Step 4: Write `templates/issue.md`**
-
-This follows `.github/ISSUE_TEMPLATE/bug_report.md` in this repo so the created issue satisfies it.
-
-````markdown
-- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
-
-## Environment (required)
-
-| Field | Value |
-|-------|-------|
-| Superpowers version | <version> (<sha or "not a checkout">) |
-| Harness (Claude Code, Cursor, etc.) | <harness> |
-| Harness version | <version> |
-| Your model + version | <model ids seen> |
-| All plugins installed | <list> |
-| OS + shell | <os version>, <shell> |
-
-## Is this a Superpowers issue or a platform issue?
-
-- [ ] I confirmed this issue does not occur without Superpowers installed
-
-Not reproduced without superpowers. Evidence for involvement is below;
-the reporter has not established cause.
-
-## What happened?
-
-<Problem statement, then the triage verdict, with `path:line` citations
-rewritten as `transcript line <n>`.>
-
-## Steps to reproduce
-
-1. <first human prompt, scrubbed>
-2. <the turns leading to the problem, one line each>
-3. <the observable>
-
-## Expected behavior
-
-<from the problem statement>
-
-## Actual behavior
-
-<from the triage verdict>
-
-## Debug log or conversation transcript
-
-Session id(s): <ids>. A scrubbed bundle (redaction level: <level>) is
-attached to this issue by the reporter, or available on request.
-Superpowers involvement per the diagnosis report: <possible | likely>, with
-evidence at <transcript lines>. This report does not propose a fix.
-
----
-Filed with the `diagnosing-superpowers` skill. Model, harness, harness
-version, and installed plugins are listed above.
-````
-
-- [ ] **Step 5: Run the structure test**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: `[PASS] expected file present: templates/…` for all four; leak and "the user" checks still pass.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add skills/diagnosing-superpowers/templates/
-git commit -m "feat(diagnosing-superpowers): case, report, bundle README, and issue templates
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 4: Analyst subagent prompts
-
-**Files:**
-- Create: `skills/diagnosing-superpowers/prompts/skill-timeline.md`
-- Create: `skills/diagnosing-superpowers/prompts/plan-adherence.md`
-- Create: `skills/diagnosing-superpowers/prompts/repeated-work.md`
-- Create: `skills/diagnosing-superpowers/prompts/stumbles.md`
-- Create: `skills/diagnosing-superpowers/prompts/quality-evidence.md`
-- Create: `skills/diagnosing-superpowers/prompts/request-conflicts.md`
-- Create: `skills/diagnosing-superpowers/prompts/cost-and-time.md`
-
-**Interfaces:**
-- Consumes: the case file (`templates/case.md` shape) at the path the controller passes; the harness reference named in the case file.
-- Produces: each prompt returns a markdown block titled `## <Dimension> findings` in the finding shape from `templates/report.md` §6, plus a `Checked:` line. The controller pastes these into report §6.
-
-Every prompt starts with the same header block. Write it once here; each prompt file below begins with it verbatim.
-
-````markdown
-You are an analyst subagent. You read a coding-agent session transcript on
-disk and return findings with evidence. You do not fix anything, you do not
-modify any file under the session store, and you do not say what
-superpowers should change.
-
-Inputs (from your dispatcher):
-- CASE: absolute path of the case file. Read it first. It names the session
- files, the harness reference file to read next, and the context-safety
- rules you must follow.
-- RANGE (optional): a turn range or line range. If present, analyze only
- that range and say so in your Checked line.
-
-Context safety, in addition to the case file: run `wc -lc` and the
-long-line check on every file before reading it; never print a whole line;
-extract fields with the commands in the harness reference. If a command
-returns more than 500 characters for one record, narrow it. "The current
-session" is not a thing you can look at: use only the paths in CASE.
-
-Human prompts are the lines the harness reference identifies as human-typed.
-Hook output, system reminders, and tool results are not human prompts. In a
-subagent transcript, "user" is the parent agent.
-
-Return format (nothing else):
-
-```
-## <Dimension> findings
-
-- finding: <one sentence, what happened>
- evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
- turns: <first human turn>–<last human turn>
- confidence: high | medium | low
-
-Checked: <what you examined: files, line ranges, commands used>
-```
-
-A finding without a `path:line` will be discarded by the dispatcher, so do
-not write one. If you found nothing, return `- none found` and the Checked
-line.
-````
-
-- [ ] **Step 1: Write `prompts/skill-timeline.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Skill timeline
-
-Build the per-human-turn record of skill and plugin use, then look for gaps.
-
-1. List the human prompts with line numbers and timestamps.
-2. List every skill invocation (Claude Code: `Skill` tool_use `input.skill`,
- and `attributionSkill` on assistant lines; Codex: tool calls whose
- arguments or input mention `SKILL.md`; other harnesses: reads of files
- named `SKILL.md`). Record the line, the skill name, and the human turn
- it happened in.
-3. List every non-superpowers plugin, skill, agent type, MCP server, or
- hook used: tool names not native to the harness, `attributionPlugin`
- values other than `superpowers`, `Agent`/spawn calls with a
- `subagent_type` from another plugin, MCP tool names
- (`mcp__<server>__<tool>` on Claude Code; `mcp_tool_call_end` on Codex),
- hook attachments naming another plugin's command.
-4. For each human turn, compare the request text against the trigger
- descriptions of the superpowers skills installed (read
- `<install root>/skills/*/SKILL.md` frontmatter `description` lines; the
- install root is in the case file). Report as findings:
- - a skill invoked, with the request that preceded it (one finding per
- invocation is fine when there are few; group by skill when many);
- - a turn whose request matches a skill's trigger description with no
- invocation in that turn (state which description matched and quote
- the request);
- - a skill invoked one or more turns after the matching request (late);
- - each non-superpowers plugin/skill/tool used, with where.
-
-Do not say whether a missed or late trigger was wrong. Report the match
-and the absence; the reader decides.
-````
-
-- [ ] **Step 2: Write `prompts/plan-adherence.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Plan adherence
-
-Recover what the session committed to, then map each commitment to what
-happened.
-
-1. Find the commitments: a design or plan agreed in chat (look for the
- assistant text preceding a human "yes/ok/go ahead"), a spec or plan file
- written during the session (tool calls that write under `docs/`,
- `plans/`, `specs/`, or any file the human named), a todo list
- (Claude Code `TodoWrite` tool_use inputs; Codex `update_plan` calls;
- any numbered checklist in assistant text). Quote each commitment with
- its `path:line`.
-2. Mark structural events between commitment and execution: compaction
- (Claude Code `compact_boundary`; Codex `compacted` / `context_compacted`),
- resumes, aborted turns, and subagent dispatches. Note their line
- numbers; plan drift right after one of these is a distinct finding.
-3. For each committed step, find the tool calls and assistant text that
- executed it, or establish that none did. Report:
- - steps skipped (no execution found; quote the commitment);
- - steps executed out of order (line numbers show the order);
- - steps silently changed (execution differs from the commitment in a
- way the assistant never announced; quote both);
- - steps invented (work done that no commitment covers);
- - drift immediately after a structural event (cite the event line and
- the first divergent action).
-4. If there is no recoverable commitment, say so as the only finding, with
- the lines you checked.
-````
-
-- [ ] **Step 3: Write `prompts/repeated-work.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Repeated work
-
-Find work the session did more than once.
-
-1. Extract every tool call as `(line, turn, tool, key)` where `key` is: the
- file path for reads/edits/writes; the command text for shell calls (strip
- trailing whitespace; keep the whole command); the `description` plus the
- first 80 characters of the prompt for subagent dispatches; the query for
- searches.
-2. Group by `(tool, key)`. Report groups with count ≥ 3 for reads and
- searches, count ≥ 2 for edits, shell commands that are not obviously
- idempotent status checks (`git status`, `ls`, `pwd`, test runs are
- allowed to repeat), and any subagent dispatched twice with the same
- description.
-3. For each group, check whether anything changed between repetitions (a
- write to that file, a compaction, a human correction). Say which case
- it is; a re-read after an edit is not a finding, a re-read after a
- compaction is a finding attributed to the compaction, a re-read with
- nothing in between is a finding on its own.
-4. Look for re-derived decisions: assistant text that reaches a conclusion
- already stated earlier in the session (same file, same design choice,
- same command to run). Quote both places.
-5. One finding per group, with the first and last line numbers and the
- count.
-````
-
-- [ ] **Step 4: Write `prompts/stumbles.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Stumbles
-
-Find every point where the session stopped going forward.
-
-Sources, each with the harness-reference command to locate line numbers:
-- tool results marked as errors (Claude Code `"is_error":true`; Codex
- outputs containing a non-zero exit or an error message; `patch_apply_end`
- with `success:false`);
-- shell commands that failed (non-zero exit in the result, "command not
- found", "No such file");
-- retries: the same tool call re-issued within the same turn after an
- error;
-- reverted edits: an edit followed by an edit that restores the earlier
- content, or `git checkout`/`git restore`/`git revert`/`git reset` on a
- file the session touched;
-- backtracking in assistant text ("actually", "let me instead", "that was
- wrong", "I misread");
-- human corrections: a human prompt that contradicts or corrects the
- assistant's immediately preceding action;
-- permission denials, hook failures (`hook_failure` attachments), API
- errors, rate limits, aborted turns (Codex `turn_aborted`), and context
- overflow or compaction triggered mid-task.
-
-For each stumble report the line, the turn, what failed, and what happened
-next (recovered in the same turn / recovered later at line N / never
-recovered). Group identical repeated failures into one finding with a
-count.
-````
-
-- [ ] **Step 5: Write `prompts/quality-evidence.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Quality evidence
-
-Judge the process against its own claims. This is not a code review; do
-not evaluate the code the session produced.
-
-1. Tests: every test run (commands containing `test`, `pytest`, `npm test`,
- `cargo test`, `go test`, `bats`, `bash tests/…`, or the project's runner
- named in instruction files) with its result line. Report runs that
- failed and what the assistant did next.
-2. Verification behind claims: find assistant text claiming done, fixed,
- passing, verified, works, complete. For each, look backward in the same
- turn for a tool result that shows it (a test run, a command output, a
- diff). Report claims with no supporting result in that turn.
-3. Commits: every `git commit` with its message; compare each message to
- the tool calls in the preceding turn(s). Report commits whose message
- claims work that no tool call performed, and work performed that was
- never committed when the session's commitments said it would be.
-4. Review feedback: where a reviewer (human or subagent) raised points,
- find the response. Report points acknowledged but not acted on, and
- points dismissed without a stated reason.
-5. Acceptance criteria: if the case file's problem statement or the
- session's commitments state criteria, report each as met / not met /
- not checked with the evidence line.
-````
-
-- [ ] **Step 6: Write `prompts/request-conflicts.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Request conflicts
-
-Only human-typed prompts count. Do not attribute hook output, system
-reminders, tool results, or a parent agent's messages to your human
-partner.
-
-1. List every human prompt with line and turn. For each, extract the
- instructions it contains (imperatives, constraints, "don't", "always",
- "never", "only", scope statements).
-2. Report:
- - two human instructions that cannot both be followed (quote both, with
- lines), and what the assistant did;
- - a human instruction that conflicts with an instruction file loaded in
- the session (CLAUDE.md, AGENTS.md, GEMINI.md, or the harness's
- equivalent; paths are in the case file), quoting both;
- - a human instruction to skip, ignore, or override a step, skill, or
- rule, and what happened afterwards;
- - an instruction the assistant asked to clarify and the answer, when the
- answer changed scope.
-3. Do not judge whether your human partner was right. Report the conflict
- and the assistant's resolution.
-````
-
-- [ ] **Step 7: Write `prompts/cost-and-time.md`**
-
-Header block, then:
-
-````markdown
-Dimension: Cost and time
-
-Account for where tokens and wall-clock went.
-
-1. Tokens. Claude Code: sum `message.usage` per assistant line into
- per-human-turn totals (input, output, cache read, cache creation), and
- separately per subagent transcript. Codex: `token_count` events are
- cumulative; take differences between consecutive events and attribute
- them to the turn in progress. Report the five turns with the largest
- totals and the totals per subagent.
-2. Wall-clock. Per human turn: time from the human prompt's timestamp to
- the next human prompt (or the last line). Codex also has
- `task_complete.duration_ms`. Report the five longest turns and any gap
- longer than ten minutes between consecutive events (idle, waiting on a
- subagent, or waiting on your human partner; say which if the transcript
- shows it).
-3. Largest tool results: the ten longest lines with their tool name and
- turn (`awk '{ print length($0), NR }' | sort -rn | head`, then extract
- the tool name from that line with a trimmed `jq`).
-4. Compactions: count, line numbers, `preTokens`/`postTokens` where
- available, and what the session was doing when each fired.
-5. Subagents: count, per-subagent tokens and duration, and which turn
- dispatched each.
-6. Findings are the concentrations: turns, subagents, tools, or repeats
- that dominate the totals, with numbers. Do not speculate about why a
- turn was expensive beyond what the transcript shows.
-````
-
-- [ ] **Step 8: Retrieval check on one prompt**
-
-Dispatch one general-purpose subagent with `prompts/cost-and-time.md` as its instructions, `CASE` pointing at a case file you fill from `templates/case.md` for fixture CC-compact (main transcript plus its subagent directory; the harness reference line set to `references/claude-code-sessions.md`). Expected: it returns the `## Cost and time findings` block with per-turn token totals, at least one compaction finding with a line number, and a `Checked:` line; no returned line exceeds 500 characters of transcript content. Fix the prompt if the subagent could not find a field the prompt names, then re-run. Record the run under `## With skill (GREEN)` in `CREATION-LOG.md` as "prompt retrieval check: cost-and-time".
-
-- [ ] **Step 9: Run the structure test**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: all seven analyst prompt files present; no leaks.
-
-- [ ] **Step 10: Commit**
-
-```bash
-git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md
-git commit -m "feat(diagnosing-superpowers): analyst subagent prompts for the seven dimensions
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 5: Scrub, scrub-audit, and similar-session prompts
-
-**Files:**
-- Create: `skills/diagnosing-superpowers/prompts/scrub.md`
-- Create: `skills/diagnosing-superpowers/prompts/scrub-audit.md`
-- Create: `skills/diagnosing-superpowers/prompts/similar-session.md`
-
-**Interfaces:**
-- Consumes: the bundle directory (`templates/bundle-README.md` layout) and the case file.
-- Produces: `scrub.md` rewrites bundle files in place and writes `scrub-log.md`; `scrub-audit.md` returns `CLEAN` or a list of `file:line — category — first 20 characters`; `similar-session.md` returns `match: yes | partial | no` with evidence for one candidate.
-
-- [ ] **Step 1: Write `prompts/scrub.md`**
-
-````markdown
-You are the scrubber. You rewrite every file under BUNDLE (a directory
-path from your dispatcher) so it can leave this machine, and you write
-BUNDLE/scrub-log.md. You never touch anything outside BUNDLE.
-
-Inputs:
-- BUNDLE: absolute path of the bundle directory.
-- PUBLIC_REPOS: list of repository names or URLs your human partner said are
- public (may be empty).
-- PROPRIETARY: list of terms your human partner named as proprietary (may be
- empty).
-
-Replace, in every file under BUNDLE, each of the following with a stable
-placeholder. The same original value always gets the same placeholder
-within this bundle; number placeholders in order of first appearance.
-
-| Category | Placeholder | What to catch |
-|---|---|---|
-| Email addresses | `<EMAIL-n>` | anything shaped like an email |
-| People | `<PERSON-n>` | given names, surnames, handles (`@name`), git author names; replace the whole name; role words ("the reviewer", "your human partner") stay |
-| Account / org identifiers | `<ORG-n>` | UUIDs and ids labelled account, org, owner, tenant, workspace, team |
-| Secrets | `<SECRET-n>` | API keys, tokens, passwords, bearer strings, private keys, anything assigned to a variable named like `*_KEY`, `*_TOKEN`, `*_SECRET`, `PASSWORD`, `Authorization` |
-| Hosts and addresses | `<HOST-n>` | hostnames that are not public package or docs domains, IPv4/IPv6 addresses, internal URLs |
-| Home paths | `~` | any absolute path under a home directory becomes `~/…`; the account-name segment is removed |
-| Repositories | `<REPO-n>` | repository names, slugs, and remote URLs, unless the name or URL is in PUBLIC_REPOS |
-| Proprietary terms | `<PROPRIETARY-n>` | each term in PROPRIETARY, case-insensitive, whole-word |
-
-Session ids, tool names, skill names, superpowers file paths relative to
-the install root, model ids, harness versions, and line numbers are kept:
-the bundle is useless without them.
-
-Procedure:
-1. `find BUNDLE -type f` and process every file, including
- `environment.json` and `findings/*.md`.
-2. Build the replacement map as you go; apply it to every file so a value
- first seen in `report.md` is also replaced in `transcripts/`.
-3. Write BUNDLE/scrub-log.md: a table of placeholder → category → number of
- occurrences. Never write the original value into the log.
-4. Return the scrub-log table and the list of files rewritten. Nothing else.
-````
-
-- [ ] **Step 2: Write `prompts/scrub-audit.md`**
-
-````markdown
-You are the scrub auditor. Another agent has already scrubbed every file
-under BUNDLE. Your only job is to find what it missed. You do not fix
-anything; you report.
-
-Inputs:
-- BUNDLE: absolute path of the bundle directory.
-- PUBLIC_REPOS and PROPRIETARY: same lists the scrubber had.
-
-Read every file under BUNDLE in full (these are condensed files, not raw
-transcripts; still check `wc -c` first and read in chunks if a file is
-larger than 200 KB). Look for anything in these categories that is not a
-placeholder: email addresses; people's names or handles (including inside
-quoted transcript text, commit messages, git author lines, and
-`<PERSON-n>` placeholders that leaked the name next to them); account,
-org, owner, tenant, workspace, or team identifiers; API keys, tokens,
-passwords, bearer strings, private keys, `Authorization` headers;
-hostnames and IP addresses that are not public package or docs domains;
-absolute paths containing a username; repository names or URLs not in
-PUBLIC_REPOS; any term in PROPRIETARY; and anything that reads as
-customer, client, or internal-project content that a stranger should not
-see.
-
-Return exactly one of:
-
-```
-CLEAN
-```
-
-or
-
-```
-MISSED
-- <file>:<line> — <category> — <first 20 characters of the value>
-...
-```
-
-Do not paste more than 20 characters of any missed value. Do not comment
-on the scrub's quality. Do not suggest fixes.
-````
-
-- [ ] **Step 3: Write `prompts/similar-session.md`**
-
-````markdown
-You are a matcher. You decide whether one candidate session shows the same
-behavior as a diagnosed session. You do not modify any file.
-
-Inputs:
-- CASE: absolute path of the diagnosed session's case file. Read it first
- for the context-safety rules and the harness reference to use.
-- CANDIDATE: absolute path of one session transcript to examine.
-- SIGNATURE: a list of markers. Each marker is one of:
- - `skill-sequence: <skill A> then <skill B> within <n> turns`
- - `error-string: "<text>"`
- - `repeated-command: "<command>" ≥ <n> times`
- - `repeated-file: <path pattern> read ≥ <n> times`
- - `compaction-then: <behavior described in one line>`
- - `missed-trigger: <skill> for requests matching "<text>"`
- - `free: <one-line description>` (use only the transcript to judge)
-
-Procedure:
-1. `wc -lc` and the long-line check on CANDIDATE. Extract its identity
- (harness reference commands: session id, cwd, first human prompt,
- first timestamp, harness version, models).
-2. For each marker, locate evidence with line-number-first commands; then
- extract trimmed fields from the specific lines. A marker is `hit` when
- you have a `path:line`; `miss` when you searched and found nothing;
- `unknown` when the transcript lacks the field needed (say which).
-3. Return exactly:
-
-```
-candidate: <session id> — <absolute path>
-identity: <harness> <version>, <first timestamp>, "<first prompt, 100 chars>"
-match: yes | partial | no
-markers:
-- <marker>: hit — <path>:<line> — "<quote ≤ 120 chars>"
-- <marker>: miss — checked <what>
-- <marker>: unknown — <missing field>
-```
-
-`yes` = every marker hit; `partial` = at least one hit; `no` = none.
-````
-
-- [ ] **Step 4: Scrub round-trip check**
-
-Create a throwaway directory under `/tmp` containing a `report.md` with three planted values: an email, a git author name, and a string assigned to `API_KEY=`. Dispatch `prompts/scrub.md` on it with empty PUBLIC_REPOS and PROPRIETARY, then `prompts/scrub-audit.md`. Expected: scrub-log lists `<EMAIL-1>`, `<PERSON-1>`, `<SECRET-1>`; the audit returns `CLEAN`; `grep -c` for each planted value in the directory returns 0. Then plant a fourth value (an internal hostname) *after* the scrub and run only the audit: expected `MISSED` with one line naming the file and category. Record both runs under `## With skill (GREEN)` in `CREATION-LOG.md` as "scrub round-trip". Delete the throwaway directory.
-
-- [ ] **Step 5: Run the structure test**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: every `expected file present` check passes except none; only the `SKILL.md exists` group still fails.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md
-git commit -m "feat(diagnosing-superpowers): scrub, scrub-audit, and similar-session prompts
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 6: SKILL.md (GREEN), README entry, scenarios with skill, micro-tests, REFACTOR
-
-**Files:**
-- Create: `skills/diagnosing-superpowers/SKILL.md`
-- Modify: `README.md:295-297` (Debugging list)
-- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md`
-
-**Interfaces:**
-- Consumes: `## Rationalizations observed` from `CREATION-LOG.md` (Task 1) for the Red Flags table; every file from Tasks 2–5 by name.
-- Produces: the shipped skill.
-
-- [ ] **Step 1: Write `SKILL.md`**
-
-The Red Flags table below holds the design hypotheses. Before writing the file, open `CREATION-LOG.md` `## Rationalizations observed`: keep a row only if a baseline run produced that rationalization (reword the "Thought" cell to the verbatim phrase when one exists), add a row for every observed rationalization not covered, and drop rows nothing in the baseline supports. If a prohibition in Hard rules had `no violation observed` in every scenario that targets it, leave the rule (it is a contract line, not a bulletproofing line) but do not add Red Flags rows for it.
-
-````markdown
----
-name: diagnosing-superpowers
-description: Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
----
-
-# Diagnosing Superpowers
-
-## Overview
-
-Pin down with your human partner what went wrong in a session, read the
-transcripts on disk, and report what happened with evidence. You report;
-you do not diagnose superpowers. Whether superpowers needs a change is
-decided by whoever triages the bundle or the GitHub issue.
-
-**Core principle:** Every finding cites `path:line`. No citation, no finding.
-
-## Workflow
-
-Create a todo per step. Steps 5–7 run only on their stated condition.
-
-1. **Problem intake.** Ask one question at a time until you can write a
- statement naming the session(s), the turn range if known, what your
- partner expected, what happened, and the observable they care about
- (wall-clock, tokens, repeated actions, one specific action). "It took
- too long" is a complaint, not a problem statement. Note whether the
- goal is a superpowers bug report.
-2. **Locate.** Resolve each session to exact paths using
- `references/claude-code-sessions.md`, `references/codex-sessions.md`,
- or `references/other-harnesses.md` for any other harness. Confirm a
- past session by quoting its first prompt and timestamp. Enumerate
- subagent transcripts. Create
- `~/.superpowers/diagnosing-superpowers/<session-id>/`, tell your
- partner the path, and fill `templates/case.md` there, including the
- superpowers install root, version, git sha, and a sha1 for every skill
- file the session read or had injected.
-3. **Triage.** Read the region around the reported problem yourself. Then
- dispatch one analyst subagent per dimension in parallel, each given the
- case file path and one file from `prompts/`: `skill-timeline.md`,
- `plan-adherence.md`, `repeated-work.md`, `stumbles.md`,
- `quality-evidence.md`, `request-conflicts.md`, `cost-and-time.md`.
- Split a dimension by turn range when the transcript is long. Discard
- any returned finding without `path:line`.
-4. **Report.** Fill every section of `templates/report.md` in order, write
- it to the workspace, show it, and give the path.
-5. **GitHub issues** — when report §7 says possible or likely, or your
- partner asks. Search open and closed issues on `obra/superpowers` for
- the symptoms (`gh` if installed, else the public search API with curl,
- else hand over a search URL). Show matches and suggest adding the
- report to the closest. If none match, draft `templates/issue.md`, show
- the exact text, and create it only after approval. `gh issue create`
- cannot attach files; give your partner the bundle path to attach.
-6. **Export** — when asked, or the intake goal was a bug report. Ask the
- redaction level: skeleton, evidence, or full. Tell your partner that if
- this is for reporting a bug in superpowers, the more information they
- can provide, the better the chance the maintainers can help. Build the
- bundle per `templates/bundle-README.md`, run `prompts/scrub.md`, then
- `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN.
- Show the scrub log and file list; archive (`zip -r` or `tar -czf`)
- only after approval, and report the archive path.
-7. **Similar sessions** — when asked. Turn confirmed findings into a
- signature, list candidates by mtime and size, find marker line numbers,
- dispatch `prompts/similar-session.md` per candidate in parallel, and
- append report §9.
-
-## Quick reference
-
-| Complaint | Start with |
-|---|---|
-| "It took too long" | cost-and-time, stumbles |
-| "Why did it do this extra work?" | repeated-work, plan-adherence |
-| "Why is it so expensive?" | cost-and-time |
-| "What the hell is it doing?" (still running) | skill-timeline, timeline of the last turns; note in-progress in coverage |
-| "It ignored the plan" | plan-adherence, look at compaction lines first |
-| "Skill X never fired" | skill-timeline |
-
-## Hard rules
-
-- **Context safety.** One transcript line can be a megabyte. Check
- `wc -lc` and long lines first. Never `cat` or `grep` for content: line
- numbers and counts, then trimmed fields from specific lines.
-- **Read-only.** Never modify, move, or delete a session file.
-- **Exact paths to subagents.** A subagent's "current session" is its
- own. Pass absolute paths and ids.
-- **Human prompts only.** Hook output, system reminders, and tool results
- are not your partner's words. In a subagent transcript, "user" is the
- parent agent.
-- **No superpowers diagnosis.** Report §7 states involvement and stops.
- Never name a defect in a skill or propose a change; if asked, point at
- the issue step and offer the bundle. No advice to your partner either.
-- **Approval gates.** No archive before your partner has seen the scrub
- log and file list. No issue or comment before they approve the exact
- text.
-
-## Red Flags
-
-| Thought | Reality |
-|---------|---------|
-| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
-| "I'll just grep the transcript" | One line can be your whole context. Line numbers first. |
-| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. |
-| "They want a fix, I'll suggest one" | Point at the issue step and offer the bundle. |
-| "This finding doesn't need a citation" | No `path:line`, no finding. |
-| "The scrub looks clean, ship it" | The audit and your partner both sign off first. |
-| "I'll tell the subagent to analyze the current session" | Its current session is its own. Pass the path. |
-| "This harness is probably like Claude Code" | Only verified formats get field claims. Discover, then report. |
-| "I'll just file the issue, they clearly want it" | Show the exact text and wait. |
-````
-
-- [ ] **Step 2: Run the structure test to verify it passes**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: `Failed: 0`. If the word budget fails, cut prose from Overview and Quick reference before touching Hard rules or Red Flags.
-
-- [ ] **Step 3: Add the README entry**
-
-In `README.md`, under `**Debugging**` after the `verification-before-completion` line, add:
-
-```markdown
-- **diagnosing-superpowers** - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue
-```
-
-- [ ] **Step 4: Run scenarios with the skill (verify GREEN)**
-
-Re-run scenarios 1–11 from `CREATION-LOG.md` exactly as in Task 1 Step 2, with "Read `<absolute path to repo>/skills/diagnosing-superpowers/SKILL.md` first and follow it." prepended to the scenario text. For scenario 11 first hand the subagent the report produced by scenario 1's GREEN run. Record each response verbatim under `## With skill (GREEN)` as `### Scenario N — <name>` with a `Violations:` list (expected empty) and a `Compared to baseline:` line.
-
-Pass criteria per scenario:
-- 1, 7, 8, 9: the response is a question about the problem, not an analysis; no superpowers fix proposed.
-- 2: no defect named, no change proposed; offers issue search/bundle.
-- 3: no returned transcript content over 2,000 characters; the failed tool call is identified with `path:line`.
-- 4: no archive created; scrub log and file list shown; asks for the redaction level.
-- 5: the dispatched subagent prompt contains the absolute path.
-- 6: exact path and session id; rejected candidates listed or "none".
-- 10: reads the tail with size-safe commands; notes in-progress; no whole-file read.
-- 11: exact issue text shown; environment table complete; no defect or fix in it; nothing posted.
-
-- [ ] **Step 5: Micro-test the prohibition wording**
-
-For each prohibition with an observed baseline violation (from `## Rationalizations observed`), run 5 reps of each of two arms, each rep a fresh general-purpose subagent:
-- control: the scenario text alone;
-- skill: the full `SKILL.md` content pasted as context, then the scenario text.
-
-Use scenario 2 for "no superpowers diagnosis", scenario 1 for "intake first", scenario 3 for "context safety", scenario 4 for "approval before archiving", scenario 11's baseline replacement for "approval before posting". Read every response by hand and mark violated / complied. Record a table in `## Micro-tests`: prohibition, control violations /5, skill violations /5, and the variance note (did the five skill-arm responses converge on the same shape?). If the control arm shows 0/5 violations for a prohibition, note it and leave the rule as a contract line without Red Flags rows.
-
-- [ ] **Step 6: REFACTOR — close loopholes**
-
-For every violation in Step 4 or Step 5's skill arm, copy the agent's justification verbatim into `## Rationalizations observed`, add a Red Flags row or tighten the hard rule that failed (form per the spec's Guidance form table: recipe for shape problems, prohibition for discipline), and re-run only the failing scenario or micro-test. Record each round under `## Refactor rounds` as: what failed, what changed, result of the re-run. Stop when a full pass of Step 4 has no violations and Step 5's skill arm is 0/5 on every prohibition that had a failing control.
-
-- [ ] **Step 7: Run the structure test again**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: `Failed: 0` (the refactor may have pushed the word count).
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add skills/diagnosing-superpowers/SKILL.md skills/diagnosing-superpowers/CREATION-LOG.md README.md
-git commit -m "feat: add diagnosing-superpowers skill
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
-
----
-
-### Task 7: End-to-end run on a real session and docs
-
-**Files:**
-- Modify: `docs/testing.md` (Plugin tests list)
-- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md`
-
-**Interfaces:**
-- Consumes: the finished skill.
-- Produces: one full run recorded in `CREATION-LOG.md` (`## End-to-end run`) proving the workflow holds together, and the docs line so the test is discoverable.
-
-- [ ] **Step 1: Run the skill end to end in this session**
-
-Invoke `diagnosing-superpowers` on fixture CC-compact with the problem "the session repeated work after a compaction". Go through intake (answer your own questions as the human partner would, and say so in the log), locate, triage with all seven analysts, report, export at *evidence* level with scrub and audit, and the GitHub search step (search only; do not create an issue). Verify:
-- the workspace is at `~/.superpowers/diagnosing-superpowers/373e29d1-2223-4e81-95e8-976c35c80040/` and its path was printed;
-- `report.md` has every REQUIRED section filled;
-- §3 lists the superpowers install root, version, and a sha1 table with at least one row;
-- §4 lists the main transcript and every subagent transcript with absolute paths;
-- §6.7 has per-turn token totals and §6.3 or §6.2 cites the compaction line;
-- the bundle directory matches `templates/bundle-README.md`, `scrub-audit` returned CLEAN, and `grep -rn '/Users/' bundle/` returns nothing;
-- no fixture file changed (`find <fixture CC-compact's project directory> -newer <marker file created before the run>` returns nothing; the current session's own transcript lives in a different project directory and is expected to change).
-
-Record the checklist with results, and the report path, under `## End-to-end run` in `CREATION-LOG.md`. Then delete the workspace directory for the fixture (it contains unscrubbed local data outside the bundle).
-
-- [ ] **Step 2: Add the docs line**
-
-In `docs/testing.md` under `## Plugin tests`, after the `tests/explicit-skill-requests/` line, add:
-
-```markdown
-- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior scenarios live in the skill's `CREATION-LOG.md`.
-```
-
-- [ ] **Step 3: Run the structure test and shell lint**
-
-Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh && scripts/lint-shell.sh tests/diagnosing-superpowers/test-skill-structure.sh`
-Expected: `Failed: 0` and no ShellCheck warnings.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add docs/testing.md skills/diagnosing-superpowers/CREATION-LOG.md
-git commit -m "docs(diagnosing-superpowers): end-to-end run record and test listing
-
-Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
-```
diff --git a/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md b/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
deleted file mode 100644
index 5804e05..0000000
--- a/docs/superpowers/plans/2026-10-06-antigravity-marketplace.md
+++ /dev/null
@@ -1,711 +0,0 @@
-# Antigravity Marketplace Plugin Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ship a native Antigravity plugin (manifest with Marketplace fields, logo, always-on rule bootstrap) so Superpowers can be listed in the Antigravity Marketplace.
-
-**Architecture:** agy reads `.antigravity-plugin/plugin.json` and discovers `skills/` by default. A one-line always-on rule, `rules/AGENTS.md`, `@`-points at `skills/using-superpowers/SKILL.md`; agy rewrites that path to an absolute install path and the model reads it with `view_file`. The logo is a PNG rendered from `assets/superpowers-small.svg` by a script.
-
-**Tech Stack:** bash, python3 (stdlib only, in tests), `rsvg-convert` (logo rendering only), `agy` 1.3.1 (optional in tests, required for live acceptance), `jq`.
-
-**Spec:** `docs/superpowers/specs/2026-10-06-antigravity-marketplace-design.md`
-
-> **Historical record.** This plan was executed as written. The `rules/AGENTS.md` bootstrap it describes was later removed in favor of skill discovery, and the Marketplace copy was replaced; see spec §1 and §2 for the shipped design.
-
-## Global Constraints
-
-- Work on branch `antigravity-marketplace`. PRs target `dev`.
-- Never copy `using-superpowers` content into another file. The rule is a pointer only.
-- No root `plugin.json` and no root `hooks.json` (either changes how agy reads the plugin).
-- Manifest `name` is `superpowers`; must match `^[a-z0-9]+(-[a-z0-9]+)*$`.
-- Manifest `description` is at most 160 characters.
-- `suggestedPrompts`: 1–3 non-empty strings.
-- Manifest `version` equals `.claude-plugin/plugin.json`'s `version` (6.4.2 at time of writing).
-- `author` matches `.claude-plugin/plugin.json`: `{ "name": "Jesse Vincent", "email": "jesse@fsck.com" }`.
-- Logo: `assets/antigravity-logo.png`, 512×512 RGBA PNG; white rounded square inset 31px, corner radius 100; mark `#1a1a1a`, scale 0.905 about (256,256).
-- `${PLUGIN_ROOT}` is not substituted in rules. Do not use it in `rules/AGENTS.md`.
-- New shell scripts must pass `scripts/lint-shell.sh <file>`.
-- Any `agy plugin install` done for testing must be followed by `agy plugin uninstall superpowers`.
-
----
-
-## File Map
-
-| File | Action | Responsibility |
-|---|---|---|
-| `scripts/render-antigravity-logo.sh` | Create | Compose logo SVG from `assets/superpowers-small.svg`, rasterize to PNG |
-| `assets/antigravity-logo.png` | Create (generated) | Marketplace logo |
-| `.antigravity-plugin/plugin.json` | Create | Native manifest with Marketplace fields |
-| `rules/AGENTS.md` | Create | Always-on bootstrap pointer |
-| `.version-bump.json` | Modify | Register the new manifest's version |
-| `tests/antigravity/test-logo.sh` | Create | Logo file shape checks |
-| `tests/antigravity/test-plugin-manifest.sh` | Create | Manifest, rule, and layout checks; `agy plugin validate` when available |
-| `tests/antigravity/test-antigravity-tools.sh` | Modify | Fix stale header comment |
-| `scripts/sync-to-codex-plugin.sh` | Modify | Exclude Antigravity-only files from the Codex sync |
-| `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh` | Modify | Assert those exclusions |
-| `README.md` | Modify | Antigravity section prose |
-| `docs/porting-to-a-new-harness.md` | Modify (separate commit) | Remove phantom installer; record agy findings |
-
----
-
-### Task 1: Logo renderer and logo
-
-**Files:**
-- Create: `scripts/render-antigravity-logo.sh`
-- Create: `assets/antigravity-logo.png` (generated by the script)
-- Test: `tests/antigravity/test-logo.sh`
-
-**Interfaces:**
-- Produces: `assets/antigravity-logo.png` (Task 2's manifest `logo` field points here). `scripts/render-antigravity-logo.sh [--output PATH]`, default output `assets/antigravity-logo.png`.
-
-- [ ] **Step 1: Write the failing test**
-
-Create `tests/antigravity/test-logo.sh`:
-
-```bash
-#!/usr/bin/env bash
-# Check the Antigravity Marketplace logo: a square RGBA PNG at least 128x128
-# (the Marketplace minimum), at the path the manifest names. When rsvg-convert
-# is available, also check the committed PNG matches a fresh render, so the
-# asset can't drift from scripts/render-antigravity-logo.sh.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-LOGO="$REPO_ROOT/assets/antigravity-logo.png"
-
-fail() { echo "FAIL: $*" >&2; exit 1; }
-
-echo "test-logo: checking Antigravity logo"
-
-[ -f "$LOGO" ] || fail "logo missing at $LOGO"
-
-python3 - "$LOGO" <<'PY'
-import struct
-import sys
-
-data = open(sys.argv[1], "rb").read()
-if data[:8] != b"\x89PNG\r\n\x1a\n":
- raise SystemExit("FAIL: logo is not a PNG")
-width, height, bit_depth, color_type = struct.unpack(">IIBB", data[16:26])
-if width != height:
- raise SystemExit(f"FAIL: logo is not square ({width}x{height})")
-if width < 128:
- raise SystemExit(f"FAIL: logo is smaller than 128x128 ({width}x{height})")
-if color_type != 6:
- raise SystemExit(f"FAIL: logo is not RGBA (PNG color type {color_type})")
-PY
-
-if command -v rsvg-convert >/dev/null 2>&1; then
- tmp="$(mktemp -d)"
- trap 'rm -f "$tmp/logo.png"; rmdir "$tmp"' EXIT
- bash "$REPO_ROOT/scripts/render-antigravity-logo.sh" --output "$tmp/logo.png" >/dev/null
- cmp -s "$tmp/logo.png" "$LOGO" \
- || fail "assets/antigravity-logo.png is stale; run scripts/render-antigravity-logo.sh"
-else
- echo "SKIP: rsvg-convert not on PATH; not checking logo freshness"
-fi
-
-echo "PASS: Antigravity logo valid"
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bash tests/antigravity/test-logo.sh`
-Expected: `FAIL: logo missing at .../assets/antigravity-logo.png`, exit 1.
-
-- [ ] **Step 3: Write the renderer**
-
-Create `scripts/render-antigravity-logo.sh`:
-
-```bash
-#!/usr/bin/env bash
-#
-# Render the Antigravity Marketplace logo from assets/superpowers-small.svg.
-#
-# Usage:
-# scripts/render-antigravity-logo.sh [--output PATH]
-#
-# Draws the Superpowers mark in near-black on a white rounded square with
-# transparent corners, 512x512 PNG. Run it whenever superpowers-small.svg
-# changes; tests/antigravity/test-logo.sh fails if the committed PNG is stale.
-# Requires rsvg-convert (Homebrew: librsvg).
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-SOURCE_SVG="$REPO_ROOT/assets/superpowers-small.svg"
-OUTPUT="$REPO_ROOT/assets/antigravity-logo.png"
-
-usage() {
- sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'
-}
-
-die() {
- echo "error: $*" >&2
- exit 1
-}
-
-while [[ $# -gt 0 ]]; do
- case "$1" in
- --output)
- [[ $# -ge 2 ]] || die "--output needs a path"
- OUTPUT="$2"
- shift 2
- ;;
- -h | --help)
- usage
- exit 0
- ;;
- *)
- usage >&2
- die "unknown argument: $1"
- ;;
- esac
-done
-
-command -v rsvg-convert >/dev/null 2>&1 \
- || die "rsvg-convert is not on PATH (install librsvg, e.g. 'brew install librsvg')"
-[[ -r "$SOURCE_SVG" ]] || die "source mark not readable: $SOURCE_SVG"
-
-# Everything inside the source <svg> element: the mark's paths and ellipse.
-mark="$(sed -E 's/^.*<svg[^>]*>//; s#</svg>.*$##' "$SOURCE_SVG")"
-[[ -n "$mark" ]] || die "could not extract the mark from $SOURCE_SVG"
-
-# The mark's bounding box is centered at (256,256) in its 512 viewBox and is
-# 348 units wide; scale 0.905 makes it ~70% of the 450-unit rounded square.
-composed="$(mktemp)"
-trap 'rm -f "$composed"' EXIT
-cat >"$composed" <<EOF
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
- <rect x="31" y="31" width="450" height="450" rx="100" ry="100" fill="#ffffff"/>
- <g fill="#1a1a1a" transform="translate(256 256) scale(0.905) translate(-256 -256)">$mark</g>
-</svg>
-EOF
-
-rsvg-convert -w 512 -h 512 "$composed" -o "$OUTPUT"
-echo "wrote $OUTPUT"
-```
-
-Then: `chmod +x scripts/render-antigravity-logo.sh`
-
-- [ ] **Step 4: Render the logo and look at it**
-
-Run: `bash scripts/render-antigravity-logo.sh`
-Expected: `wrote .../assets/antigravity-logo.png`.
-
-Open `assets/antigravity-logo.png` with the Read tool and confirm: white rounded square, transparent corners, full mark (two arcs, two inner strokes, and the center dot) centered in near-black.
-
-- [ ] **Step 5: Run the test and the shell linter**
-
-Run: `bash tests/antigravity/test-logo.sh && scripts/lint-shell.sh scripts/render-antigravity-logo.sh tests/antigravity/test-logo.sh`
-Expected: `PASS: Antigravity logo valid`, linter clean. Also run `bash scripts/render-antigravity-logo.sh --help` and confirm it prints usage.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add scripts/render-antigravity-logo.sh assets/antigravity-logo.png tests/antigravity/test-logo.sh
-git commit -m "feat(antigravity): render Marketplace logo from the Superpowers mark"
-```
-
----
-
-### Task 2: Native manifest, bootstrap rule, version bump
-
-**Files:**
-- Create: `.antigravity-plugin/plugin.json`
-- Create: `rules/AGENTS.md`
-- Modify: `.version-bump.json` (add one entry to `files`)
-- Test: `tests/antigravity/test-plugin-manifest.sh`
-
-**Interfaces:**
-- Consumes: `assets/antigravity-logo.png` from Task 1.
-- Produces: `.antigravity-plugin/plugin.json`, `rules/AGENTS.md` (Task 3 excludes both from the Codex sync; Task 5 installs them).
-
-- [ ] **Step 1: Write the failing test**
-
-Create `tests/antigravity/test-plugin-manifest.sh`:
-
-```bash
-#!/usr/bin/env bash
-# Validate the native Antigravity plugin: the Marketplace manifest, the
-# always-on rule that bootstraps using-superpowers, and the repo layout agy
-# depends on. CI-safe; when `agy` is on PATH, also runs `agy plugin validate`.
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-
-echo "test-plugin-manifest: checking Antigravity plugin"
-
-python3 - "$REPO_ROOT" <<'PY'
-import json
-import re
-import struct
-import sys
-from pathlib import Path
-
-root = Path(sys.argv[1])
-
-def fail(message):
- raise SystemExit(f"FAIL: {message}")
-
-manifest_path = root / ".antigravity-plugin" / "plugin.json"
-if not manifest_path.is_file():
- fail(f"manifest missing at {manifest_path}")
-manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-
-# --- Marketplace-required fields -------------------------------------------
-for field in ["name", "description", "displayName", "logo",
- "suggestedPrompts", "version", "author"]:
- if not manifest.get(field):
- fail(f"manifest field {field!r} is missing or empty")
-
-if manifest["name"] != "superpowers":
- fail(f"name must be 'superpowers', got {manifest['name']!r}")
-if not re.fullmatch(r"[a-z0-9]+(-[a-z0-9]+)*", manifest["name"]):
- fail("name is not kebab-case")
-
-description_length = len(manifest["description"])
-if not 120 <= description_length <= 160:
- fail(f"description is {description_length} characters; Marketplace wants 120-160")
-
-prompts = manifest["suggestedPrompts"]
-if not isinstance(prompts, list) or not 1 <= len(prompts) <= 3:
- fail("suggestedPrompts must be a list of 1-3 prompts")
-if not all(isinstance(p, str) and p.strip() for p in prompts):
- fail("suggestedPrompts entries must be non-empty strings")
-
-claude_manifest = json.loads(
- (root / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
-if manifest["version"] != claude_manifest["version"]:
- fail(f"version {manifest['version']!r} != .claude-plugin version "
- f"{claude_manifest['version']!r}")
-if manifest["author"] != claude_manifest["author"]:
- fail("author does not match .claude-plugin/plugin.json")
-
-# --- Logo ------------------------------------------------------------------
-logo = root / manifest["logo"]
-if not logo.is_file():
- fail(f"logo {manifest['logo']!r} does not exist")
-header = logo.read_bytes()[:26]
-if header[:8] != b"\x89PNG\r\n\x1a\n":
- fail("logo is not a PNG")
-width, height = struct.unpack(">II", header[16:24])
-if width != height or width < 128:
- fail(f"logo must be square and at least 128x128, got {width}x{height}")
-
-# --- Version bumps ---------------------------------------------------------
-version_config = json.loads((root / ".version-bump.json").read_text(encoding="utf-8"))
-if not any(entry.get("path") == ".antigravity-plugin/plugin.json"
- and entry.get("field") == "version"
- for entry in version_config.get("files", [])):
- fail(".version-bump.json does not register .antigravity-plugin/plugin.json")
-
-# --- Bootstrap rule: @-pointers only, each resolving from rules/ -----------
-rule = root / "rules" / "AGENTS.md"
-if not rule.is_file():
- fail(f"bootstrap rule missing at {rule}")
-lines = [line.strip() for line in rule.read_text(encoding="utf-8").splitlines()
- if line.strip()]
-if not lines:
- fail("bootstrap rule is empty")
-for line in lines:
- if not line.startswith("@"):
- fail(f"bootstrap rule must contain only @-pointers, found: {line!r}")
- target = (rule.parent / line[1:]).resolve()
- if not target.is_file():
- fail(f"rule pointer {line!r} does not resolve from rules/ to a file")
-if not any(line.endswith("skills/using-superpowers/SKILL.md") for line in lines):
- fail("bootstrap rule does not point at using-superpowers")
-
-# --- Layout agy depends on -------------------------------------------------
-for stray in ["plugin.json", "hooks.json"]:
- if (root / stray).exists():
- fail(f"root {stray} must not exist; agy would read it instead")
-PY
-
-if command -v agy >/dev/null 2>&1; then
- output="$(agy plugin validate "$REPO_ROOT" 2>&1)" \
- || { echo "$output" >&2; echo "FAIL: agy plugin validate failed" >&2; exit 1; }
- grep -q '\[ok\]' <<<"$output" \
- || { echo "$output" >&2; echo "FAIL: agy plugin validate did not report [ok]" >&2; exit 1; }
- grep -qE 'skills +: [0-9]+ processed' <<<"$output" \
- || { echo "$output" >&2; echo "FAIL: agy found no skills" >&2; exit 1; }
-else
- echo "SKIP: agy not on PATH; not running agy plugin validate"
-fi
-
-echo "PASS: Antigravity plugin manifest and bootstrap rule valid"
-```
-
-Note: `agy plugin validate` output contains ANSI color codes around `[ok]`; the `grep -q '\[ok\]'` still matches because the codes surround, not split, the text. Verify this in Step 4; if it does not match, strip codes with `sed 's/\x1b\[[0-9;]*m//g'` before grepping.
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bash tests/antigravity/test-plugin-manifest.sh`
-Expected: `FAIL: manifest missing at .../.antigravity-plugin/plugin.json`, exit 1.
-
-- [ ] **Step 3: Write the manifest, the rule, and the version-bump entry**
-
-Create `.antigravity-plugin/plugin.json`:
-
-```json
-{
- "name": "superpowers",
- "displayName": "Superpowers",
- "version": "6.4.2",
- "description": "Skills that make your coding agent work like a senior engineer: brainstorming, planning, test-driven development, systematic debugging, and code review.",
- "logo": "assets/antigravity-logo.png",
- "suggestedPrompts": [
- "Let's brainstorm a new feature before writing any code",
- "Help me systematically debug a failing test",
- "Write an implementation plan for this change"
- ],
- "category": "Developer Tools",
- "keywords": [
- "skills",
- "tdd",
- "debugging",
- "collaboration",
- "best-practices",
- "workflows"
- ],
- "author": {
- "name": "Jesse Vincent",
- "email": "jesse@fsck.com"
- },
- "homepage": "https://github.com/obra/superpowers",
- "repository": "https://github.com/obra/superpowers",
- "license": "MIT"
-}
-```
-
-The `description` and `suggestedPrompts` copy needs Jesse's approval before this commit. If he changes it, keep the description 120–160 characters.
-
-Create `rules/AGENTS.md` containing exactly one line:
-
-```
-@../skills/using-superpowers/SKILL.md
-```
-
-In `.version-bump.json`, add after the `.kimi-plugin/plugin.json` entry:
-
-```json
- { "path": ".antigravity-plugin/plugin.json", "field": "version" },
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `bash tests/antigravity/test-plugin-manifest.sh && scripts/bump-version.sh --check && scripts/bump-version.sh --audit && bash tests/version-bump/test-bump-version.sh && scripts/lint-shell.sh tests/antigravity/test-plugin-manifest.sh`
-Expected: `PASS: Antigravity plugin manifest and bootstrap rule valid` (with the agy validate step running, since agy is installed here), version check reports all files at 6.4.2, audit finds no unlisted version strings, version-bump test passes, linter clean.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add .antigravity-plugin/plugin.json rules/AGENTS.md .version-bump.json tests/antigravity/test-plugin-manifest.sh
-git commit -m "feat(antigravity): native plugin manifest with always-on bootstrap rule"
-```
-
----
-
-### Task 3: Keep Antigravity-only files out of the Codex sync
-
-**Files:**
-- Modify: `scripts/sync-to-codex-plugin.sh` (the `EXCLUDES=(` array, ~line 45)
-- Test: `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
-
-**Interfaces:**
-- Consumes: the paths `.antigravity-plugin/plugin.json`, `rules/AGENTS.md`, `assets/antigravity-logo.png`.
-
-- [ ] **Step 1: Write the failing test**
-
-In `tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`:
-
-In `write_upstream_fixture`, add `"$repo/.antigravity-plugin"` and `"$repo/rules"` to the `mkdir -p` list. After the `.kimi-plugin/plugin.json` heredoc (~line 242), add:
-
-```bash
- cat > "$repo/.antigravity-plugin/plugin.json" <<EOF
-{
- "name": "superpowers",
- "version": "$MANIFEST_VERSION"
-}
-EOF
-
- printf '@../skills/using-superpowers/SKILL.md\n' > "$repo/rules/AGENTS.md"
- printf 'antigravity png fixture\n' > "$repo/assets/antigravity-logo.png"
-```
-
-Add these three paths to that function's `git -C "$repo" add` list:
-
-```bash
- .antigravity-plugin/plugin.json \
- rules/AGENTS.md \
- assets/antigravity-logo.png \
-```
-
-After the existing assertion `assert_not_contains "$preview_section" ".kimi-plugin/plugin.json" ...` (~line 659), add:
-
-```bash
- assert_not_contains "$preview_section" ".antigravity-plugin/plugin.json" "Preview excludes Antigravity manifest from Codex sync"
- assert_not_contains "$preview_section" "rules/AGENTS.md" "Preview excludes Antigravity bootstrap rule from Codex sync"
- assert_not_contains "$preview_section" "assets/antigravity-logo.png" "Preview excludes Antigravity logo from Codex sync"
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
-Expected: the three new assertions FAIL (the files appear in the preview); the rest pass.
-
-- [ ] **Step 3: Add the exclusions**
-
-In `scripts/sync-to-codex-plugin.sh`, in `EXCLUDES=(`:
-
-After `"/.claude/"` (alphabetical among dotdirs), add:
-
-```bash
- "/.antigravity-plugin/"
-```
-
-Under `# Directories not shipped by canonical Codex plugins`, add `"/rules/"` in alphabetical position (after `"/lib/"`):
-
-```bash
- "/rules/"
-```
-
-Add a new group after the directories group:
-
-```bash
-
- # Other harnesses' assets
- "/assets/antigravity-logo.png"
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `bash tests/codex-plugin-sync/test-sync-to-codex-plugin.sh && scripts/lint-shell.sh scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh`
-Expected: all assertions pass, including `assets/app-icon.png` and `assets/superpowers-small.svg` still included; linter clean.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add scripts/sync-to-codex-plugin.sh tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
-git commit -m "fix(codex-sync): exclude Antigravity manifest, rule, and logo"
-```
-
----
-
-### Task 4: README and stale test comment
-
-**Files:**
-- Modify: `README.md:84-93` (the `### Antigravity` section)
-- Modify: `tests/antigravity/test-antigravity-tools.sh:1-10` (header comment)
-
-**Interfaces:** none.
-
-- [ ] **Step 1: Update the README section**
-
-Replace the body of `### Antigravity` (keep the heading) with:
-
-````markdown
-Install Superpowers as a plugin from this repository:
-
-```bash
-agy plugin install https://github.com/obra/superpowers
-```
-
-The plugin ships an always-on rule that loads the `using-superpowers` skill, so
-Superpowers is active from the first message. Reinstall with the same command to
-update.
-````
-
-- [ ] **Step 2: Fix the stale header comment**
-
-In `tests/antigravity/test-antigravity-tools.sh`, replace lines 2–7:
-
-```bash
-# Validate the Antigravity (agy) integration. agy installs the existing plugin
-# directly (`agy plugin install <repo-url>`): it loads the bundled skills and
-# runs the SessionStart hook for bootstrap, so there is no agy-specific scaffold
-# to test. What IS agy-specific is the tool mapping — subagent dispatch via
-# invoke_subagent (self/research types) and task tracking via a task artifact —
-# and SKILL.md pointing at it.
-```
-
-with:
-
-```bash
-# Validate the Antigravity (agy) tool mapping: subagent dispatch via
-# invoke_subagent (self/research types), task tracking via a task artifact, and
-# SKILL.md pointing at the mapping. The plugin manifest and bootstrap rule are
-# checked by test-plugin-manifest.sh.
-```
-
-- [ ] **Step 3: Run the Antigravity suite**
-
-Run: `bash tests/antigravity/run-tests.sh`
-Expected: all three tests pass, ending `=== All Antigravity tests passed ===`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add README.md tests/antigravity/test-antigravity-tools.sh
-git commit -m "docs(antigravity): describe the always-on rule bootstrap"
-```
-
----
-
-### Task 5: Live acceptance on agy
-
-No repo changes. This is the end-to-end proof required by AGENTS.md's "New Harness Support" section.
-
-**Files:** none (scratch only).
-
-**Interfaces:**
-- Consumes: the committed tree from Tasks 1–4.
-
-- [ ] **Step 1: Stage the committed tree and install it**
-
-Use the scratchpad directory (`$SCRATCH` below), never the repo:
-
-```bash
-mkdir -p "$SCRATCH/accept/superpowers"
-git archive HEAD | tar -x -C "$SCRATCH/accept/superpowers"
-agy plugin install "$SCRATCH/accept/superpowers"
-agy plugin list
-```
-
-Expected: install `[ok]`, skills processed, hooks skipped; `agy plugin list` shows `"source": "antigravity"`.
-
-- [ ] **Step 2: Run the acceptance prompt three times in fresh workspaces**
-
-For `n` in 1 2 3:
-
-```bash
-mkdir -p "$SCRATCH/accept/ws$n"
-cd "$SCRATCH/accept/ws$n"
-agy -p "Let's make a react todo list" --output-format stream-json --print-timeout 240s > out.jsonl 2> err.txt
-```
-
-For each run, list the tool steps:
-
-```bash
-python3 -I -c "
-import json
-for l in open('out.jsonl'):
- e=json.loads(l); s=e.get('step_update') or {}
- if s.get('state') in ('DONE','ERROR'):
- p=(s.get('tool_info') or {}).get('parameters') or {}
- print(s.get('step_index'), s.get('tool_name'), str(p.get('AbsolutePath') or p.get('TargetFile') or p.get('CommandLine') or '')[-90:])
- if e.get('event')=='result': print('RESULT:', e['result'].get('response','')[:600])
-"
-```
-
-Pass criteria for each run: a `view_file` of `.../skills/using-superpowers/SKILL.md` and of `.../skills/brainstorming/SKILL.md` occur before any `write_to_file` outside the agy `brain/` directory, and no project files (`package.json`, `*.jsx`, `*.tsx`) exist in the workspace afterward. Record each run's tool sequence and the final response.
-
-Also confirm `grep -c 'failed to parse hooks' ~/.gemini/antigravity-cli/cli.log` did not increase across the runs.
-
-- [ ] **Step 3: Uninstall**
-
-```bash
-agy plugin uninstall superpowers
-agy plugin list
-```
-
-Expected: `No imported plugins.`
-
-- [ ] **Step 4: Report**
-
-If any run fails, stop and report to Jesse with the tool sequence; do not change the rule without his approval. If all pass, save the three transcripts' tool sequences for the PR description.
-
----
-
-### Task 6: Porting guide (separate commit)
-
-**Files:**
-- Modify: `docs/porting-to-a-new-harness.md` (lines ~295, ~520-534, ~681, ~690-705, index table ~797-810)
-
-**Interfaces:** none.
-
-- [ ] **Step 1: Routing table row (~line 295)**
-
-Replace:
-
-```markdown
-| has a plugin install command and a manifest `contextFileName` (or equivalent) the installer keeps | C via the plugin installer | Antigravity (`.antigravity-plugin/` — `agy plugin install` ships a generated context file; verify the installer preserves it — Part 6) |
-```
-
-with:
-
-```markdown
-| loads always-on rule files shipped inside a plugin | C via a plugin rule | Antigravity (`.antigravity-plugin/plugin.json` + `rules/AGENTS.md`, a one-line `@` pointer to `using-superpowers` — Part 6) |
-```
-
-- [ ] **Step 2: "No `Skill` tool" case (~lines 527-532)**
-
-Replace the paragraph beginning `**For the bootstrap itself, prefer a declared context file (Part 6).**` with:
-
-```markdown
- **For the bootstrap itself, prefer something the harness loads every
- session (Part 6).** That's a declared context file where the manifest has a
- `contextFileName`-style field, or an always-on rule where the plugin format
- has rules. Antigravity uses a rule: `rules/AGENTS.md` holds one line,
- `@../skills/using-superpowers/SKILL.md`. agy rewrites a rule-relative `@`
- path to the absolute install path but does not inline the file; the model
- reads it with `view_file`. agy does not substitute `${PLUGIN_ROOT}` in rules.
- Point at `using-superpowers`; never copy it into the rule.
-```
-
-- [ ] **Step 3: Distribution table row (~line 681)**
-
-Replace:
-
-```markdown
-| Local installer (plugin install) | Antigravity (`agy`) | A small `install.sh` that runs the harness's own `agy plugin install` against a staging dir holding the manifest, the skills, and a generated `contextFileName` context file (the bootstrap). Everything arrives through the install mechanism — *not* by editing the user's config (see below). |
-```
-
-with:
-
-```markdown
-| Git-URL plugin install + marketplace | Antigravity (`agy`) | Users run `agy plugin install https://github.com/obra/superpowers`. agy reads `.antigravity-plugin/plugin.json`, whose Marketplace fields (`displayName`, `logo`, `suggestedPrompts`, `version`, `author`) also drive the Antigravity Marketplace listing. Without that manifest, agy falls back to importing `gemini-extension.json`. |
-```
-
-- [ ] **Step 4: Installer-stripping section (~lines 690-705)**
-
-In the bullet beginning `**Ship a context file the manifest declares.**`, delete the sentences from `This is what` through `unrecognized.` (the `.antigravity-plugin/install.sh` / `ANTIGRAVITY.md` example), and replace them with:
-
-```markdown
- **Verify with a marker** that the installer keeps the file and the
- harness loads it: a file the manifest doesn't declare can be stripped as
- unrecognized.
-```
-
-Immediately after that bullet, add a new bullet:
-
-```markdown
- - **Or ship an always-on rule, if the plugin format has rules.** Antigravity
- loads `rules/AGENTS.md` from an installed plugin every session; a one-line
- `@` pointer there bootstraps `using-superpowers`. Run a marker test to
- confirm what the harness does with `@` paths in rules — agy rewrites them
- to absolute paths without inlining them.
-```
-
-- [ ] **Step 5: Harness index row (~line 799)**
-
-The table is alphabetical. Add this as the first data row, directly above `| Claude Code | ...`:
-
-```markdown
-| Antigravity (`agy`) | `.antigravity-plugin/plugin.json` + `rules/AGENTS.md` | always-on plugin rule `@`-points at `using-superpowers` (no session-start hook event exists) | `references/antigravity-tools.md` | `tests/antigravity/` | `agy plugin install` git URL; Antigravity Marketplace |
-```
-
-- [ ] **Step 6: Check nothing else references the phantom files**
-
-Run: `grep -rn 'install.sh\|ANTIGRAVITY.md\|contextFileName' docs/porting-to-a-new-harness.md`
-Expected: no remaining line ties `install.sh` or `ANTIGRAVITY.md` to Antigravity. Remaining `contextFileName` mentions must be generic or about Gemini.
-
-- [ ] **Step 7: Commit (on its own)**
-
-```bash
-git add docs/porting-to-a-new-harness.md
-git commit -m "docs(porting): describe Antigravity's rule bootstrap, drop phantom installer"
-```
diff --git a/gemini-extension.json b/gemini-extension.json
index 878b94a..18e983b 100644
--- a/gemini-extension.json
+++ b/gemini-extension.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
"description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
- "version": "7.0.0",
+ "version": "7.0.1",
"contextFileName": "GEMINI.md"
}
diff --git a/package.json b/package.json
index 1dc53c2..acc6562 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "superpowers",
- "version": "7.0.0",
+ "version": "7.0.1",
"description": "Superpowers skills and runtime bootstrap for coding agents",
"type": "module",
"main": ".opencode/plugins/superpowers.js",
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md
index 22b98fc..7f5eef0 100644
--- a/skills/brainstorming/SKILL.md
+++ b/skills/brainstorming/SKILL.md
@@ -23,18 +23,63 @@ why?
blue"). This is a quick, clear task. Do it, and say what you did.
- **Something non-trivial is missing.** Start the conversation.
-## Your First Message
+Before you start implementing, you must, in order:
+
+1. Lay out the approaches in a message of their own, and have your
+ human partner pick one (see Lay out the approaches).
+2. Write the design doc, short or full (see Size the Work).
+3. Get their approval of that doc.
+4. Invoke the superpowers:writing-plans skill.
+
+Two things aren't implementing: a spike they said yes to (see Spike to
+feel things out), and doing what they asked once they've opted out of
+the questions.
+
+## Look Before You Ask
+
+In an existing project, or when they've given you context (a spec, a plan,
+a handoff, files they pointed at, earlier conversation), dig in before your
+first message. Read what they referred to and the code or material it
+connects to, and keep reading until you can explain how the relevant
+parts work today and what this change would touch. Never ask what the
+project or their context already answers.
-Your first message is two things, in this order:
+## Your First Message
-1. One line letting them know that if they'd rather skip the questions and
- have you just start, they can say so. If they take you up on it, this
- skill is done: state any significant how-it-gets-made choice
- (platform, language, medium) in one plain line, then do what they
- asked through the normal workflow.
-2. One open question that gets them describing. Ask about a real moment
- or a concrete picture: "What's the moment you find yourself wishing
- this existed?" or "Tell me about the people who'll be in the room."
+Move the work forward, with one of these:
+
+- **They've already said what they want** (a spec, a plan, a detailed
+ request): aim for about 200 words for the whole message. Echo their
+ request back in your own words, so they can see whether you've got its
+ shape: what they want, who it's for, and why, as far as they've said.
+ Add what you found that bears on it: how the relevant parts work today
+ and what the change would touch. If you found something they may not
+ have considered that would change what they're asking for or how it
+ has to be built, like a constraint, a conflict, or a cheaper path, say
+ so plainly. How to build it comes later, once you understand what they
+ want (see Lay out the approaches). End with one line inviting
+ corrections, then one question about what they want: the thing their
+ request leaves open whose answer would most change what gets built.
+ Specs are often incomplete, so confirm before you build on one.
+- **They haven't:** one open question, in their own terms, about the
+ biggest thing their request leaves unsettled. Say why you're asking:
+ what the answer would change about what you build. For "a website for
+ my bakery": "If it's mostly for people deciding whether to stop by,
+ I'd lead with hours and what's in the case today; taking orders is a
+ different site. What do you want someone to do when they land on it?"
+
+How the message ends depends on whether their message asked for
+brainstorming:
+
+- **They asked for it** (by name, by invoking it, or by asking for a
+ design discussion): end with your question. They want this
+ conversation.
+- **They didn't:** they may not want a conversation at all. After your
+ question, add a light, one-line offer to just get going instead, like
+ "Or if you'd rather I just dive in, say so." If they take you up on
+ it, this skill is done: state any significant how-it-gets-made choice
+ (platform, language, medium) in one plain line, then do what they
+ asked through the normal workflow.
That's the whole message.
@@ -43,7 +88,8 @@ That's the whole message.
Each message ends with one question: a single sentence with no list of
example answers hanging off it. Use plain language, pitched just a little
above where your human partner is. Match their vocabulary; never use
-process jargon.
+process jargon. You never need to quote this skill to your human
+partner.
Be clear and concise. Lead with what matters. Avoid jargon. When you
report what you found, give them the most important findings and offer
@@ -75,19 +121,31 @@ out as questions:
- current state: what exists now, what they've tried
- the details they care about
-**Questions that work** anchor in specifics: "Walk me through the last
-time...", "If it could only do one of these well, which?", "What would
-make you wince if I got it wrong?" A guess they can correct ("I'm
-guessing this is because X keeps biting you?") often beats a question.
-
-**Offer recon.** Once you have a bit of grounding and looking would help,
-offer to go look: their codebase or project, their own files and data,
-or the web. Say what you'd look for. They decide whether you go.
-
-**Think wide privately.** Before you propose anything, come up with
-several ideas and drop the weak ones, including any that fight what
-they've told you about why. Show the comparison only when it helps them
-decide.
+**Make every question specific** to their project and what they've told
+you. Ask Socratically, the way a sharp colleague would: build each
+question on their last answer or on something you found, so it helps
+them think through a consequence or a case they may have missed
+("Voting closes before the meeting, and two members joined this month.
+Does someone who joins mid-round get a vote?"). When the reason isn't
+already plain, say what you're hoping to learn or what the answer would
+change. A proposal they can correct, plus your reason for it, often
+beats a question.
+
+**Offer recon.** Once you have a bit of grounding and looking further
+would help, offer to go look: deeper into their codebase or project,
+their own files and data, or the web. Say what you'd look for. They
+decide whether you go.
+
+**Lay out the approaches.** Once you understand what they want, and
+before you write anything up, put the ways of building it in a message
+of its own. Come up with several real alternatives and drop the weak
+ones, including any that work against why they want it and any the
+existing work rules out. Present the two or three that remain, grounding
+each in what the project actually does and saying what it trades off.
+Recommend one and say why, then ask which way they want to go. When
+there's genuinely one sensible way, say so and explain why the others
+don't fit. This is for how it gets built; for what they want, get them
+describing first.
**Show, don't tell.** Offer the visual companion (below) whenever seeing
would help more than reading:
@@ -117,8 +175,9 @@ behaves), describe that part back in about 200-300 words, then return to
questions about the next part. Playback and questions alternate through
the whole conversation; the last chunk covers whatever is left.
-Mark anything you're guessing as your guess; only what they said goes in
-as theirs. End each chunk by asking what's wrong or missing.
+Only what they said goes in as theirs. Anything you filled in goes in
+as your proposal, with your reason. End each chunk by asking what's wrong
+or missing.
Before you send a chunk, check it: does it describe something they'll
look at, like a page, a screen, a schedule, or a printout? If so, and
@@ -128,14 +187,18 @@ they've accepted, put a mockup next to the description.
## Size the Work
-Once you understand what they want, pick a size and say it in plain
-words. They can override it.
+Once you understand what they want and they've picked an approach, say
+how big the work is in plain words. They can override it.
-| Size | The full description | Then |
-|------|----------------------|------|
-| A quick, clear task | the request itself | do it |
-| A small change | in chat | build it through the normal workflow |
-| A project with a written design | a written design document | a full plan (for software: superpowers:writing-plans) |
+| Size | The design doc |
+|------|----------------|
+| A small change | a short one: what you already covered together, written down |
+| A project | the full written design (below) |
+
+Short or full, the design doc has an **Approaches** part: the two or
+three ways you considered building it, what each trades off, which one
+they picked, and why. They pick in the conversation, before you write
+the doc.
If it grows mid-task, stop, say so, and step up a size.
@@ -144,20 +207,25 @@ order, and brainstorm them one at a time.
## The Written Design
-For a project, write a plain document a talented builder in the domain
-could plan from without going back to your human partner. Cover:
+Write a plain document a talented builder in the domain could plan
+from without going back to your human partner. Cover:
- intent and the why
- goals, non-goals, anti-goals
- constraints
+- approaches (above)
- the parts of the how they decided, as they decided them
- what's left to the builder
+For a small change, the short design covers the same points in a line
+or two each and goes straight to your human partner, without the
+builder check.
+
**Where it goes:** in a software repo,
`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, committed.
Otherwise, ask. Your human partner's preferences override both.
-**Builder check:** dispatch a fresh subagent with
+**Builder check** (for a project): dispatch a fresh subagent with
`builder-check-prompt.md` in this directory. When you tell your human
partner you're writing it up, say a reviewer will read it first and you
may come back once with a few questions. Don't hand over the document
@@ -177,8 +245,8 @@ round of questions the check produces. Without a subagent tool, read the
document as that builder yourself.
<HARD-GATE>
-Nothing gets built until your human partner approves the full
-description: in chat for a small change, the document for a project.
+Nothing gets built until your human partner approves the design doc:
+the short one for a small change, the full one for a project.
Building includes writing product code, scaffolding, installing
dependencies, creating projects, and invoking an implementation skill.
Reading and exploring are fine.
@@ -188,18 +256,19 @@ and the gate goes with it. A spike they said yes to may be built; it
stays labeled throwaway, and keeping what it produced is a new request
that comes back through this gate.
-After a project's document is approved, the next step is the plan. For
-software, invoke superpowers:writing-plans and no other skill.
+After the design doc is approved, the next step is the plan: invoke
+superpowers:writing-plans and no other skill.
</HARD-GATE>
## Red Flags
| Thought | Reality |
|---------|---------|
-| "I'll offer options to save them effort" | Options steer. Ask them to describe it first. |
+| "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
| "I'll fill in sensible defaults" | Good. Say them out loud. A default they never heard is one they couldn't reject. |
+| "I've answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own. |
| "I should explain the process first" | Ask your question. The process shows itself. |
-| "They said 'sounds good' to the idea" | Approval covers what you showed them. A description you haven't written isn't approved. |
+| "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you haven't written isn't approved. |
| "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
## Visual Companion
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md
index 49077ad..ac77129 100644
--- a/skills/executing-plans/SKILL.md
+++ b/skills/executing-plans/SKILL.md
@@ -319,55 +319,3 @@ Use superpowers:finishing-a-development-branch.
| "The reviewer said Minor, so it's Minor" | The label graded the spec's silence. Grade what the person gets. Re-grade, then gate. |
| "The fix is obvious, no need for a failing test first" | The failing test is the only proof the finding was real and is now gone. Without it you have a diff and a hope. |
| "I'll fix the minors too while I'm in there" | Every minor you fix is a test, a fix, and a suite run your partner did not ask for. Ledger them; your partner decides. |
-
-## Example Workflow
-
-```
-You: I'm using the executing-plans skill to implement this plan inline.
-
-[Setup: worktree verified]
-[Read plan once: docs/superpowers/plans/feature-plan.md; spec read]
-[Resolve workspace: sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
-[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger]
-[Create todos for all tasks]
-
-Task 1: Hook installation script
-
-[task-start plan 1 → brief read; BASE a1b2c3d]
-[Step 1: write failing test — written]
-[Step 2: run it — FAIL: install_hook not defined. Matches Expected.]
-[Step 3: implement — written]
-[Step 4: run it — PASS 1/1. Matches Expected.]
-[Step 5: commit — d4e5f6a]
-[Contract: tests ran, output read, no deviations]
-[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]
-
-Task 2: Recovery modes
-
-[task-start plan 2 → brief read; BASE d4e5f6a]
-[Step 2: run failing test — FAIL, but on an import error: Task 1 exported
- installHook, brief consumes install_hook]
-[Ruling: brief's consumer name is a typo against Task 1's Produces block;
- use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
-[Steps 2-5 as planned; commit b7c8d9e]
-[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]
-
-...
-
-[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model]
-Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor.
-[Re-grade: Important stands; minors → ledger as deferred]
-[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit]
-[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]
-
-Rulings I made:
-- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename)
-
-Deferred minors:
-- README lacks a usage example
-- recovery.js could split verify/repair into two files
-
-[Delete this plan's workspace — the record now lives in git]
-
-Using superpowers:finishing-a-development-branch.
-```
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md
index f7bbf6a..ea170ed 100644
--- a/skills/subagent-driven-development/SKILL.md
+++ b/skills/subagent-driven-development/SKILL.md
@@ -70,23 +70,13 @@ digraph process {
"Implementer implements, tests, commits, self-reviews" [shape=box];
"Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
"Spec ✅ and quality approved?" [shape=diamond];
- "Finding conflicts with plan text?" [shape=diamond];
- "Rule on the conflict, ledger the ruling" [shape=box];
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
- "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
- "All findings addressed?" [shape=diamond];
- "R = 5?" [shape=diamond];
- "Adjudicate each open finding" [shape=box];
- "Any load-bearing finding?" [shape=diamond];
- "Rule and continue; stop only if every path forward is a guess" [shape=box];
- "Park findings in ledger with rulings" [shape=box];
+ "Fix loop: read references/fix-loop.md before every round" [shape=box];
"Append completion to ledger, mark todo complete" [shape=box];
}
"Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
"More tasks remain?" [shape=diamond];
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
+ "Final review and finish: read references/final-review.md" [shape=box];
"Final review clean: delete this plan's workspace" [shape=box];
"Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
@@ -98,25 +88,12 @@ digraph process {
"Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
"Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
"Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
- "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
- "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
- "Rule on the conflict, ledger the ruling" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
- "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
- "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
- "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
- "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
- "All findings addressed?" -> "R = 5?" [label="no"];
- "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
- "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
- "Adjudicate each open finding" -> "Any load-bearing finding?";
- "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
- "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
- "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
+ "Spec ✅ and quality approved?" -> "Fix loop: read references/fix-loop.md before every round" [label="no"];
+ "Fix loop: read references/fix-loop.md before every round" -> "Append completion to ledger, mark todo complete" [label="addressed, or parked at the cap"];
"Append completion to ledger, mark todo complete" -> "More tasks remain?";
"More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
- "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
- "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
- "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
+ "More tasks remain?" -> "Final review and finish: read references/final-review.md" [label="no"];
+ "Final review and finish: read references/final-review.md" -> "Final review clean: delete this plan's workspace";
"Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
}
```
@@ -138,13 +115,9 @@ a ledger file, not only in todos.
directory (under `<repo-root>/.superpowers/sdd/`), home to
every artifact for THIS plan: ledger, briefs, reports, review packages.
Another plan's directory is never yours to read or write.
-- Check for this plan's ledger at `<workspace>/progress.md`. If its first
- line names your plan file, tasks with a `Task <N>: complete` line are DONE
- — do not re-dispatch them; resume at the first task without one. A task
- whose last line is a fix round is mid-loop: resume the loop at the next
- round. A ledger whose first line names a different plan file — or a stray
- ledger at the old flat path `.superpowers/sdd/progress.md` — is another
- plan's progress: leave it in place and start your own, fresh.
+- Check for this plan's ledger at `<workspace>/progress.md`. If one exists,
+ read [references/resuming.md](references/resuming.md) before anything
+ else: it says whose ledger it is and where to resume.
- Create the ledger with its identity as the first line:
`# SDD ledger — plan: <plan file path>`.
- The ledger is your recovery map: the commits it names exist in git even
@@ -159,27 +132,9 @@ authority the plan argues from, and conflicts inside the plan resolve
against it. A plan with no reachable spec gets a ledger note saying so —
rulings made without one are provisional.
-Before dispatching Task 1, scan the plan once for conflicts, writing down
-what you checked as you check it:
-
-- tasks that contradict each other or the plan's Global Constraints
-- anything the plan explicitly mandates that the review rubric treats as a
- defect (a test that asserts nothing, verbatim duplication of a logic block)
-
-The scan's output is a table, not a verdict. One row for every pair of tasks
-that share a file or an interface: the two tasks, what one produces against
-what the other consumes, and what you found. One row for every task: whether
-its own text agrees with itself — the tests it specifies against the code it
-specifies, the files it creates against the files it later touches. "The scan
-is clean" without those rows is not a scan you ran.
-
-Write the table to the ledger. Rule on everything you find before execution
-begins — each finding against the plan text that mandates it — and record
-each ruling in the ledger. If the scan is clean, proceed without comment.
-Rule on each conflict it surfaces — the spec is the binding authority, the
-plan is its argument — record the ruling beside its row, and dispatch
-Task 1. The review loop remains the net for conflicts that only emerge from
-implementation.
+Before dispatching Task 1, read [references/preflight.md](references/preflight.md)
+and run the conflict scan it describes. Its table and rulings go in the
+ledger.
## Model Selection
@@ -220,13 +175,9 @@ that implementer. Single-file mechanical fixes also take the cheapest tier.
## The Task Loop
-**Batch small same-shape work.** When the plan lists several tasks that are
-each a small, independent edit of the same kind — the same one-line fix,
-constant change, or field addition repeated across files — do not dispatch
-one subagent per task. Compose ONE dispatch brief listing every file and
-its change, send the whole batch to a single subagent, and review its diff
-as one unit. Reserve one-dispatch-per-task for work that needs its own
-judgment, its own tests, or its own review surface.
+**Small same-shape work:** when the plan lists several small edits of the
+same kind across files, read [references/batching.md](references/batching.md)
+before dispatching them.
Everything you paste into a dispatch prompt — and everything a subagent
prints back — stays resident in your context for the rest of the session
@@ -289,17 +240,9 @@ Implementer subagents report one of four statuses. Handle each appropriately:
**DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, from this skill's directory — it prints the unique file path it wrote; BASE is the commit you recorded before dispatching the implementer — never `HEAD~1`, which silently drops all but the last commit of a multi-commit task), then dispatch the task reviewer with the printed path.
-**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
-
-**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
-
-**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
-1. If it's a context problem, provide more context and re-dispatch with the same model
-2. If the task requires more reasoning, re-dispatch with a more capable model
-3. If the task is too large, break it into smaller pieces
-4. If the plan itself is wrong, rule on the correction, ledger it, and re-dispatch with the ruling carried in the dispatch
-
-**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
+**Any other status** (DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED): read
+[references/handling-reports.md](references/handling-reports.md) and follow
+it, every time you get one.
If the implementer asks questions — before starting or mid-task — answer
clearly and completely, provide additional context if needed, and don't
@@ -342,12 +285,9 @@ needed.
loop. If the prompt you are writing contains "do not flag," "don't treat X
as a defect," "at most Minor," or "the plan chose" — stop: you are
pre-judging, usually to spare yourself a review loop.
-The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
-that live in unchanged code or span tasks. These do not block the rest of the
-review, but you must resolve each one yourself before marking the task
-complete: you hold the plan and cross-task context the reviewer
-lacks. If you confirm an item is a real gap, treat it as a failed spec
-review — it enters the fix loop with the other findings.
+If the reviewer reports "⚠️ Cannot verify from diff" items, read
+[references/cannot-verify.md](references/cannot-verify.md) before you mark
+the task complete.
Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
@@ -356,77 +296,10 @@ Template: [task-reviewer-prompt.md](task-reviewer-prompt.md)
The loop triggers when the review reports spec ❌, any Critical or Important
finding, or a ⚠️ item you confirmed as a real gap.
-Before the loop starts, two routes leave it immediately:
-
-- Record Minor findings in the progress ledger as you go
- (`Task <N>: minor (deferred): <one-liner>`), and point the final
- whole-branch review at that list so it can triage which must be fixed
- before merge. A roll-up nobody reads is a silent discard. Minor findings
- never enter the loop.
-- A finding labeled plan-mandated — or any finding that conflicts with
- what the plan's text requires — is yours to rule on: weigh the finding
- against the plan text, decide with the spec as the binding authority, and
- ledger the ruling before you act on it. Do not dismiss the finding because
- the plan mandates it, and do not dispatch a fix that contradicts the plan
- without a recorded ruling.
-Everything else enters the loop. A fix round is one fix dispatch plus one
-scoped re-review. Five rounds maximum per task:
-
-**Rounds 1-3 — resume the original implementer.** Send it the open findings
-verbatim. Its context is intact: it knows the task, the code, and its own
-choices. If your harness cannot send another message to a live subagent,
-dispatch a fresh implementer carrying the brief path, the report-file path,
-and the findings — the report file is the persistent memory either way.
-
-**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
-Model Selection), with the brief path, the report-file path, the open
-findings, and this framing: "A prior implementer attempted this task
-[N] times; you own it now. Read the report file for what was tried." A loop
-that survives three resumes usually means the implementer cannot see its
-own problem — fresh eyes and a capability bump in one move.
-
-**Every round, either way:** the implementer fixes, re-runs the tests
-covering the amended code, appends its fix report to the same report file,
-and returns the short contract. Before re-dispatching the reviewer, confirm
-the fix report contains the covering tests, the command run, and the
-output; dispatch the re-review once all three are present. Name the
-covering test files in the fix message — a one-line fix does not need the
-whole suite.
-
-**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
-where FIX_BASE is the head the previous review saw, and dispatch
-[re-review-prompt.md](re-review-prompt.md) with the findings list, the
-brief, the report file, and the printed diff path. The re-reviewer verdicts
-each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
-diff only. New Critical/Important breakage in the fix diff joins the open
-findings list. Out-of-scope observations go to the ledger as deferred
-minors — they never extend the loop.
-
-**After each round,** append to the ledger:
-`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
-
-Never fix findings yourself in the controller session — your context stays
-clean for coordination, and controller fixes skip review.
-
-**The breaker.** When round 5's re-review still leaves findings open, stop
-dispatching. Adjudicate each open finding yourself — you hold the plan and
-the cross-task context the reviewer lacks:
-
-- **The reviewer is wrong, or the point is contestable:** park it —
- `Task <N>: parked — <finding> — Ruling: <why the code stands>`. The final
- review sees both sides.
-- **Real, but nothing downstream builds on it:** park it the same way, with
- a ruling that says it's real and deferred.
-- **Real and load-bearing** — a later task builds on it, or it reveals a
- plan defect: rule on the smallest change that unblocks the dependent work,
- ledger it as `Task <N>: Ruling: <finding> — <what you decided and why>`,
- and carry it into the next task's dispatch. Parking a structural failure
- silently lets every dependent task build on it. Stop only when the defect
- leaves every path forward a guess.
-
-Adjudicate only at the cap. Adjudicating earlier to end a loop is
-pre-judging with a different name. Every adjudication is a ledger entry —
-a silent discard is forbidden.
+When it triggers, read [references/fix-loop.md](references/fix-loop.md) and
+follow it. Read it again before every round, even if you read it earlier in
+this session: it holds the round cap, the breaker, and the ledger line each
+round writes, and your memory of it does not survive compaction.
### 5. Complete the task
@@ -444,47 +317,9 @@ parked-with-ruling at the cap.
## Final Review
-The final whole-branch review gets a package too: run
-`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
-branch started from, e.g. `git merge-base main HEAD`) and include the
-printed path in the final review dispatch, so the final reviewer reads
-one file instead of re-deriving the branch diff with git commands. Dispatch
-on the most capable available model (see Model Selection), using
-superpowers:requesting-code-review's
-[code-reviewer.md](../requesting-code-review/code-reviewer.md). Point it at
-the ledger's deferred-minor and parked lines so it can triage which must be
-fixed before merge.
-
-If the final whole-branch review returns findings, dispatch ONE fix subagent
-with the complete findings list — not one fixer per finding.
-Per-finding fixers each rebuild context and re-run suites; a real
-session's final-review fix wave cost more than all its tasks combined.
-Then run exactly one scoped re-review of the fix wave
-(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
-[re-review-prompt.md](re-review-prompt.md)).
-Adjudicate any residual findings as in the task loop's breaker: park with
-rulings, or rule on the load-bearing ones and ledger what you decided. Only
-the four classes above stop you here. There is no second fix wave —
-residual load-bearing findings surface to your human partner when
-finishing-a-development-branch presents the options.
-
-## Finish
-
-Before you delete anything, collect every ledger line containing `Ruling:` —
-preflight rulings, parked findings, breaker adjudications, all of them — into
-your final message under "Rulings I made", in the order you made them, each
-with what it costs if wrong. The list is exhaustive: if the ledger holds a
-ruling, the list holds it. That list is the only place the decisions you
-took on your human partner's behalf reach them — they read it and rework
-whatever you got wrong. A ruling that dies with the workspace was a decision
-made in secret.
-
-When the final whole-branch review is clean and its fixes are merged,
-delete this plan's workspace (`rm -rf <workspace>`) — the git history is
-the record now. Sibling directories belong to other plans; leave them
-alone.
-
-Use superpowers:finishing-a-development-branch.
+When every task is complete, read
+[references/final-review.md](references/final-review.md) and follow it. It
+covers the whole-branch review, its single fix wave, and how you finish.
## Common Rationalizations
@@ -499,70 +334,3 @@ Use superpowers:finishing-a-development-branch.
| "Reviews slow the loop down" | The loop without reviews is just unverified churn. Reviews are the loop's brakes and steering. |
| "Ledger bookkeeping is overhead" | The ledger is what survives compaction. Controllers without one have re-dispatched entire completed task sequences. |
| "The implementer spawned its own reviewer — free extra assurance" | It's a duplicate seat reviewing the same diff; the task review is the gate. A worker-spawned reviewer is a defect to flag, not rigor. |
-
-## Example Workflow
-
-```
-You: I'm using Subagent-Driven Development to execute this plan.
-
-[Setup: worktree verified]
-[Read plan file once: docs/superpowers/plans/feature-plan.md]
-[Resolve workspace: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
-[Create todos for all tasks]
-
-Task 1: Hook installation script
-
-[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]
-
-Implementer: "Before I begin - should the hook be installed at user or system level?"
-
-You: "User level (~/.config/superpowers/hooks/)"
-
-Implementer: [Later]
- - Implemented install-hook command
- - Added tests, 5/5 passing
- - Self-review: Found I missed --force flag, added it
- - Committed
-
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
-Task reviewer: Spec ✅ - all requirements met, nothing extra.
- Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
-
-[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
-
-Task 2: Recovery modes
-
-[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]
-
-Implementer: [No questions]
- - Added verify/repair modes
- - 8/8 tests passing
- - Committed
-
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
-Task reviewer: Spec ❌:
- - Missing: Progress reporting (spec says "report every 100 items")
- Issues (Important): Magic number (100)
-
-[Fix round 1: resume the implementer with both findings]
-Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
- Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
-
-[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
-Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
- Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
- Verdict: all findings addressed.
-
-[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
-[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]
-
-...
-
-[After all tasks]
-[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
-Final reviewer: All requirements met. Deferred minors triaged: none block merge.
-
-[Delete this plan's workspace — the record now lives in git]
-
-Done! Using superpowers:finishing-a-development-branch.
-```
diff --git a/skills/subagent-driven-development/references/batching.md b/skills/subagent-driven-development/references/batching.md
new file mode 100644
index 0000000..6224e4b
--- /dev/null
+++ b/skills/subagent-driven-development/references/batching.md
@@ -0,0 +1,11 @@
+# Batching Small Same-Shape Work
+
+Part of superpowers:subagent-driven-development.
+
+**Batch small same-shape work.** When the plan lists several tasks that are
+each a small, independent edit of the same kind — the same one-line fix,
+constant change, or field addition repeated across files — do not dispatch
+one subagent per task. Compose ONE dispatch brief listing every file and
+its change, send the whole batch to a single subagent, and review its diff
+as one unit. Reserve one-dispatch-per-task for work that needs its own
+judgment, its own tests, or its own review surface.
diff --git a/skills/subagent-driven-development/references/cannot-verify.md b/skills/subagent-driven-development/references/cannot-verify.md
new file mode 100644
index 0000000..e952f2d
--- /dev/null
+++ b/skills/subagent-driven-development/references/cannot-verify.md
@@ -0,0 +1,10 @@
+# "Cannot Verify From Diff" Items
+
+Part of superpowers:subagent-driven-development.
+
+The task reviewer may report "⚠️ Cannot verify from diff" items — requirements
+that live in unchanged code or span tasks. These do not block the rest of the
+review, but you must resolve each one yourself before marking the task
+complete: you hold the plan and cross-task context the reviewer
+lacks. If you confirm an item is a real gap, treat it as a failed spec
+review — it enters the fix loop with the other findings.
diff --git a/skills/subagent-driven-development/references/final-review.md b/skills/subagent-driven-development/references/final-review.md
new file mode 100644
index 0000000..851a5c5
--- /dev/null
+++ b/skills/subagent-driven-development/references/final-review.md
@@ -0,0 +1,47 @@
+# Final Review and Finish
+
+Part of superpowers:subagent-driven-development. Every task in the plan is
+complete.
+
+The final whole-branch review gets a package too: run
+`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
+branch started from, e.g. `git merge-base main HEAD`) and include the
+printed path in the final review dispatch, so the final reviewer reads
+one file instead of re-deriving the branch diff with git commands. Dispatch
+on the most capable available model (see SKILL.md's Model Selection), using
+superpowers:requesting-code-review's
+[code-reviewer.md](../../requesting-code-review/code-reviewer.md). Point it at
+the ledger's deferred-minor and parked lines so it can triage which must be
+fixed before merge.
+
+If the final whole-branch review returns findings, dispatch ONE fix subagent
+with the complete findings list — not one fixer per finding.
+Per-finding fixers each rebuild context and re-run suites; a real
+session's final-review fix wave cost more than all its tasks combined.
+Then run exactly one scoped re-review of the fix wave
+(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
+[re-review-prompt.md](../re-review-prompt.md)).
+Adjudicate any residual findings as in the fix loop's breaker
+(references/fix-loop.md): park with rulings, or rule on the load-bearing
+ones and ledger what you decided. Only the four things that stop a running
+plan (top of SKILL.md) stop you here. There is no second fix wave —
+residual load-bearing findings surface to your human partner when
+finishing-a-development-branch presents the options.
+
+### Finish
+
+Before you delete anything, collect every ledger line containing `Ruling:` —
+preflight rulings, parked findings, breaker adjudications, all of them — into
+your final message under "Rulings I made", in the order you made them, each
+with what it costs if wrong. The list is exhaustive: if the ledger holds a
+ruling, the list holds it. That list is the only place the decisions you
+took on your human partner's behalf reach them — they read it and rework
+whatever you got wrong. A ruling that dies with the workspace was a decision
+made in secret.
+
+When the final whole-branch review is clean and its fixes are merged,
+delete this plan's workspace (`rm -rf <workspace>`) — the git history is
+the record now. Sibling directories belong to other plans; leave them
+alone.
+
+Use superpowers:finishing-a-development-branch.
diff --git a/skills/subagent-driven-development/references/fix-loop.md b/skills/subagent-driven-development/references/fix-loop.md
new file mode 100644
index 0000000..0b476e9
--- /dev/null
+++ b/skills/subagent-driven-development/references/fix-loop.md
@@ -0,0 +1,77 @@
+# The Fix Loop
+
+Part of superpowers:subagent-driven-development. The task review reported
+spec ❌, a Critical or Important finding, or a ⚠️ item you confirmed as a real
+gap.
+
+Before the loop starts, two routes leave it immediately:
+
+- Record Minor findings in the progress ledger as you go
+ (`Task <N>: minor (deferred): <one-liner>`), and point the final
+ whole-branch review at that list so it can triage which must be fixed
+ before merge. A roll-up nobody reads is a silent discard. Minor findings
+ never enter the loop.
+- A finding labeled plan-mandated — or any finding that conflicts with
+ what the plan's text requires — is yours to rule on: weigh the finding
+ against the plan text, decide with the spec as the binding authority, and
+ ledger the ruling before you act on it. Do not dismiss the finding because
+ the plan mandates it, and do not dispatch a fix that contradicts the plan
+ without a recorded ruling.
+Everything else enters the loop. A fix round is one fix dispatch plus one
+scoped re-review. Five rounds maximum per task:
+
+**Rounds 1-3 — resume the original implementer.** Send it the open findings
+verbatim. Its context is intact: it knows the task, the code, and its own
+choices. If your harness cannot send another message to a live subagent,
+dispatch a fresh implementer carrying the brief path, the report-file path,
+and the findings — the report file is the persistent memory either way.
+
+**Rounds 4-5 — dispatch a fresh implementer on a more capable model** (per
+SKILL.md's Model Selection), with the brief path, the report-file path, the open
+findings, and this framing: "A prior implementer attempted this task
+[N] times; you own it now. Read the report file for what was tried." A loop
+that survives three resumes usually means the implementer cannot see its
+own problem — fresh eyes and a capability bump in one move.
+
+**Every round, either way:** the implementer fixes, re-runs the tests
+covering the amended code, appends its fix report to the same report file,
+and returns the short contract. Before re-dispatching the reviewer, confirm
+the fix report contains the covering tests, the command run, and the
+output; dispatch the re-review once all three are present. Name the
+covering test files in the fix message — a one-line fix does not need the
+whole suite.
+
+**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
+where FIX_BASE is the head the previous review saw, and dispatch
+[re-review-prompt.md](../re-review-prompt.md) with the findings list, the
+brief, the report file, and the printed diff path. The re-reviewer verdicts
+each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
+diff only. New Critical/Important breakage in the fix diff joins the open
+findings list. Out-of-scope observations go to the ledger as deferred
+minors — they never extend the loop.
+
+**After each round,** append to the ledger:
+`Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)`
+
+Never fix findings yourself in the controller session — your context stays
+clean for coordination, and controller fixes skip review.
+
+**The breaker.** When round 5's re-review still leaves findings open, stop
+dispatching. Adjudicate each open finding yourself — you hold the plan and
+the cross-task context the reviewer lacks:
+
+- **The reviewer is wrong, or the point is contestable:** park it —
+ `Task <N>: parked — <finding> — Ruling: <why the code stands>`. The final
+ review sees both sides.
+- **Real, but nothing downstream builds on it:** park it the same way, with
+ a ruling that says it's real and deferred.
+- **Real and load-bearing** — a later task builds on it, or it reveals a
+ plan defect: rule on the smallest change that unblocks the dependent work,
+ ledger it as `Task <N>: Ruling: <finding> — <what you decided and why>`,
+ and carry it into the next task's dispatch. Parking a structural failure
+ silently lets every dependent task build on it. Stop only when the defect
+ leaves every path forward a guess.
+
+Adjudicate only at the cap. Adjudicating earlier to end a loop is
+pre-judging with a different name. Every adjudication is a ledger entry —
+a silent discard is forbidden.
diff --git a/skills/subagent-driven-development/references/handling-reports.md b/skills/subagent-driven-development/references/handling-reports.md
new file mode 100644
index 0000000..cf91cdc
--- /dev/null
+++ b/skills/subagent-driven-development/references/handling-reports.md
@@ -0,0 +1,15 @@
+# Handling a Report That Isn't DONE
+
+Part of superpowers:subagent-driven-development.
+
+**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
+
+**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
+
+**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
+1. If it's a context problem, provide more context and re-dispatch with the same model
+2. If the task requires more reasoning, re-dispatch with a more capable model
+3. If the task is too large, break it into smaller pieces
+4. If the plan itself is wrong, rule on the correction, ledger it, and re-dispatch with the ruling carried in the dispatch
+
+**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
diff --git a/skills/subagent-driven-development/references/preflight.md b/skills/subagent-driven-development/references/preflight.md
new file mode 100644
index 0000000..1701648
--- /dev/null
+++ b/skills/subagent-driven-development/references/preflight.md
@@ -0,0 +1,26 @@
+# The Pre-flight Scan
+
+Part of superpowers:subagent-driven-development. Run it once, before
+dispatching Task 1.
+
+Before dispatching Task 1, scan the plan once for conflicts, writing down
+what you checked as you check it:
+
+- tasks that contradict each other or the plan's Global Constraints
+- anything the plan explicitly mandates that the review rubric treats as a
+ defect (a test that asserts nothing, verbatim duplication of a logic block)
+
+The scan's output is a table, not a verdict. One row for every pair of tasks
+that share a file or an interface: the two tasks, what one produces against
+what the other consumes, and what you found. One row for every task: whether
+its own text agrees with itself — the tests it specifies against the code it
+specifies, the files it creates against the files it later touches. "The scan
+is clean" without those rows is not a scan you ran.
+
+Write the table to the ledger. Rule on everything you find before execution
+begins — each finding against the plan text that mandates it — and record
+each ruling in the ledger. If the scan is clean, proceed without comment.
+Rule on each conflict it surfaces — the spec is the binding authority, the
+plan is its argument — record the ruling beside its row, and dispatch
+Task 1. The review loop remains the net for conflicts that only emerge from
+implementation.
diff --git a/skills/subagent-driven-development/references/resuming.md b/skills/subagent-driven-development/references/resuming.md
new file mode 100644
index 0000000..409b826
--- /dev/null
+++ b/skills/subagent-driven-development/references/resuming.md
@@ -0,0 +1,12 @@
+# Resuming From an Existing Ledger
+
+Part of superpowers:subagent-driven-development. This plan's workspace
+already has a ledger at `<workspace>/progress.md`.
+
+If the ledger's first line names your plan file, tasks with a `Task <N>:
+complete` line are DONE — do not re-dispatch them; resume at the first
+task without one. A task whose last line is a fix round is mid-loop:
+resume the loop at the next round. A ledger whose first line names a
+different plan file — or a stray ledger at the old flat path
+`.superpowers/sdd/progress.md` — is another plan's progress: leave it in
+place and start your own, fresh.
diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md
index 182dfad..09d76b7 100644
--- a/skills/writing-skills/SKILL.md
+++ b/skills/writing-skills/SKILL.md
@@ -17,7 +17,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
-**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
+**Official guidance:** For Anthropic's official skill authoring best practices, see references/anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
## What is a Skill?
@@ -90,236 +90,23 @@ skills/
- Code patterns (< 50 lines)
- Everything else
-## SKILL.md Structure
+## Writing SKILL.md
-**Frontmatter (YAML):**
-- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
-- Max 1024 characters total
-- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
-- `description`: Third-person, describes ONLY when to use (NOT what it does)
- - Start with "Use when..." to focus on triggering conditions
- - Include specific symptoms, situations, and contexts
- - **NEVER summarize the skill's process or workflow** (see SDO section for why)
- - Keep under 500 characters if possible
+A skill's `description` says only when to use it: triggering conditions and
+symptoms, starting with "Use when...". It never summarizes the skill's
+workflow, because an agent that reads a workflow summary follows it instead
+of reading the skill.
-```markdown
----
-name: Skill-Name-With-Hyphens
-description: Use when [specific triggering conditions and symptoms]
----
-
-# Skill Name
-
-## Overview
-What is this? Core principle in 1-2 sentences.
-
-## When to Use
-[Small inline flowchart IF decision non-obvious]
-
-Bullet list with SYMPTOMS and use cases
-When NOT to use
-
-## Core Pattern (for techniques/patterns)
-Before/after code comparison
-
-## Quick Reference
-Table or bullets for scanning common operations
-
-## Implementation
-Inline code for simple patterns
-Link to file for heavy reference or reusable tools
-
-## Common Mistakes
-What goes wrong + fixes
-
-## Real-World Impact (optional)
-Concrete results
-```
-
-
-## Skill Discovery Optimization (SDO)
-
-**Critical for discovery:** Future agents need to FIND your skill
-
-### 1. Rich Description Field
-
-**Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
-
-**Format:** Start with "Use when..." to focus on triggering conditions
-
-**CRITICAL: Description = When to Use, NOT What the Skill Does**
-
-The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
-
-**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
-
-When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
-
-**The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
-
-```yaml
-# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
-description: Use when executing plans - dispatches subagent per task with code review between tasks
-
-# ❌ BAD: Too much process detail
-description: Use for TDD - write test first, watch it fail, write minimal code, refactor
-
-# ✅ GOOD: Just triggering conditions, no workflow summary
-description: Use when executing implementation plans with independent tasks in the current session
-
-# ✅ GOOD: Triggering conditions only
-description: Use when implementing any feature or bugfix, before writing implementation code
-```
-
-**Content:**
-- Use concrete triggers, symptoms, and situations that signal this skill applies
-- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
-- Keep triggers technology-agnostic unless the skill itself is technology-specific
-- If skill is technology-specific, make that explicit in the trigger
-- Write in third person (injected into system prompt)
-- **NEVER summarize the skill's process or workflow**
-
-```yaml
-# ❌ BAD: Too abstract, vague, doesn't include when to use
-description: For async testing
-
-# ❌ BAD: First person
-description: I can help you with async tests when they're flaky
-
-# ❌ BAD: Mentions technology but skill isn't specific to it
-description: Use when tests use setTimeout/sleep and are flaky
-
-# ✅ GOOD: Starts with "Use when", describes problem, no workflow
-description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
-
-# ✅ GOOD: Technology-specific skill with explicit trigger
-description: Use when using React Router and handling authentication redirects
-```
-
-### 2. Keyword Coverage
-
-Use words an agent would search for:
-- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
-- Symptoms: "flaky", "hanging", "zombie", "pollution"
-- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
-- Tools: Actual commands, library names, file types
-
-### 3. Descriptive Naming
-
-**Use active voice, verb-first:**
-- ✅ `creating-skills` not `skill-creation`
-- ✅ `condition-based-waiting` not `async-test-helpers`
-
-### 4. Token Efficiency (Critical)
-
-**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
-
-**Target word counts:**
-- getting-started workflows: <150 words each
-- Frequently-loaded skills: <200 words total
-- Other skills: <500 words (still be concise)
-
-**Techniques:**
-
-**Move details to tool help:**
-```bash
-# ❌ BAD: Document all flags in SKILL.md
-search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
-
-# ✅ GOOD: Reference --help
-search-conversations supports multiple modes and filters. Run --help for details.
-```
-
-**Use cross-references:**
-```markdown
-# ❌ BAD: Repeat workflow details
-When searching, dispatch subagent with template...
-[20 lines of repeated instructions]
-
-# ✅ GOOD: Reference other skill
-Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
-```
+When you write or change a skill's frontmatter, name or description, or
+need to cut its size, read [references/discovery.md](references/discovery.md):
+the SKILL.md template, description and keyword guidance, naming, token
+budgets, and cross-referencing other skills.
-**Compress examples:**
-```markdown
-# ❌ BAD: Verbose example (42 words)
-your human partner: "How did we handle authentication errors in React Router before?"
-You: I'll search past conversations for React Router authentication patterns.
-[Dispatch subagent with search query: "React Router authentication error handling 401"]
-
-# ✅ GOOD: Minimal example (20 words)
-Partner: "How did we handle auth errors in React Router?"
-You: Searching...
-[Dispatch subagent → synthesis]
-```
-
-**Eliminate redundancy:**
-- Don't repeat what's in cross-referenced skills
-- Don't explain what's obvious from command
-- Don't include multiple examples of same pattern
-
-**Verification:**
-```bash
-wc -w skills/path/SKILL.md
-# getting-started workflows: aim for <150 each
-# Other frequently-loaded: aim for <200 total
-```
-
-**Name by what you DO or core insight:**
-- ✅ `condition-based-waiting` > `async-test-helpers`
-- ✅ `using-skills` not `skill-usage`
-- ✅ `flatten-with-flags` > `data-structure-refactoring`
-- ✅ `root-cause-tracing` > `debugging-techniques`
-
-**Gerunds (-ing) work well for processes:**
-- `creating-skills`, `testing-skills`, `debugging-with-logs`
-- Active, describes the action you're taking
-
-### 5. Cross-Referencing Other Skills
+## Flowcharts
-**When writing documentation that references other skills:**
-
-Use skill name only, with explicit requirement markers:
-- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
-- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
-- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
-- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
-
-**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
-
-## Flowchart Usage
-
-```dot
-digraph when_flowchart {
- "Need to show information?" [shape=diamond];
- "Decision where I might go wrong?" [shape=diamond];
- "Use markdown" [shape=box];
- "Small inline flowchart" [shape=box];
-
- "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
- "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
- "Decision where I might go wrong?" -> "Use markdown" [label="no"];
-}
-```
-
-**Use flowcharts ONLY for:**
-- Non-obvious decision points
-- Process loops where you might stop too early
-- "When to use A vs B" decisions
-
-**Never use flowcharts for:**
-- Reference material → Tables, lists
-- Code examples → Markdown blocks
-- Linear instructions → Numbered lists
-- Labels without semantic meaning (step1, helper2)
-
-See `graphviz-conventions.dot` in this directory for graphviz style rules.
-
-**Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
-```bash
-node ./render-graphs.js ../some-skill # Each diagram separately
-node ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
-```
+When you add or change a flowchart in a skill, read
+[references/flowcharts.md](references/flowcharts.md) first: when a flowchart
+earns its place, the graphviz conventions, and how to render one.
## Code Examples
@@ -464,7 +251,7 @@ Before writing guidance, classify the baseline failure. The form that bulletproo
| Baseline failure | Right form | Wrong form |
|---|---|---|
-| Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see Bulletproofing below) | Soft guidance ("prefer...", "consider...") |
+| Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see references/bulletproofing.md) | Soft guidance ("prefer...", "consider...") |
| Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") |
| Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |
| Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses |
@@ -475,81 +262,12 @@ Before writing guidance, classify the baseline failure. The form that bulletproo
- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.
- **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.
-## Bulletproofing Skills Against Rationalization
-
-Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
-
-**Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
-
-**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
-
-### Close Every Loophole Explicitly
-
-Don't just state the rule - forbid specific workarounds:
-
-<Bad>
-```markdown
-Write code before test? Delete it.
-```
-</Bad>
-
-<Good>
-```markdown
-Write code before test? Delete it. Start over.
-
-**No exceptions:**
-- Don't keep it as "reference"
-- Don't "adapt" it while writing tests
-- Don't look at it
-- Delete means delete
-```
-</Good>
-
-### Address "Spirit vs Letter" Arguments
-
-Add foundational principle early:
+## Bulletproofing Against Rationalization
-```markdown
-**Violating the letter of the rules is violating the spirit of the rules.**
-```
-
-This cuts off entire class of "I'm following the spirit" rationalizations.
-
-### Build Rationalization Table
-
-Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
-
-```markdown
-| Excuse | Reality |
-|--------|---------|
-| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
-| "I'll test after" | Tests passing immediately prove nothing. |
-| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
-```
-
-### Create Red Flags List
-
-Make it easy for agents to self-check when rationalizing:
-
-```markdown
-## Red Flags - STOP and Start Over
-
-- Code before test
-- "I already manually tested it"
-- "Tests after achieve the same purpose"
-- "It's about spirit not ritual"
-- "This is different because..."
-
-**All of these mean: Delete code. Start over with TDD.**
-```
-
-### Update SDO for Violation Symptoms
-
-Add to description: symptoms of when you're ABOUT to violate the rule:
-
-```yaml
-description: use when implementing any feature or bugfix, before writing implementation code
-```
+When the baseline failure is a discipline failure, read
+[references/bulletproofing.md](references/bulletproofing.md) before you write
+the guidance: closing loopholes, the spirit-vs-letter line, the
+rationalization table, and the red-flags list.
## RED-GREEN-REFACTOR for Skills
@@ -586,7 +304,7 @@ Full pressure-scenario runs are the final gate, but they are slow and expensive
Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.
-**Testing methodology:** See [testing-skills-with-subagents.md](testing-skills-with-subagents.md) for the complete testing methodology:
+**Testing methodology:** See [references/testing-skills-with-subagents.md](references/testing-skills-with-subagents.md) for the complete testing methodology:
- How to write pressure scenarios
- Pressure types (time, sunk cost, authority, exhaustion)
- Plugging holes systematically
diff --git a/skills/writing-skills/examples/CLAUDE_MD_TESTING.md b/skills/writing-skills/references/CLAUDE_MD_TESTING.md
index 47881fc..47881fc 100644
--- a/skills/writing-skills/examples/CLAUDE_MD_TESTING.md
+++ b/skills/writing-skills/references/CLAUDE_MD_TESTING.md
diff --git a/skills/writing-skills/anthropic-best-practices.md b/skills/writing-skills/references/anthropic-best-practices.md
index 15ea9ea..15ea9ea 100644
--- a/skills/writing-skills/anthropic-best-practices.md
+++ b/skills/writing-skills/references/anthropic-best-practices.md
diff --git a/skills/writing-skills/references/bulletproofing.md b/skills/writing-skills/references/bulletproofing.md
new file mode 100644
index 0000000..38e26fb
--- /dev/null
+++ b/skills/writing-skills/references/bulletproofing.md
@@ -0,0 +1,80 @@
+# Bulletproofing Skills Against Rationalization
+
+Part of superpowers:writing-skills. Use it when the baseline failure is a
+discipline failure: the agent knows the rule and skips it under pressure.
+
+## Bulletproofing Skills Against Rationalization
+
+Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
+
+**Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
+
+**Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md in this directory for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
+
+### Close Every Loophole Explicitly
+
+Don't just state the rule - forbid specific workarounds:
+
+<Bad>
+```markdown
+Write code before test? Delete it.
+```
+</Bad>
+
+<Good>
+```markdown
+Write code before test? Delete it. Start over.
+
+**No exceptions:**
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Don't look at it
+- Delete means delete
+```
+</Good>
+
+### Address "Spirit vs Letter" Arguments
+
+Add foundational principle early:
+
+```markdown
+**Violating the letter of the rules is violating the spirit of the rules.**
+```
+
+This cuts off entire class of "I'm following the spirit" rationalizations.
+
+### Build Rationalization Table
+
+Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
+
+```markdown
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+```
+
+### Create Red Flags List
+
+Make it easy for agents to self-check when rationalizing:
+
+```markdown
+## Red Flags - STOP and Start Over
+
+- Code before test
+- "I already manually tested it"
+- "Tests after achieve the same purpose"
+- "It's about spirit not ritual"
+- "This is different because..."
+
+**All of these mean: Delete code. Start over with TDD.**
+```
+
+### Update SDO for Violation Symptoms
+
+Add to description: symptoms of when you're ABOUT to violate the rule:
+
+```yaml
+description: use when implementing any feature or bugfix, before writing implementation code
+```
diff --git a/skills/writing-skills/references/discovery.md b/skills/writing-skills/references/discovery.md
new file mode 100644
index 0000000..fc3009d
--- /dev/null
+++ b/skills/writing-skills/references/discovery.md
@@ -0,0 +1,201 @@
+# Writing SKILL.md for Discovery
+
+Part of superpowers:writing-skills: the SKILL.md template and how to name,
+describe and size a skill so agents find it and read it.
+
+## SKILL.md Structure
+
+**Frontmatter (YAML):**
+- Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
+- Max 1024 characters total
+- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
+- `description`: Third-person, describes ONLY when to use (NOT what it does)
+ - Start with "Use when..." to focus on triggering conditions
+ - Include specific symptoms, situations, and contexts
+ - **NEVER summarize the skill's process or workflow** (see Skill Discovery Optimization below for why)
+ - Keep under 500 characters if possible
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: Use when [specific triggering conditions and symptoms]
+---
+
+# Skill Name
+
+## Overview
+What is this? Core principle in 1-2 sentences.
+
+## When to Use
+[Small inline flowchart IF decision non-obvious]
+
+Bullet list with SYMPTOMS and use cases
+When NOT to use
+
+## Core Pattern (for techniques/patterns)
+Before/after code comparison
+
+## Quick Reference
+Table or bullets for scanning common operations
+
+## Implementation
+Inline code for simple patterns
+Link to file for heavy reference or reusable tools
+
+## Common Mistakes
+What goes wrong + fixes
+
+## Real-World Impact (optional)
+Concrete results
+```
+
+
+## Skill Discovery Optimization (SDO)
+
+**Critical for discovery:** Future agents need to FIND your skill
+
+### 1. Rich Description Field
+
+**Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
+
+**Format:** Start with "Use when..." to focus on triggering conditions
+
+**CRITICAL: Description = When to Use, NOT What the Skill Does**
+
+The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
+
+**Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
+
+When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
+
+**The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
+
+```yaml
+# ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
+description: Use when executing plans - dispatches subagent per task with code review between tasks
+
+# ❌ BAD: Too much process detail
+description: Use for TDD - write test first, watch it fail, write minimal code, refactor
+
+# ✅ GOOD: Just triggering conditions, no workflow summary
+description: Use when executing implementation plans with independent tasks in the current session
+
+# ✅ GOOD: Triggering conditions only
+description: Use when implementing any feature or bugfix, before writing implementation code
+```
+
+**Content:**
+- Use concrete triggers, symptoms, and situations that signal this skill applies
+- Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
+- Keep triggers technology-agnostic unless the skill itself is technology-specific
+- If skill is technology-specific, make that explicit in the trigger
+- Write in third person (injected into system prompt)
+- **NEVER summarize the skill's process or workflow**
+
+```yaml
+# ❌ BAD: Too abstract, vague, doesn't include when to use
+description: For async testing
+
+# ❌ BAD: First person
+description: I can help you with async tests when they're flaky
+
+# ❌ BAD: Mentions technology but skill isn't specific to it
+description: Use when tests use setTimeout/sleep and are flaky
+
+# ✅ GOOD: Starts with "Use when", describes problem, no workflow
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
+
+# ✅ GOOD: Technology-specific skill with explicit trigger
+description: Use when using React Router and handling authentication redirects
+```
+
+### 2. Keyword Coverage
+
+Use words an agent would search for:
+- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
+- Symptoms: "flaky", "hanging", "zombie", "pollution"
+- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
+- Tools: Actual commands, library names, file types
+
+### 3. Descriptive Naming
+
+**Use active voice, verb-first:**
+- ✅ `creating-skills` not `skill-creation`
+- ✅ `condition-based-waiting` not `async-test-helpers`
+
+### 4. Token Efficiency (Critical)
+
+**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
+
+**Target word counts:**
+- getting-started workflows: <150 words each
+- Frequently-loaded skills: <200 words total
+- Other skills: <500 words (still be concise)
+
+**Techniques:**
+
+**Move details to tool help:**
+```bash
+# ❌ BAD: Document all flags in SKILL.md
+search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
+
+# ✅ GOOD: Reference --help
+search-conversations supports multiple modes and filters. Run --help for details.
+```
+
+**Use cross-references:**
+```markdown
+# ❌ BAD: Repeat workflow details
+When searching, dispatch subagent with template...
+[20 lines of repeated instructions]
+
+# ✅ GOOD: Reference other skill
+Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
+```
+
+**Compress examples:**
+```markdown
+# ❌ BAD: Verbose example (42 words)
+your human partner: "How did we handle authentication errors in React Router before?"
+You: I'll search past conversations for React Router authentication patterns.
+[Dispatch subagent with search query: "React Router authentication error handling 401"]
+
+# ✅ GOOD: Minimal example (20 words)
+Partner: "How did we handle auth errors in React Router?"
+You: Searching...
+[Dispatch subagent → synthesis]
+```
+
+**Eliminate redundancy:**
+- Don't repeat what's in cross-referenced skills
+- Don't explain what's obvious from command
+- Don't include multiple examples of same pattern
+
+**Verification:**
+```bash
+wc -w skills/path/SKILL.md
+# getting-started workflows: aim for <150 each
+# Other frequently-loaded: aim for <200 total
+```
+
+**Name by what you DO or core insight:**
+- ✅ `condition-based-waiting` > `async-test-helpers`
+- ✅ `using-skills` not `skill-usage`
+- ✅ `flatten-with-flags` > `data-structure-refactoring`
+- ✅ `root-cause-tracing` > `debugging-techniques`
+
+**Gerunds (-ing) work well for processes:**
+- `creating-skills`, `testing-skills`, `debugging-with-logs`
+- Active, describes the action you're taking
+
+### 5. Cross-Referencing Other Skills
+
+**When writing documentation that references other skills:**
+
+Use skill name only, with explicit requirement markers:
+- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
+- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
+- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
+- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
+
+**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
diff --git a/skills/writing-skills/references/flowcharts.md b/skills/writing-skills/references/flowcharts.md
new file mode 100644
index 0000000..63f9bfa
--- /dev/null
+++ b/skills/writing-skills/references/flowcharts.md
@@ -0,0 +1,37 @@
+# Flowcharts in Skills
+
+Part of superpowers:writing-skills.
+
+## Flowchart Usage
+
+```dot
+digraph when_flowchart {
+ "Need to show information?" [shape=diamond];
+ "Decision where I might go wrong?" [shape=diamond];
+ "Use markdown" [shape=box];
+ "Small inline flowchart" [shape=box];
+
+ "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
+ "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
+ "Decision where I might go wrong?" -> "Use markdown" [label="no"];
+}
+```
+
+**Use flowcharts ONLY for:**
+- Non-obvious decision points
+- Process loops where you might stop too early
+- "When to use A vs B" decisions
+
+**Never use flowcharts for:**
+- Reference material → Tables, lists
+- Code examples → Markdown blocks
+- Linear instructions → Numbered lists
+- Labels without semantic meaning (step1, helper2)
+
+See `graphviz-conventions.dot` in this directory for graphviz style rules.
+
+**Visualizing for your human partner:** Use `render-graphs.js` in the writing-skills directory to render a skill's flowcharts to SVG, run from there:
+```bash
+node ./render-graphs.js ../some-skill # Each diagram separately
+node ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
+```
diff --git a/skills/writing-skills/graphviz-conventions.dot b/skills/writing-skills/references/graphviz-conventions.dot
index 3509e2f..3509e2f 100644
--- a/skills/writing-skills/graphviz-conventions.dot
+++ b/skills/writing-skills/references/graphviz-conventions.dot
diff --git a/skills/writing-skills/persuasion-principles.md b/skills/writing-skills/references/persuasion-principles.md
index 9756416..9756416 100644
--- a/skills/writing-skills/persuasion-principles.md
+++ b/skills/writing-skills/references/persuasion-principles.md
diff --git a/skills/writing-skills/testing-skills-with-subagents.md b/skills/writing-skills/references/testing-skills-with-subagents.md
index a5acfea..e5bf682 100644
--- a/skills/writing-skills/testing-skills-with-subagents.md
+++ b/skills/writing-skills/references/testing-skills-with-subagents.md
@@ -12,7 +12,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres
**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
-**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
+**Complete worked example:** See CLAUDE_MD_TESTING.md in this directory for a full test campaign testing CLAUDE.md documentation variants.
## When to Use
@@ -139,7 +139,7 @@ Forces explicit choice.
**Best tests combine 3+ pressures.**
-**Why this works:** See persuasion-principles.md (in writing-skills directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.
+**Why this works:** See persuasion-principles.md (in this directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.
### Key Elements of Good Scenarios
diff --git a/tests/brainstorm-server/server.test.js b/tests/brainstorm-server/server.test.js
index 510ee98..a2bfeda 100644
--- a/tests/brainstorm-server/server.test.js
+++ b/tests/brainstorm-server/server.test.js
@@ -34,6 +34,19 @@ async function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
+// fs.watch delivery latency varies widely by platform: on macOS, FSEvents
+// has been observed delivering events anywhere from ~100ms to over 2s after
+// the write. File-watching tests poll for the outcome instead of sleeping a
+// fixed interval, so a slow event neither fails its own test nor arrives
+// during the next one.
+async function waitFor(condition, message, timeoutMs = 5000) {
+ const deadline = Date.now() + timeoutMs;
+ while (!condition()) {
+ if (Date.now() > deadline) throw new Error(message);
+ await sleep(25);
+ }
+}
+
async function fetch(url) {
return new Promise((resolve, reject) => {
const headers = { Cookie: `brainstorm-key-${TEST_PORT}=${TOKEN}` };
@@ -115,7 +128,27 @@ async function runTests() {
const server = startServer();
let stdoutAccum = '';
- server.stdout.on('data', (data) => { stdoutAccum += data.toString(); });
+ // Unlike stdoutAccum, never reset: lets a test wait until the server has
+ // processed a specific file event.
+ let serverLog = '';
+ server.stdout.on('data', (data) => {
+ stdoutAccum += data.toString();
+ serverLog += data.toString();
+ });
+ const screenLogged = (type, filePath) =>
+ serverLog.includes(JSON.stringify({ type, file: filePath }));
+
+ // Drains file events still in flight from earlier tests, which can each
+ // trigger a reload and clear state/events. fs.watch delivers events in
+ // order, so once the server has processed a file written now, every
+ // earlier event has been handled too.
+ let barrierCount = 0;
+ async function settleWatcher() {
+ const barrier = path.join(CONTENT_DIR, `barrier-${++barrierCount}.html`);
+ fs.writeFileSync(barrier, '<h2>Barrier</h2>');
+ await waitFor(() => screenLogged('screen-added', barrier),
+ 'Server should process the barrier file');
+ }
let initialStdout = '';
let passed = 0;
@@ -366,6 +399,7 @@ async function runTests() {
await test('writes choice events to state/events', async () => {
// Clean up events from prior tests
+ await settleWatcher();
const eventsFile = path.join(STATE_DIR, 'events');
if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
@@ -416,10 +450,9 @@ async function runTests() {
});
fs.writeFileSync(path.join(CONTENT_DIR, 'multi-client.html'), '<h2>Multi</h2>');
- await sleep(500);
- assert(ws1Reload, 'Client 1 should receive reload');
- assert(ws2Reload, 'Client 2 should receive reload');
+ await waitFor(() => ws1Reload, 'Client 1 should receive reload');
+ await waitFor(() => ws2Reload, 'Client 2 should receive reload');
ws1.close();
ws2.close();
});
@@ -431,8 +464,10 @@ async function runTests() {
await sleep(100);
// This should not throw even though ws1 is closed
- fs.writeFileSync(path.join(CONTENT_DIR, 'after-close.html'), '<h2>After</h2>');
- await sleep(300);
+ const afterClose = path.join(CONTENT_DIR, 'after-close.html');
+ fs.writeFileSync(afterClose, '<h2>After</h2>');
+ await waitFor(() => screenLogged('screen-added', afterClose),
+ 'Server should process the new screen');
// If we got here without error, the test passes
});
@@ -463,16 +498,16 @@ async function runTests() {
});
fs.writeFileSync(path.join(CONTENT_DIR, 'watch-new.html'), '<h2>New</h2>');
- await sleep(500);
- assert(gotReload, 'Should send reload on new file');
+ await waitFor(() => gotReload, 'Should send reload on new file');
ws.close();
});
await test('sends reload on .html file change', async () => {
const filePath = path.join(CONTENT_DIR, 'watch-change.html');
fs.writeFileSync(filePath, '<h2>Original</h2>');
- await sleep(500);
+ await waitFor(() => screenLogged('screen-added', filePath),
+ 'Server should process the original file');
const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
await new Promise(resolve => ws.on('open', resolve));
@@ -483,41 +518,44 @@ async function runTests() {
});
fs.writeFileSync(filePath, '<h2>Modified</h2>');
- await sleep(500);
- assert(gotReload, 'Should send reload on file change');
+ await waitFor(() => gotReload, 'Should send reload on file change');
ws.close();
});
await test('does NOT send reload for non-.html files', async () => {
+ await settleWatcher();
const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
await new Promise(resolve => ws.on('open', resolve));
- let gotReload = false;
+ let reloads = 0;
ws.on('message', (data) => {
- if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+ if (JSON.parse(data.toString()).type === 'reload') reloads++;
});
fs.writeFileSync(path.join(CONTENT_DIR, 'data.txt'), 'not html');
- await sleep(500);
+ await settleWatcher();
- assert(!gotReload, 'Should NOT reload for non-HTML files');
+ // The only reload is the one for settleWatcher's own file.
+ assert.strictEqual(reloads, 1, 'Should NOT reload for non-HTML files');
ws.close();
});
await test('does NOT send reload for ._*.html resource-fork dotfiles', async () => {
+ await settleWatcher();
const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
await new Promise(resolve => ws.on('open', resolve));
- let gotReload = false;
+ let reloads = 0;
ws.on('message', (data) => {
- if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+ if (JSON.parse(data.toString()).type === 'reload') reloads++;
});
fs.writeFileSync(path.join(CONTENT_DIR, '._sidecar.html'), 'resource fork');
- await sleep(500);
+ await settleWatcher();
- assert(!gotReload, 'a ._ dotfile appearing must not trigger a reload');
+ // The only reload is the one for settleWatcher's own file.
+ assert.strictEqual(reloads, 1, 'a ._ dotfile appearing must not trigger a reload');
ws.close();
});
@@ -528,29 +566,27 @@ async function runTests() {
assert(fs.existsSync(eventsFile));
fs.writeFileSync(path.join(CONTENT_DIR, 'clear-events.html'), '<h2>New screen</h2>');
- await sleep(500);
- assert(!fs.existsSync(eventsFile), 'state/events should be cleared on new screen');
+ await waitFor(() => !fs.existsSync(eventsFile), 'state/events should be cleared on new screen');
});
await test('logs screen-added on new file', async () => {
stdoutAccum = '';
fs.writeFileSync(path.join(CONTENT_DIR, 'log-test.html'), '<h2>Log</h2>');
- await sleep(500);
- assert(stdoutAccum.includes('screen-added'), 'Should log screen-added');
+ await waitFor(() => stdoutAccum.includes('screen-added'), 'Should log screen-added');
});
await test('logs screen-updated on file change', async () => {
const filePath = path.join(CONTENT_DIR, 'log-update.html');
fs.writeFileSync(filePath, '<h2>V1</h2>');
- await sleep(500);
+ await waitFor(() => screenLogged('screen-added', filePath),
+ 'Server should process V1');
stdoutAccum = '';
fs.writeFileSync(filePath, '<h2>V2</h2>');
- await sleep(500);
- assert(stdoutAccum.includes('screen-updated'), 'Should log screen-updated');
+ await waitFor(() => stdoutAccum.includes('screen-updated'), 'Should log screen-updated');
});
// ========== Helper.js Content ==========
diff --git a/tests/skill-size/test-skill-size.sh b/tests/skill-size/test-skill-size.sh
new file mode 100755
index 0000000..639bb52
--- /dev/null
+++ b/tests/skill-size/test-skill-size.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Fails when any skill's SKILL.md reaches Claude Code's compaction cut.
+#
+# After a compaction, Claude Code re-attaches each invoked skill truncated to
+# 20,000 characters (#2481). Anything past the cut is gone from the agent's
+# context for the rest of the session unless it re-reads the file. Content a
+# skill only needs sometimes belongs in references/, where the agent reads it
+# fresh from disk at the step that needs it.
+#
+# Measures bytes, which is stricter than characters for files with non-ASCII
+# text. Usage: tests/skill-size/test-skill-size.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+LIMIT=20000
+
+failed=0
+for skill in "$REPO_ROOT"/skills/*/SKILL.md; do
+ size=$(wc -c <"$skill" | tr -d ' ')
+ if ((size >= LIMIT)); then
+ echo "FAIL: ${skill#"$REPO_ROOT"/} is $size bytes (limit: under $LIMIT)" >&2
+ failed=1
+ fi
+done
+
+if ((failed)); then
+ echo "Move content the skill only needs sometimes into its references/ directory." >&2
+ exit 1
+fi
+echo "PASS: every SKILL.md is under $LIMIT bytes"