summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-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
18 files changed, 1 insertions, 13609 deletions
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"
-```