superpowers-mcp 6.3.6 → 6.3.7

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")

package/skills/subagent-driven-development/scripts/sdd-workspace

@@ -23,6 +23,10 @@
 # Single source of truth for the workspace location, so task-brief and
 # review-package cannot drift to different directories.
 #
+# A greenfield plan's first task is often "create the repo", so there is no
+# repo root to resolve yet: fall back to the current directory rather than
+# failing, since that task is exactly the one needing a brief.
+#
 # Usage: sdd-workspace PLAN_FILE
 set -euo pipefail
 
@@ -38,7 +42,10 @@ 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)
+if ! root=$(git rev-parse --show-toplevel 2>/dev/null); then
+  root=$PWD
+  echo "sdd-workspace: no git repository yet, using $root/.superpowers/sdd until this plan's first task creates one" >&2
+fi
 root=$(CDPATH= cd -- "$root" && pwd -P)
 base="$root/.superpowers/sdd"
 

package/skills/subagent-driven-development/scripts/sdd-workspace.ps1

@@ -7,6 +7,10 @@
 # plan in the same working tree can never read or overwrite another plan's
 # artifacts.
 #
+# A greenfield plan's first task is often "create the repo", so there is no
+# repo root to resolve yet: fall back to the current directory rather than
+# failing, since that task is exactly the one needing a brief.
+#
 # Usage: ./sdd-workspace.ps1 PLAN_FILE
 
 $ErrorActionPreference = "Stop"
@@ -28,8 +32,21 @@ if ([string]::IsNullOrEmpty($slug) -or $slug -eq "." -or $slug -eq "..") {
     exit 2
 }
 
