superpowers-mcp 6.3.6 → 6.3.8

package/skills/brainstorming/scripts/server.cjs

@@ -6,7 +6,7 @@ const net = require('net');
 
 // ========== WebSocket Protocol (RFC 6455) ==========
 
-const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const OPCODES = { CONTINUATION: 0x00, TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
 const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
 const MAX_FRAME_PAYLOAD_BYTES = 10 * 1024 * 1024;
 // Bound concurrent WebSocket clients (each holds a frame buffer up to
@@ -52,6 +52,8 @@ function encodeFrame(opcode, payload) {
 function decodeFrame(buffer) {
   if (buffer.length < 2) return null;
 
+  const fin = (buffer[0] & 0x80) !== 0;
+  const rsv = buffer[0] & 0x70;
   const secondByte = buffer[1];
   const opcode = buffer[0] & 0x0F;
   const masked = (secondByte & 0x80) !== 0;
@@ -59,6 +61,10 @@ function decodeFrame(buffer) {
   let offset = 2;
 
   if (!masked) throw new Error('Client frames must be masked');
+  if (rsv !== 0) throw new Error('WebSocket extensions are not supported');
+  if (![OPCODES.CONTINUATION, OPCODES.TEXT, OPCODES.CLOSE, OPCODES.PING, OPCODES.PONG].includes(opcode)) {
+    throw new Error('Unsupported WebSocket opcode');
+  }
 
   if (payloadLen === 126) {
     if (buffer.length < 4) return null;
@@ -83,6 +89,9 @@ function decodeFrame(buffer) {
   if (opcode >= 0x8 && payloadLen > 125) {
     throw new Error('WebSocket control frame payload exceeds 125 bytes');
   }
+  if (opcode >= 0x8 && !fin) {
+    throw new Error('WebSocket control frames must not be fragmented');
+  }
 
   const maskOffset = offset;
   const dataOffset = offset + 4;
@@ -95,7 +104,7 @@ function decodeFrame(buffer) {
     data[i] = buffer[dataOffset + i] ^ mask[i % 4];
   }
 
-  return { opcode, payload: data, bytesConsumed: totalLen };
+  return { fin, opcode, payload: data, bytesConsumed: totalLen };
 }
 
 // ========== Configuration ==========
@@ -351,7 +360,7 @@ function openPrivateAppendFile(filePath) {
   }
 
   let fd = null;
-  const appendFlags = fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT | noFollow;
+  const appendFlags = fs.constants.O_RDWR | fs.constants.O_APPEND | fs.constants.O_CREAT | noFollow;
   try {
     if (!before) {
       try {
@@ -762,6 +771,9 @@ function handleUpgrade(req, socket) {
   let buffer = Buffer.alloc(0);
   let closed = false;
   let partialFrameTimer = null;
+  let fragmentedOpcode = null;
+  let fragmentedPayloads = [];
+  let fragmentedBytes = 0;
   clients.add(socket);
 
   const clearPartialFrameTimer = () => {
@@ -820,7 +832,36 @@ function handleUpgrade(req, socket) {
 
       switch (result.opcode) {
         case OPCODES.TEXT:
-          handleMessage(result.payload.toString());
+          if (fragmentedOpcode !== null) {
+            closeSocket(1002);
+            return;
+          }
+          if (result.fin) {
+            handleMessage(result.payload.toString());
+          } else {
+            fragmentedOpcode = OPCODES.TEXT;
+            fragmentedPayloads = [result.payload];
+            fragmentedBytes = result.payload.length;
+          }
+          break;
+        case OPCODES.CONTINUATION:
+          if (fragmentedOpcode === null) {
+            closeSocket(1002);
+            return;
+          }
+          fragmentedBytes += result.payload.length;
+          if (fragmentedBytes > MAX_FRAME_PAYLOAD_BYTES) {
+            closeSocket(1009);
+            return;
+          }
+          fragmentedPayloads.push(result.payload);
+          if (result.fin) {
+            const message = Buffer.concat(fragmentedPayloads, fragmentedBytes);
+            fragmentedOpcode = null;
+            fragmentedPayloads = [];
+            fragmentedBytes = 0;
+            handleMessage(message.toString());
+          }
           break;
         case OPCODES.CLOSE:
           closeSocket();
@@ -834,6 +875,7 @@ function handleUpgrade(req, socket) {
           closeSocket(1003);
           return;
       }
+      if (fragmentedOpcode !== null) armPartialFrameTimer();
     }
   });
 
@@ -866,7 +908,16 @@ function appendEvent(event) {
   try {
     const current = fs.fstatSync(fd);
     if (current.size + lineBytes > MAX_EVENTS_FILE_BYTES) {
+      const keepBytes = MAX_EVENTS_FILE_BYTES - lineBytes;
+      const existing = Buffer.alloc(Math.min(current.size, MAX_EVENTS_FILE_BYTES));
+      const bytesRead = fs.readSync(fd, existing, 0, existing.length, Math.max(0, current.size - existing.length));
+      let retained = existing.subarray(Math.max(0, bytesRead - keepBytes), bytesRead);
+      if (retained.length < bytesRead) {
+        const firstNewline = retained.indexOf(0x0a);
+        retained = firstNewline >= 0 ? retained.subarray(firstNewline + 1) : Buffer.alloc(0);
+      }
       fs.ftruncateSync(fd, 0);
+      if (retained.length > 0) fs.writeSync(fd, retained);
     }
     fs.writeSync(fd, line);
   } catch (e) {
@@ -894,8 +945,12 @@ function handleMessage(text) {
     ? logLine
     : JSON.stringify({ source: 'user-event', truncated: true });
   console.log(logOutput);
-  if (event && event.choice) {
-    appendEvent(event);
+  if (event && typeof event === 'object') {
+    if (event.choice) {
+      appendEvent(event);
+    } else if (event.type === 'choice' && event.value) {
+      appendEvent({ ...event, choice: event.value });
+    }
   }
 }
 

package/skills/brainstorming/scripts/start-server.ps1

@@ -67,7 +67,9 @@ $projectDir = ""
 $foreground = $false
 $forceBackground = $false
 $bindHost = "127.0.0.1"
+if ($env:BRAINSTORM_HOST) { $bindHost = $env:BRAINSTORM_HOST }
 $urlHost = ""
+if ($env:BRAINSTORM_URL_HOST) { $urlHost = $env:BRAINSTORM_URL_HOST }
 $idleTimeoutMinutes = ""
 
 for ($i = 0; $i -lt $args.Count; $i++) {
@@ -151,17 +153,34 @@ if ($env:CODEX_CI -and -not $foreground -and -not $forceBackground) {
     $foreground = $true
 }
 
-$sessionId = "$PID-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
+$baseSessionId = "$PID-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
 $brainstormRoot = ""
 if ($projectDir -ne "") {
     $brainstormRoot = Join-Path $projectDir ".superpowers/brainstorm"
+    # $PID is the invoking host process, so two starts in the same second from
+    # one pwsh session would resolve to the same id and die on the live
+    # session's redirected log file. Take the next free directory instead.
+    $sessionId = $baseSessionId
     $sessionDir = Join-Path $brainstormRoot $sessionId
+    $sessionSuffix = 2
+    while (Test-Path -LiteralPath $sessionDir) {
+        $sessionId = "$baseSessionId-$sessionSuffix"
+        $sessionDir = Join-Path $brainstormRoot $sessionId
+        $sessionSuffix++
+    }
     # Reuse the last bound port and session key so a restart keeps an
     # already-open browser tab connected to the same URL with a valid cookie.
     $env:BRAINSTORM_PORT_FILE = Join-Path $brainstormRoot ".last-port"
     $env:BRAINSTORM_TOKEN_FILE = Join-Path $brainstormRoot ".last-token"
 } else {
+    $sessionId = $baseSessionId
     $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+    $sessionSuffix = 2
+    while (Test-Path -LiteralPath $sessionDir) {
+        $sessionId = "$baseSessionId-$sessionSuffix"
+        $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+        $sessionSuffix++
+    }
     # $env: assignments persist in the invoking pwsh session; a stale project
     # token/port file from an earlier --project-dir run must not leak into an
     # ephemeral session (it would defeat key rotation and could overwrite the

package/skills/brainstorming/scripts/start-server.sh

@@ -23,8 +23,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR=""
 FOREGROUND="false"
 FORCE_BACKGROUND="false"
-BIND_HOST="127.0.0.1"
-URL_HOST=""
+BIND_HOST="${BRAINSTORM_HOST:-127.0.0.1}"
+URL_HOST="${BRAINSTORM_URL_HOST:-}"
 IDLE_TIMEOUT_MINUTES=""
 while [[ $# -gt 0 ]]; do
   case "$1" in

package/skills/executing-plans/SKILL.md

@@ -28,7 +28,11 @@ For each task:
 1. Mark as in_progress
 2. Follow each step exactly (plan has bite-sized steps)
 3. Run verifications as specified
-4. Mark as completed
+4. Mark as completed — the todo **and** the plan file: edit it and flip this
+   task's steps from `- [ ]` to `- [x]`. The plan is the artifact a human
+   reads to see where things stand, and nothing else in this skill writes
+   back to it. Leave a step unticked only when its deliverable does not exist
+   yet; never tick one you skipped.
 
 ### Step 3: Complete Development
 
@@ -62,3 +66,5 @@ After all tasks complete and verified:
 - Reference skills when plan says to
 - Stop when blocked, don't guess
 - Never start implementation on main/master branch without explicit user consent
+- Commits stay local — no push/pull/fetch unless the plan or your human partner says so. At each checkpoint glance at `git status -sb`: a branch tracking or ahead of a shared branch (main/dev/production) is a stop-and-fix, not a footnote
+- Never rewrite a shared branch (`git push --force*` to main/dev/production) to undo a mistake — a forward-only `git revert` is the only remedy you apply yourself; anything more is your human partner's call

package/skills/finishing-a-development-branch/SKILL.md

@@ -85,6 +85,14 @@ is theirs.
 
 ### Option 1: Merge Locally
 
+If the branch came from subagent-driven-development, commit the plan ledger's
+deferred findings first: carry every ledger line tagged `minor (deferred)`,
+`parked`, or `Ruling:` into
+`docs/superpowers/follow-ups/<plan-basename>.md` (append under a dated
+heading if the file already exists) and commit it to the branch before the
+merge — subagent-driven-development's Finish rule owns the details, and the
+file must land here so it survives the branch deletion.
+
 ```bash
 # Get main repo root for CWD safety
 MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
@@ -123,6 +131,13 @@ tooling — its CLI if one is available, or the creation URL most forges
 print when you push — following the repo's PR template and conventions if
 present, and report the URL to your human partner.
 
+If the branch came from subagent-driven-development, append the plan
+ledger's deferred findings to the PR description before reporting the URL —
+a "Deferred items" checklist carrying every ledger line tagged `minor
+(deferred)`, `parked`, or `Ruling:`, verbatim. Subagent-driven-development's
+Finish rule owns the details; the checklist must land here, where your human
+partner reviews.
+
 Keep the worktree — your human partner iterates on PR feedback there.
 
 ### Option 3: Keep As-Is

package/skills/subagent-driven-development/SKILL.md

@@ -87,8 +87,9 @@ digraph process {
     "More tasks remain?" [shape=diamond];
     "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
     "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
-    "Final review clean: delete this plan's workspace" [shape=box];
-    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+    "Use superpowers:finishing-a-development-branch" [shape=box];
+    "Finish path resolved: export deferred findings to its durable artifact" [shape=box];
+    "Delete this plan's workspace (only after the export; keep-as-is keeps it)" [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?";
@@ -116,8 +117,9 @@ digraph process {
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
     "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
     "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
-    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
-    "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
+    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Use superpowers:finishing-a-development-branch";
+    "Use superpowers:finishing-a-development-branch" -> "Finish path resolved: export deferred findings to its durable artifact";
+    "Finish path resolved: export deferred findings to its durable artifact" -> "Delete this plan's workspace (only after the export; keep-as-is keeps it)";
 }
 ```
 
@@ -142,14 +144,21 @@ a ledger file, not only in todos.
   line names your plan file, tasks with a `Task <N>: complete` line are DONE
   — do not re-dispatch them; resume at the first task without one. A task
   whose last line is a fix round is mid-loop: resume the loop at the next
-  round. A ledger whose first line names a different plan file — or a stray
+  round. A resumed controller also reads the ledger's `## Discoveries`
+  section: it holds what completed tasks found that the plan could not
+  know, and it is the source for clause (3) of the next dispatch. 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>`.
 - 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.
+  trust the ledger and `git log` over your own recollection. The ledger's
+  `## Discoveries` section is the same map for knowledge: what earlier tasks
+  found that the plan could not know. A resumed controller composes clause
+  (3) of every dispatch from that section, never from recollection of a
+  context it no longer has.
 - `git clean -fdx` will destroy the workspace (it's git-ignored scratch); if
   that happens, recover from `git log`.
 
@@ -272,9 +281,12 @@ and fix-round diffs need it.
   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
+  know — read them from the ledger's Discoveries section, not from your
+  memory of past reports: copy the entries the task's interfaces touch, in
+  full, and skip the rest; (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. When the brief is a contract
   (goal, success criteria, interfaces) rather than written-out code, item
   (3) also carries the elaboration the contract leaves to dispatch time:
@@ -290,7 +302,10 @@ and fix-round diffs need it.
   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.
+  touches, and the global constraints. Nothing else. A curated slice copied
+  from the Discoveries section is not pasted history — it is clause (3)
+  above, kept small enough to read in full because each entry is a delta
+  from the plan.
 - 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
@@ -366,9 +381,16 @@ needed.
   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.
-- **Reviewer inputs:** 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.
+- **Reviewer inputs:** the task reviewer gets four paths — the same brief
+  file, the report file, the review package, and a review file to write
+  to (brief `…/task-N-brief.md` → review `…/task-N-review.md`) — plus
+  the global constraints that bind the task.
+- **Review file:** the reviewer writes its full report there and returns
+  only verdicts, ⚠️ items, one line per Critical/Important finding, a
+  Minor count, and the path. Don't read the review file during the loop —
+  the final message is your decision surface; the detail is for fix
+  subagents. One exception: when you ledger a task's deferred minors, copy
+  each one-liner from the review file's Minor section.
 - 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
@@ -402,9 +424,12 @@ 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
+- Dispatch fix subagents for Critical and Important findings, passing the
+  review file path for the full detail. Record each task's Minor count,
+  review file path, and one ledger line per deferred minor copied from the
+  review file's Minor section (`Task <N>: minor (deferred): <one-liner>` —
+  the deferred-findings export greps these lines), and point the final
+  whole-branch review at those files 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
@@ -417,14 +442,16 @@ 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.
+verbatim, plus the review file path for the full detail. 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, the review 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
+Model Selection), with the brief path, the report-file path, the review
+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.
@@ -441,7 +468,8 @@ whole suite.
 (or `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell)
 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
+brief, the report file, the review file to append its verdicts to, 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
@@ -483,6 +511,27 @@ message as your other bookkeeping:
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
   tripped breaker
 
+Copy the task's Discoveries into the ledger in the same message, from the
+report's "Discoveries for later tasks" field: append a `### Task <N>`
+heading under the ledger's `## Discoveries` section (create the section on
+first use) with each discovery as one line, or `- None` when the field is
+empty. Keep it a delta from the plan: only what a later task needs and the
+plan could not know — corrections to the plan, negative results, resolved
+unknowns, interfaces discovered in the code. If it does not change what a
+later task does, it does not go in.
+
+In the same message, **edit the plan file and flip this task's steps from
+`- [ ]` to `- [x]`**. The plan is what a human reads to see where the work
+stands; the ledger is yours. Tie the two to this one event so they cannot
+drift — a plan left at 0 while its tasks are done and deployed reads as
+"nothing happened", and nothing downstream will catch it: the task reviewer
+sees a diff, the re-review sees findings, the final review sees the ledger.
+None of them ever opens the plan.
+
+Leave a step unticked only when its deliverable does not exist yet — a step
+that waits on someone else, or on an event that has not happened. Never tick
+a step you skipped.
+
 **On a skeleton-first plan,** write one plan-check line with the
 completion line. Re-read the remaining tasks against what this task
 actually established — interfaces as built, environment facts,
@@ -541,13 +590,45 @@ took on your human partner's behalf reach them — they read it and rework
 whatever you got wrong. A ruling that dies with the workspace was a decision
 made in secret.
 
-When the final whole-branch review is clean and its fixes are merged,
-delete this plan's workspace (`rm -rf <workspace>`) — the git history is
-the record now. Sibling directories belong to other plans; leave them
-alone.
+Rulings are not the only content that dies with the workspace. Findings you
+chose not to fix are the record of what was *not* done — git history cannot
+carry them, because git records what was done. So export them before
+anything is deleted: grep the progress ledger for its three finding tags
+
+```bash
+grep -E 'Ruling:|^(Task [0-9]+: )?(minor \(deferred\)|parked)' <workspace>/progress.md
+```
+
+and carry every matching line, verbatim, into a durable, human-reachable
+artifact. The chat roll-up does not satisfy this — scrollback, compaction,
+and session end all eat it. Where the artifact lives depends on how
+finishing-a-development-branch resolves (it carries the same obligation from
+its side):
+
+- **Option 2 (push and create PR):** append the lines to the PR description
+  under a "Deferred items" checklist. That is where your human partner
+  reviews, and checkboxes survive the merge.
+- **Option 1 (merge locally):** write them to
+  `docs/superpowers/follow-ups/<plan-basename>.md` — append under a dated
+  heading if a re-run under the same basename already created the file — and
+  commit the file to the branch before the merge so it survives the branch
+  deletion.
+- **Option 3 (keep as-is):** the workspace stays, so there is nothing to
+  export.
+- **Explicit discard:** your human partner asked to throw the work away, so
+  no export is required.
 
 Use superpowers:finishing-a-development-branch.
 
+When the finish path has resolved and its export exists — the checklist in
+the PR description, or the committed follow-ups file — delete this plan's
+workspace (`rm -rf <workspace>`), provided the final whole-branch review was
+clean and its fixes are merged. The export, not git history, is the record
+of the deferred findings. Sibling directories belong to other plans; leave
+them alone. On an explicit discard there is no export, but the workspace is
+deleted together with the branch — a ledger describing thrown-away work is
+a false record.
+
 ## Common Rationalizations
 
 | Excuse | Reality |
@@ -586,11 +667,12 @@ Implementer: [Later]
   - Self-review: Found I missed --force flag, added it
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
-Task reviewer: Spec ✅ - all requirements met, nothing extra.
-  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.
+[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
+Task reviewer: Spec ✅. Quality: Approved. Minor: 0.
+  Full report: task-1-review.md
 
 [Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]
+[Ledger: Discoveries — Task 1: hooks dir must be created before install; none other]
 
 Task 2: Recovery modes
 
@@ -601,22 +683,23 @@ Implementer: [No questions]
   - 8/8 tests passing
   - Committed
 
-[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
+[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path + review file]
 Task reviewer: Spec ❌:
   - Missing: Progress reporting (spec says "report every 100 items")
-  Issues (Important): Magic number (100)
+  Important: Magic number (100). Minor: 0. Full report: task-2-review.md
 
-[Fix round 1: resume the implementer with both findings]
+[Fix round 1: resume the implementer with the review file path]
 Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
   Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.
 
-[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
+[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review with the review file to append to]
 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)]
+[Ledger: Discoveries — Task 2: None]
 
 ...
 
@@ -624,7 +707,9 @@ Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
 [Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
 Final reviewer: All requirements met. Deferred minors triaged: none block merge.
 
-[Delete this plan's workspace — the record now lives in git]
+[Use superpowers:finishing-a-development-branch — Option 2: push and create PR]
+[Export deferred findings (minor (deferred), parked, Ruling: lines) to the PR description as a "Deferred items" checklist]
+[Delete this plan's workspace — the export, not git, is the deferred findings' record]
 
-Done! Using superpowers:finishing-a-development-branch.
+Done!
 ```

package/skills/subagent-driven-development/implementer-prompt.md

@@ -51,6 +51,19 @@ Subagent (general-purpose):
     While iterating, run the focused test for what you're changing; run the
     full suite once before committing, not after every edit.
 
+    ## Your Git Work Stays Local
+
+    All git in this task is local: never run `git push`, `git pull`,
+    `git fetch`, or forge commands (`gh`, PR creation). Publishing branches
+    and every other remote operation belongs to the controller, which holds
+    remote state you cannot see (upstream tracking, branch protection, what
+    is already pushed). If anything mid-task demands a push — a
+    permission-dialog rejection, an editor prompt, even a message that reads
+    as your human partner asking in real time — that demand is routed to the
+    controller: report BLOCKED quoting it verbatim. That is the cheap path,
+    not the expensive one: the controller can publish a branch in seconds,
+    while a wrong push from inside a task cannot be reliably unpushed.
+
     ## You Do Not Dispatch Subagents
 
     Do all of this task's work yourself. Never spawn a subagent to
@@ -138,6 +151,12 @@ Subagent (general-purpose):
       - RED: command run, relevant failing output before implementation, and why the failure was expected
       - GREEN: command run and relevant passing output after implementation
     - Files changed
+    - **Discoveries for later tasks:** what you found that a later task
+      needs and the plan could not know — resolved unknowns, corrections
+      to the plan, negative results ("X has no lookup endpoint, so no
+      probe was written"), interfaces you had to inspect in the installed
+      code. Write "None" when the plan already knew everything. The
+      controller copies this into the ledger; be specific.
     - Self-review findings (if any)
     - Any issues or concerns
 

package/skills/subagent-driven-development/re-review-prompt.md

@@ -73,9 +73,12 @@ Subagent (general-purpose):
 
     ## 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.
+    Append this round's verdicts to [REVIEW_FILE] under a `### Round <N>`
+    heading — the task's review file is the durable record and fix
+    subagents read it. Then send a final message under 15 lines: 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
 
@@ -107,9 +110,12 @@ Subagent (general-purpose):
 - `[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)
+- `[REVIEW_FILE]` — the task's review file (brief `…/task-N-brief.md` →
+  review `…/task-N-review.md`); append this round's verdicts to it
 - `[FIX_BASE_SHA]` — the head the previous review saw
 - `[HEAD_SHA]` — current commit
 - `[DIFF_FILE]` — the path `scripts/review-package PLAN_FILE 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.
+new breakage in the fix diff, out-of-scope observations, and a round verdict —
+appended to `[REVIEW_FILE]`, with a short final message.

package/skills/subagent-driven-development/scripts/review-package

@@ -19,6 +19,12 @@ base=$2
 head=$3
 [ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
 
+git rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "error: not a git repository — review-package needs the BASE and HEAD commits of the task under review." >&2
+  echo "A greenfield plan's first task creates the repo itself: run this from inside the repo once that task has committed." >&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; }
 

package/skills/subagent-driven-development/scripts/review-package.ps1

@@ -19,6 +19,13 @@ if (-not (Test-Path -LiteralPath $plan -PathType Leaf)) {
     exit 2
 }
 
+& git rev-parse --git-dir *> $null
+if ($LASTEXITCODE -ne 0) {
+    [Console]::Error.WriteLine("error: not a git repository — review-package needs the BASE and HEAD commits of the task under review.")
+    [Console]::Error.WriteLine("A greenfield plan's first task creates the repo itself: run this from inside the repo once that task has committed.")
+    exit 2
+}
+
 & git rev-parse --verify --quiet $base *> $null
 if ($LASTEXITCODE -ne 0) {
     [Console]::Error.WriteLine("bad BASE: $base")