-$root = (& git rev-parse --show-toplevel).Trim()
-$base = Join-Path $root ".superpowers/sdd"
+$root = $null
+try {
+    # Collect all output without an early-terminating pipeline: a
+    # Select-Object -First teardown can leave $LASTEXITCODE stale.
+    $rootOutput = @(& git rev-parse --show-toplevel 2>$null)
+    if ($LASTEXITCODE -eq 0 -and $rootOutput.Count -gt 0 -and -not [string]::IsNullOrWhiteSpace($rootOutput[0])) {
+        $root = ([string]$rootOutput[0]).Trim()
+    }
+} catch {
+    $root = $null
+}
+if ([string]::IsNullOrWhiteSpace($root)) {
+    $root = (Get-Location).Path
+    [Console]::Error.WriteLine("sdd-workspace.ps1: no git repository yet, using $root/.superpowers/sdd until this plan's first task creates one")
+}
 
 function Get-PhysicalDirectoryPath($path) {
     if (-not (Test-Path -LiteralPath $path)) { return $path }
@@ -59,6 +76,10 @@ if ([string]::IsNullOrEmpty($planParent)) { $planParent = "." }
 
 $planDir = Get-PhysicalDirectoryPath $planParent
 $rootPhys = Get-PhysicalDirectoryPath $root
+# Build $base from the physical root so the greenfield fallback (cwd, which
+# may be a symlinked path such as macOS /var) prints the same location as
+# the later git-resolved call.
+$base = Join-Path $rootPhys ".superpowers/sdd"
 
 $planAbs = (Join-Path $planDir $planLeaf) -replace '\\', '/'
 $rootNorm = $rootPhys -replace '\\', '/'

package/skills/subagent-driven-development/task-reviewer-prompt.md

@@ -134,13 +134,27 @@ Subagent (general-purpose):
 
     Your report should point at evidence: file:line references for every
     finding and for any check you would otherwise answer with a bare
-    "yes." A tight report that cites lines gives the controller everything
-    it needs.
-
-    Your final message is the report itself: begin directly with the
-    spec-compliance verdict. Every line is a verdict, a finding with
-    file:line, or a check you ran — no preamble, no process narration,
-    no closing summary.
+    "yes." A tight report that cites lines gives the fix subagent
+    everything it needs.
+
+    ## Report Format
+
+    Write your full report to [REVIEW_FILE] using the Output Format
+    below: verdicts, strengths, every finding with file:line, and any
+    check you ran outside the diff. Fix subagents read this file — it is
+    the only place your detail survives.
+
+    Then report back with ONLY (under 15 lines — the detail lives in the
+    review file):
+    - **Spec:** ✅ | ❌ — if ❌, one line per missing/extra/misunderstood
+      item (file:line + summary)
+    - **⚠️ Cannot verify from diff:** [items the controller must resolve
+      itself — always in this message, never only in the file]
+    - **Quality:** Approved | Needs fixes
+    - One line per Critical/Important finding: file:line + what's wrong,
+      with any plan-mandated finding marked (the human adjudicates those)
+    - Minor findings: count only
+    - The review file path
 
     ## Calibration
 
@@ -158,7 +172,7 @@ Subagent (general-purpose):
     Acknowledge what was done well before listing issues — accurate praise
     helps the implementer trust the rest of the feedback.
 
-    ## Output Format
+    ## Output Format (the review file)
 
     ### Spec Compliance
 
@@ -202,6 +216,10 @@ Subagent (general-purpose):
 - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
   package to (`scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, prints the unique
   path it wrote; the package never enters the controller's context)
+- `[REVIEW_FILE]` — REQUIRED: the file the reviewer writes its full report
+  to; name it after the brief (brief `…/task-N-brief.md` → review
+  `…/task-N-review.md`). Re-reviews append to the same file.
 
-**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
-(Critical/Important/Minor), Task quality verdict
+**Reviewer returns:** full report in `[REVIEW_FILE]`; final message under
+15 lines — Spec verdict (✅/❌/⚠️), Quality verdict, Critical/Important
+findings one line each, Minor count, review file path

package/skills/systematic-debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - including when you say "systematic debug", "debug this properly", or "find the root cause first"; for driving new behavior test-first, use test-driven-development instead
 ---
 
 # Systematic Debugging

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

@@ -1,6 +1,6 @@
 ---
 name: test-driven-development
-description: Use when implementing any feature or bugfix, before writing implementation code
+description: Use when implementing any feature or bugfix, before writing implementation code - including when you say "tdd", "tdd workflow", "write the test first", or "red green refactor"; for diagnosing an existing defect, use systematic-debugging instead
 ---
 
 # Test-Driven Development (TDD)
@@ -68,6 +68,27 @@ digraph tdd_cycle {
 }
 ```
 
+### Characterization Test for a Behavior-Preserving Refactor
+
+This extends the [upstream characterization guidance](writing-good-tests.md#principle-1-name-the-break)
+to behavior-preserving refactors of your own code.
+
+Normal RED applies when behavior should change. If observable behavior must
+remain unchanged, establish a characterization guard before refactoring:
+
+1. Name the behavior and a relevant production mutation that should make the
+   test fail.
+2. Write the test and observe the existing behavior pass.
+3. Require `git diff HEAD -- <production-paths>` to be empty before mutating.
+   If those paths have existing changes, stop without discarding them.
+   Make the mutation and verify the expected failure. If the test still
+   passes, strengthen or replace it and repeat.
+4. Restore only the mutated production paths from VCS with
+   `git restore --source=HEAD --worktree -- <production-paths>`. Require
+   `git diff --exit-code HEAD -- <production-paths>` to succeed with an empty
+   diff, then verify green with the characterization test retained.
+5. Refactor while staying green.
+
 ### RED - Write Failing Test
 
 Write one minimal test showing what should happen.
@@ -123,7 +144,10 @@ Confirm:
 - Failure message is expected
 - Fails because feature missing (not typos)
 
-**Test passes?** You're testing existing behavior. Fix test.
+**Test passes?** If observable behavior must remain unchanged, follow the
+[characterization guard](#characterization-test-for-a-behavior-preserving-refactor)
+before refactoring. If behavior should change, you're testing existing
+behavior. Fix test.
 
 **Test errors?** Fix error, re-run until it fails correctly.
 
@@ -239,7 +263,7 @@ When writing or changing any test, read [writing-good-tests.md](writing-good-tes
 
 - Code before test
 - Test after implementation
-- Test passes immediately
+- Test for new or changed behavior passes immediately
 - Can't explain why test failed
 - Tests added "later"
 - Rationalizing "just this once"

package/skills/test-driven-development/writing-good-tests.md

@@ -62,6 +62,10 @@ getters, constants, and trivial forwarding earn tests only when they
 validate, normalize, default, derive, enforce, or cause side effects —
 otherwise assert the first consumer-visible result that depends on them.
 
+For a behavior-preserving refactor of your own code, establish the
+[characterization guard](SKILL.md#characterization-test-for-a-behavior-preserving-refactor)
+before changing production structure.
+
 ### Gate Function
 
 ```
@@ -156,6 +160,9 @@ process costs maintenance forever.
 
 ## The Mutation Check
 
+For a pre-refactor characterization guard, run the actual mutation and
+VCS restoration procedure in the TDD skill, including its empty-diff check.
+
 Before finishing, mentally mutate the production code; at least one test
 should fail for each realistic mutation: