superpowers-mcp 6.4.7 → 6.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.es.md +25 -3
  2. package/README.hi.md +25 -3
  3. package/README.ja.md +25 -3
  4. package/README.ko.md +25 -3
  5. package/README.md +26 -4
  6. package/README.pt-BR.md +25 -3
  7. package/README.zh-TW.md +25 -3
  8. package/docs/maintainers/upstream-sync.md +4 -0
  9. package/docs/skill-compositions.es.md +1 -1
  10. package/docs/skill-compositions.hi.md +1 -1
  11. package/docs/skill-compositions.ja.md +1 -1
  12. package/docs/skill-compositions.ko.md +1 -1
  13. package/docs/skill-compositions.md +1 -1
  14. package/docs/skill-compositions.pt-BR.md +1 -1
  15. package/docs/skill-compositions.zh-TW.md +1 -1
  16. package/out/server.js +148 -109
  17. package/out/setup-runner.js +50 -37
  18. package/out/setup.js +50 -37
  19. package/package.json +6 -5
  20. package/scripts/copy-skills.js +65 -6
  21. package/scripts/install.ps1 +11 -2
  22. package/scripts/install.sh +7 -1
  23. package/scripts/run-tests.js +126 -13
  24. package/scripts/setup.js +100 -11
  25. package/scripts/upstream-drift.js +31 -8
  26. package/skills/brainstorming/SKILL.md +24 -2
  27. package/skills/brainstorming/builder-check-prompt.md +23 -0
  28. package/skills/brainstorming/scripts/helper.js +2 -1
  29. package/skills/brainstorming/scripts/server.cjs +38 -10
  30. package/skills/brainstorming/scripts/start-server.ps1 +7 -3
  31. package/skills/brainstorming/scripts/start-server.sh +30 -6
  32. package/skills/brainstorming/scripts/stop-server.ps1 +10 -4
  33. package/skills/brainstorming/scripts/stop-server.sh +16 -10
  34. package/skills/diagnosing-superpowers/SKILL.md +6 -3
  35. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  36. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  37. package/skills/executing-plans/SKILL.md +18 -12
  38. package/skills/executing-plans/scripts/task-done +14 -5
  39. package/skills/executing-plans/scripts/task-done.ps1 +34 -12
  40. package/skills/executing-plans/scripts/task-start +16 -4
  41. package/skills/executing-plans/scripts/task-start.ps1 +9 -4
  42. package/skills/requesting-code-review/SKILL.md +1 -1
  43. package/skills/subagent-driven-development/SKILL.md +24 -15
  44. package/skills/subagent-driven-development/re-review-prompt.md +1 -1
  45. package/skills/subagent-driven-development/scripts/review-package +23 -17
  46. package/skills/subagent-driven-development/scripts/review-package.ps1 +41 -27
  47. package/skills/subagent-driven-development/scripts/sdd-repo +44 -0
  48. package/skills/subagent-driven-development/scripts/sdd-repo.ps1 +74 -0
  49. package/skills/subagent-driven-development/scripts/sdd-workspace +20 -11
  50. package/skills/subagent-driven-development/scripts/sdd-workspace.ps1 +38 -27
  51. package/skills/subagent-driven-development/scripts/task-brief +74 -11
  52. package/skills/subagent-driven-development/scripts/task-brief.ps1 +89 -17
  53. package/skills/subagent-driven-development/task-reviewer-prompt.md +2 -4
  54. package/skills/systematic-debugging/SKILL.md +2 -2
  55. package/skills/writing-skills/render-graphs.js +4 -3
  56. package/skills/brainstorming/spec-document-reviewer-prompt.md +0 -50
  57. package/skills/systematic-debugging/CREATION-LOG.md +0 -119
  58. package/skills/systematic-debugging/test-academic.md +0 -14
  59. package/skills/systematic-debugging/test-pressure-1.md +0 -58
  60. package/skills/systematic-debugging/test-pressure-2.md +0 -68
  61. package/skills/systematic-debugging/test-pressure-3.md +0 -69
@@ -29,18 +29,22 @@ IDLE_TIMEOUT_MINUTES=""
29
29
  while [[ $# -gt 0 ]]; do
30
30
  case "$1" in
31
31
  --project-dir)
32
+ if [[ -z "${2:-}" || "$2" == --* ]]; then echo '{"error": "Missing value for --project-dir"}'; exit 1; fi
32
33
  PROJECT_DIR="$2"
33
34
  shift 2
34
35
  ;;
35
36
  --host)
37
+ if [[ -z "${2:-}" || "$2" == --* ]]; then echo '{"error": "Missing value for --host"}'; exit 1; fi
36
38
  BIND_HOST="$2"
37
39
  shift 2
38
40
  ;;
39
41
  --url-host)
42
+ if [[ -z "${2:-}" || "$2" == --* ]]; then echo '{"error": "Missing value for --url-host"}'; exit 1; fi
40
43
  URL_HOST="$2"
41
44
  shift 2
42
45
  ;;
43
46
  --idle-timeout-minutes)
47
+ if [[ -z "${2:-}" || "$2" == --* ]]; then echo '{"error": "Missing value for --idle-timeout-minutes"}'; exit 1; fi
44
48
  IDLE_TIMEOUT_MINUTES="$2"
45
49
  shift 2
46
50
  ;;
@@ -57,7 +61,7 @@ while [[ $# -gt 0 ]]; do
57
61
  shift
58
62
  ;;
59
63
  *)
60
- echo "{\"error\": \"Unknown argument: $1\"}"
64
+ echo '{"error": "Unknown argument"}'
61
65
  exit 1
62
66
  ;;
63
67
  esac
@@ -130,19 +134,39 @@ fi
130
134
  # everything this script and the server create owner-only.
131
135
  umask 077
132
136
 
133
- # Generate unique session directory
134
- SESSION_ID="$$-$(date +%s)"
137
+ # Generate unique session directory. $PID plus seconds collide when two starts
138
+ # share a second from one shell, so take the next free directory (mirror
139
+ # start-server.ps1) using atomic mkdir without -p plus a suffix retry loop.
140
+ BASE_SESSION_ID="$$-$(date +%s)"
141
+ SESSION_ID="$BASE_SESSION_ID"
142
+ SESSION_SUFFIX=2
135
143
 
136
144
  if [[ -n "$PROJECT_DIR" ]]; then
137
- SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
138
145
  # Reuse the last bound port and session key so a restart keeps an
139
146
  # already-open browser tab connected to the same URL with a valid cookie.
140
147
  export BRAINSTORM_PORT_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-port"
141
148
  export BRAINSTORM_TOKEN_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-token"
142
- else
143
- SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
149
+ mkdir -p "${PROJECT_DIR}/.superpowers/brainstorm" || { echo '{"error": "Failed to create brainstorm session directory"}'; exit 1; }
144
150
  fi
145
151
 
152
+ while true; do
153
+ if [[ -n "$PROJECT_DIR" ]]; then
154
+ SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
155
+ else
156
+ SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
157
+ fi
158
+ if mkdir "$SESSION_DIR" 2>/dev/null; then
159
+ break
160
+ fi
161
+ # mkdir failed for another reason (e.g. permission) — not a collision.
162
+ if [[ ! -e "$SESSION_DIR" ]]; then
163
+ echo '{"error": "Failed to create brainstorm session directory"}'
164
+ exit 1
165
+ fi
166
+ SESSION_ID="${BASE_SESSION_ID}-${SESSION_SUFFIX}"
167
+ SESSION_SUFFIX=$((SESSION_SUFFIX + 1))
168
+ done
169
+
146
170
  STATE_DIR="${SESSION_DIR}/state"
147
171
  PID_FILE="${STATE_DIR}/server.pid"
148
172
  LOG_FILE="${STATE_DIR}/server.log"
@@ -17,10 +17,11 @@ $serverIdFile = Join-Path $stateDir "server-instance-id"
17
17
  function Mark-Stopped {
18
18
  param([string]$Reason)
19
19
  Remove-Item -LiteralPath (Join-Path $stateDir "server-info") -Force -ErrorAction SilentlyContinue
20
- [pscustomobject]@{
20
+ $stoppedJson = ([pscustomobject]@{
21
21
  reason = $Reason
22
22
  timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
23
- } | ConvertTo-Json -Compress | Set-Content -Path (Join-Path $stateDir "server-stopped") -Encoding utf8
23
+ } | ConvertTo-Json -Compress)
24
+ [System.IO.File]::WriteAllText((Join-Path $stateDir "server-stopped"), $stoppedJson + [Environment]::NewLine, [System.Text.UTF8Encoding]::new($false))
24
25
  }
25
26
 
26
27
  function Read-ExpectedServerId {
@@ -94,8 +95,13 @@ if (Test-Path -LiteralPath $pidFile) {
94
95
  Start-Sleep -Milliseconds 100
95
96
  }
96
97
  if (Get-Process -Id $serverPid -ErrorAction SilentlyContinue) {
97
- Stop-Process -Id $serverPid -Force -ErrorAction SilentlyContinue
98
- Start-Sleep -Milliseconds 100
98
+ # Re-verify identity immediately before -Force escalation so a PID
99
+ # reuse between the graceful stop and now cannot kill an unrelated
100
+ # process. Skip on mismatch.
101
+ if ((Test-BrainstormServer -ProcessId $serverPid) -and ((Get-ProcessStartToken -ProcessId $serverPid) -eq $startToken)) {
102
+ Stop-Process -Id $serverPid -Force -ErrorAction SilentlyContinue
103
+ Start-Sleep -Milliseconds 100
104
+ }
99
105
  }
100
106
  if (Get-Process -Id $serverPid -ErrorAction SilentlyContinue) {
101
107
  [pscustomobject]@{ status = "failed"; error = "process still running" } | ConvertTo-Json -Compress
@@ -119,12 +119,16 @@ if [[ -f "$PID_FILE" ]]; then
119
119
  sleep 0.1
120
120
  done
121
121
 
122
- # If still running, escalate to SIGKILL
122
+ # If still running, escalate to SIGKILL — but re-verify identity
123
+ # immediately before signalling so a PID reuse between the graceful kill
124
+ # and now cannot SIGKILL an unrelated process. Skip on mismatch.
123
125
  if kill -0 "$pid" 2>/dev/null; then
124
- kill -9 "$pid" 2>/dev/null || true
126
+ if is_brainstorm_server "$pid" && [[ "$(process_start_token "$pid")" == "$start_token" ]]; then
127
+ kill -9 "$pid" 2>/dev/null || true
125
128
 
126
- # Give SIGKILL a moment to take effect
127
- sleep 0.1
129
+ # Give SIGKILL a moment to take effect
130
+ sleep 0.1
131
+ fi
128
132
  fi
129
133
 
130
134
  if kill -0 "$pid" 2>/dev/null; then
@@ -135,12 +139,14 @@ if [[ -f "$PID_FILE" ]]; then
135
139
  rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
136
140
  mark_stopped "stop-server.sh"
137
141
 
138
- # Only delete ephemeral /tmp directories. Resolve both paths canonically
139
- # (cd + pwd -P, like stop-server.ps1) so a session dir such as
140
- # "/tmp/../home/user/project" can't trick the prefix check into deleting
141
- # a directory outside the temp root. (Plain variables: this code runs at
142
- # top level, where `local` is a syntax error on bash 3.2 / macOS.)
143
- tmp_root="$(cd /tmp 2>/dev/null && pwd -P || true)"
142
+ # Only delete ephemeral temp directories. Honor $TMPDIR when set (macOS/
143
+ # Linux ephemeral sessions live under it); fall back to /tmp. Resolve both
144
+ # paths canonically (cd + pwd -P, like stop-server.ps1) so a session dir
145
+ # such as "/tmp/../home/user/project" can't trick the prefix check into
146
+ # deleting a directory outside the temp root. (Plain variables: this code
147
+ # runs at top level, where `local` is a syntax error on bash 3.2 / macOS.)
148
+ tmp_base="${TMPDIR:-/tmp}"
149
+ tmp_root="$(cd "$tmp_base" 2>/dev/null && pwd -P || true)"
144
150
  resolved="$(cd "$SESSION_DIR" 2>/dev/null && pwd -P || true)"
145
151
  if [[ -n "$tmp_root" && -n "$resolved" && "$resolved" == "$tmp_root/"* ]]; then
146
152
  rm -rf "$resolved"
@@ -50,8 +50,11 @@ Create a todo per step. Steps 5–7 run only on their stated condition.
50
50
  `references/github-issues.md`. Show matches and suggest adding the
51
51
  report to the closest. If none match, fill `templates/issue.md`, write
52
52
  it to the workspace, show the exact text, and create the issue only
53
- after approval. `gh` cannot attach files; if a bundle exists, give
54
- your partner its path to attach in the browser.
53
+ after approval. The required Human-authored summary must be your
54
+ partner's own words: ask them for it, paste it as written, and ask them
55
+ to trim it rather than editing it if it exceeds 200 words. Do not file
56
+ while that field is a placeholder. `gh` cannot attach files; if a bundle
57
+ exists, give your partner its path to attach in the browser.
55
58
  6. **Export** — only when your partner asks for a bundle; never build one
56
59
  unprompted. If the intake goal was a bug report, say once that a
57
60
  scrubbed bundle is available on request, then wait. Ask the redaction
@@ -100,7 +103,7 @@ yourself in step 3 and which findings to lead with in the verdict.
100
103
  partner either.
101
104
  - **Approval gates.** No archive before your partner has seen the scrub
102
105
  log and file list. No issue or comment before they approve the exact
103
- text.
106
+ text, and none while the Human-authored summary is a placeholder.
104
107
  - **Intake before analysis.** Nothing in steps 2–7 starts until your
105
108
  partner has answered. If they are away, write the questions and stop.
106
109
  A statement you reconstructed for them is not an answer. An
@@ -36,11 +36,11 @@ labels land only for collaborators; the template footer still marks the
36
36
  issue as skill-filed. `gh` cannot attach files: give your partner the
37
37
  bundle path to attach through the browser after the issue exists.
38
38
 
39
- Without `gh`, hand over a prefilled link on the `diagnosis_report.md`
40
- template, which applies both labels for any reporter:
39
+ Without `gh`, hand over a prefilled link on the `bug_report.md` template,
40
+ which applies the `bug` label for any reporter:
41
41
 
42
42
  ```
43
- https://github.com/obra/superpowers/issues/new?template=diagnosis_report.md&title=<url-encoded title>&body=<url-encoded body>
43
+ https://github.com/obra/superpowers/issues/new?template=bug_report.md&title=<url-encoded title>&body=<url-encoded body>
44
44
  ```
45
45
 
46
46
  GitHub rejects URLs over about 8,000 characters; past that, send the link
@@ -2,6 +2,20 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
2
2
 
3
3
  - [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
4
4
 
5
+ ## Who's filing this report? (required)
6
+
7
+ <model and harness of this session>, filing on behalf of <how your
8
+ partner wants to be named, or "my human partner">, who asked: "<their
9
+ request from this session that led to the diagnosis or the issue,
10
+ scrubbed>"
11
+
12
+ ## Human-authored summary (required, under 200 words)
13
+
14
+ <Your partner's own words on what went wrong and what should have
15
+ happened, pasted as written. Ask for them; a placeholder here means the
16
+ issue is not ready to file. If they run long, ask them to trim rather
17
+ than editing their words.>
18
+
5
19
  ## Environment (required)
6
20
 
7
21
  | Field | Value | Provenance / supporting evidence |
@@ -17,8 +31,12 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
17
31
 
18
32
  - [ ] I confirmed this issue does not occur without Superpowers installed
19
33
 
20
- The reporter has not tried reproducing without superpowers. Evidence for
21
- involvement is below; it does not establish cause.
34
+ How I verified that this issue does not reproduce without Superpowers:
35
+ <"Not tried", or what your partner ran without Superpowers and what
36
+ happened, with the transcript path if there is one. Tick the box above
37
+ only when a transcript shows the problem did not recur.>
38
+
39
+ Evidence for involvement is below; it does not establish cause.
22
40
 
23
41
  ## What happened?
24
42
 
@@ -47,5 +65,6 @@ Superpowers involvement per the diagnosis report: <possible | likely>, with
47
65
  evidence at <transcript lines>. This report does not propose a fix.
48
66
 
49
67
  ---
50
- Filed with the `diagnosing-superpowers` skill. Model, harness, harness
51
- version, and installed plugins are listed above.
68
+ Filed with the `diagnosing-superpowers` skill. The filing model and
69
+ harness are under "Who's filing"; the diagnosed session's model, harness,
70
+ versions, and plugins are in the Environment table.
@@ -125,11 +125,15 @@ and the new one resumes from the same ledger.
125
125
  - Each plan owns a workspace: at skill start, run
126
126
  `bash ../subagent-driven-development/scripts/sdd-workspace PLAN_FILE`
127
127
  (or `../subagent-driven-development/scripts/sdd-workspace.ps1 PLAN_FILE`
128
- on Windows PowerShell) — it
129
- prints the plan's git-ignored directory
128
+ on Windows PowerShell) by its absolute path, from the working tree you're
129
+ executing in — it prints the plan's git-ignored directory
130
130
  (`<repo-root>/.superpowers/sdd/<plan-basename>/`), home to every
131
131
  artifact for THIS plan: ledger, briefs, review packages. Another plan's
132
- directory is never yours to read or write.
132
+ directory is never yours to read or write. These helpers use the current
133
+ directory's working tree, not the plan's location; run them from the tree
134
+ you're executing in (or use `-C DIR` where supported). They fail closed
135
+ outside a repository. For a new project, initialize Git first and make an
136
+ initial commit before `task-start` records BASE.
133
137
  - Check for this plan's ledger at `<workspace>/progress.md`. If its first
134
138
  line names your plan file, tasks with a `Task <N>: complete` line are
135
139
  DONE — do not redo them; resume at the first task without one. Their
@@ -171,10 +175,10 @@ in the workspace and read its tail; read a brief, not the whole plan.
171
175
 
172
176
  ### 1. Take the task
173
177
 
174
- - Run this skill's `bash scripts/task-start PLAN_FILE N` (or
175
- `scripts/task-start.ps1 PLAN_FILE N` on Windows PowerShell). It prints
176
- the brief path and BASE (the commit the task's range is cut from) in
177
- one call.
178
+ - Run this skill's `bash scripts/task-start PLAN_FILE TASK_ID` (or
179
+ `scripts/task-start.ps1 PLAN_FILE TASK_ID` on Windows PowerShell) by its
180
+ absolute path, from the working tree you're executing in. It prints the
181
+ brief path and BASE (the commit the task's range is cut from) in one call.
178
182
  Read the brief for every task, including ones you remember from setup:
179
183
  what you remember is a summary, the brief has the exact values,
180
184
  signatures, and test cases.
@@ -227,9 +231,10 @@ the claim. If any item is missing, the task is not complete: finish it.
227
231
 
228
232
  ### 4. Complete the task
229
233
 
230
- Run this skill's `bash scripts/task-done PLAN_FILE N BASE -- <test command>`
231
- (or `scripts/task-done.ps1 PLAN_FILE N BASE -- <test command>` on Windows
232
- PowerShell) with the test command the brief names for the whole task. It runs the
234
+ Run this skill's `bash scripts/task-done PLAN_FILE TASK_ID BASE -- <test command>`
235
+ (or `scripts/task-done.ps1 PLAN_FILE TASK_ID BASE -- <test command>` on Windows
236
+ PowerShell) by its absolute path, from the working tree you're executing in,
237
+ with the test command the brief names for the whole task. It runs the
233
238
  tests, keeps the full output in the workspace, prints the tail, and — only
234
239
  if they pass — appends the completion line to the ledger:
235
240
 
@@ -246,8 +251,9 @@ deliverable does not exist yet; never tick one you skipped.
246
251
 
247
252
  Run `bash ../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD`
248
253
  (or `../subagent-driven-development/scripts/review-package.ps1 PLAN_FILE MERGE_BASE HEAD`
249
- on Windows PowerShell; MERGE_BASE = the commit the branch started from, e.g.
250
- `git merge-base main HEAD`) and review from the file it prints.
254
+ on Windows PowerShell) by its absolute path, from the working tree you're
255
+ executing in (MERGE_BASE = the commit the branch started from, e.g.
256
+ `git merge-base main HEAD`), and review from the file it prints.
251
257
 
252
258
  **With a subagent tool:** dispatch the reviewer on the most capable
253
259
  available model — the whole-branch review is a judgment task — using
@@ -4,23 +4,29 @@
4
4
  # only if the command succeeded — append the completion line to the ledger.
5
5
  # A failing command records nothing: the task is not complete.
6
6
  #
7
- # Usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]
7
+ # Usage: task-done PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]
8
8
  # BASE is the SHA task-start printed; the completion line records BASE..HEAD.
9
9
  # Exit: the test command's exit status.
10
10
  set -euo pipefail
11
11
 
12
12
  if [ $# -lt 5 ] || [ "$4" != "--" ]; then
13
- echo "usage: task-done PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]" >&2
13
+ echo "usage: task-done PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]" >&2
14
14
  exit 2
15
15
  fi
16
16
 
17
17
  plan=$1
18
18
  n=$2
19
19
  base=$3
20
+ if ! [[ "$n" =~ ^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$ && "$n" =~ [0-9] ]]; then
21
+ echo "usage: task-done PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]" >&2
22
+ exit 2
23
+ fi
20
24
  shift 4
21
25
  sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
22
26
 
23
- git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
27
+ # Use the same repository as the plan workspace and require a valid HEAD.
28
+ repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit)
29
+ git -C "$repo" rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
24
30
 
25
31
  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
26
32
  # strip Unix exec bits when unpacking marketplace packages (#2040).
@@ -29,10 +35,13 @@ log="$dir/task-${n}-tests.log"
29
35
  ledger="$dir/progress.md"
30
36
 
31
37
  # Render the command the way a person would type it, for the ledger line.
38
+ # Single-quote anything outside a safe allowlist so $,`,\,(),<>,#,*,?[,quotes
39
+ # and newlines can never break or inject into the ledger line; an embedded '
40
+ # is escaped by doubling it inside the single quotes.
32
41
  cmd=""
33
42
  for a in "$@"; do
34
43
  case "$a" in
35
- *[[:space:]\"\;\|\&]*) cmd="$cmd '$a'" ;;
44
+ ''|*[!a-zA-Z0-9_@%+=:,./-]*) esc=$(printf '%s' "$a" | sed "s/'/'\\\\''/g"); cmd="$cmd '$esc'" ;;
36
45
  *) cmd="$cmd $a" ;;
37
46
  esac
38
47
  done
@@ -50,6 +59,6 @@ fi
50
59
  last=$(grep -v '^[[:space:]]*$' "$log" | tail -n 1 || true)
51
60
  [ -n "$last" ] || last="(no output)"
52
61
  [ -f "$ledger" ] || printf '# SDD ledger — plan: %s\n' "$plan" > "$ledger"
53
- line="Task $n: complete (commits $(git rev-parse --short=7 "$base")..$(git rev-parse --short=7 HEAD), tests: $cmd → $last)"
62
+ line="Task $n: complete (commits $(git -C "$repo" rev-parse --short=7 "$base")..$(git -C "$repo" rev-parse --short=7 HEAD), tests: $cmd → $last)"
54
63
  printf '%s\n' "$line" >> "$ledger"
55
64
  echo "ledger: $line"
@@ -4,35 +4,54 @@
4
4
  # only if the command succeeded — append the completion line to the ledger.
5
5
  # A failing command records nothing: the task is not complete.
6
6
  #
7
- # Usage: ./task-done.ps1 PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]
7
+ # Usage: ./task-done.ps1 PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]
8
8
  # BASE is the SHA task-start printed; the completion line records BASE..HEAD.
9
9
  # Exit: the test command's exit status.
10
10
 
11
11
  $ErrorActionPreference = "Stop"
12
12
 
13
13
  if ($args.Count -lt 4) {
14
- [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]")
14
+ [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]")
15
15
  exit 2
16
16
  }
17
17
 
18
18
  $plan = $args[0]
19
19
  $n = $args[1]
20
20
  $base = $args[2]
21
+ if ($n -notmatch '^(?=.*[0-9])[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$') {
22
+ [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]")
23
+ exit 2
24
+ }
21
25
  # PowerShell consumes an unquoted `--` as its own end-of-parameters marker,
22
26
  # so the documented `... BASE -- CMD` arrives here WITHOUT the separator; a
23
27
  # quoted "--" survives and is skipped below. Unlike the sh twin, this port
24
- # therefore cannot reject a call that genuinely omits the separator.
25
- $cmdArgs = @($args[3..($args.Count - 1)])
26
- if ($cmdArgs[0] -eq "--") {
28
+ # therefore cannot reject a call that genuinely omits the separator: a missing
29
+ # separator is treated as `... BASE CMD...` gracefully.
30
+ $cmdArgs = @()
31
+ if ($args.Count -gt 3) {
32
+ $cmdArgs = @($args[3..($args.Count - 1)])
33
+ }
34
+ if ($cmdArgs.Count -gt 0 -and $cmdArgs[0] -eq "--") {
27
35
  if ($cmdArgs.Count -lt 2) {
28
- [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_NUMBER BASE -- TEST_COMMAND [ARGS...]")
36
+ [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]")
29
37
  exit 2
30
38
  }
39
+ # Guard the lower bound: 1..0 in PowerShell yields @(1,0), not an empty
40
+ # range, so slice only when a command actually follows the separator.
31
41
  $cmdArgs = @($cmdArgs[1..($cmdArgs.Count - 1)])
32
42
  }
33
- $sdd = Join-Path $PSScriptRoot "../../subagent-driven-development/scripts"
43
+ if ($cmdArgs.Count -eq 0) {
44
+ [Console]::Error.WriteLine("usage: task-done.ps1 PLAN_FILE TASK_ID BASE -- TEST_COMMAND [ARGS...]")
45
+ exit 2
46
+ }
47
+ $sdd = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "../../subagent-driven-development/scripts"))
48
+
49
+ # Use the same working-tree selection as the workspace and require HEAD to exist.
50
+ $repoOutput = @(& (Join-Path $sdd "sdd-repo.ps1") "--with-commit")
51
+ if ($LASTEXITCODE -ne 0 -or $repoOutput.Count -eq 0) { exit 2 }
52
+ $repo = ([string]$repoOutput[0]).Trim()
34
53
 
35
- & git rev-parse --verify --quiet $base >$null 2>&1
54
+ & git -C $repo rev-parse --verify --quiet "$base" >$null 2>&1
36
55
  if ($LASTEXITCODE -ne 0) {
37
56
  [Console]::Error.WriteLine("bad BASE: $base")
38
57
  exit 2
@@ -43,8 +62,11 @@ $log = Join-Path $dir "task-$n-tests.log"
43
62
  $ledger = Join-Path $dir "progress.md"
44
63
 
45
64
  # Render the command the way a person would type it, for the ledger line.
65
+ # Single-quote anything outside a safe allowlist so $,`,(),<>,#,*,?,[,quotes
66
+ # and newlines can never break the ledger line; an embedded ' is escaped by
67
+ # doubling it inside the single quotes.
46
68
  $parts = foreach ($a in [string[]]$cmdArgs) {
47
- if ($a -match '[\s";|&]') { "'$a'" } else { $a }
69
+ if ($a -match "[^a-zA-Z0-9_@%+=:,./-]") { "'" + ($a -replace "'", "''") + "'" } else { $a }
48
70
  }
49
71
  $cmd = $parts -join ' '
50
72
 
@@ -52,7 +74,7 @@ $rc = 0
52
74
  try {
53
75
  $exe = $cmdArgs[0]
54
76
  $rest = @()
55
- if ($cmdArgs.Count -gt 1) { $rest = $cmdArgs[1..($cmdArgs.Count - 1)] }
77
+ if ($cmdArgs.Count -gt 1) { $rest = @($cmdArgs[1..($cmdArgs.Count - 1)]) }
56
78
  & $exe @rest > $log 2>&1
57
79
  $rc = $LASTEXITCODE
58
80
  } catch {
@@ -76,8 +98,8 @@ $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
76
98
  if (-not (Test-Path -LiteralPath $ledger -PathType Leaf)) {
77
99
  [System.IO.File]::WriteAllText($ledger, "# SDD ledger — plan: $plan" + [Environment]::NewLine, $utf8NoBom)
78
100
  }
79
- $base7 = (& git rev-parse --short=7 $base).Trim()
80
- $head7 = (& git rev-parse --short=7 HEAD).Trim()
101
+ $base7 = (& git -C $repo rev-parse --short=7 "$base").Trim()
102
+ $head7 = (& git -C $repo rev-parse --short=7 HEAD).Trim()
81
103
  $line = "Task ${n}: complete (commits $base7..$head7, tests: $cmd → $last)"
82
104
  [System.IO.File]::AppendAllText($ledger, $line + [Environment]::NewLine, $utf8NoBom)
83
105
  Write-Output "ledger: $line"
@@ -5,14 +5,14 @@
5
5
  # cut from. One tool call instead of two, because every call in an inline
6
6
  # session is a turn that re-reads the whole context.
7
7
  #
8
- # Usage: task-start PLAN_FILE TASK_NUMBER
8
+ # Usage: task-start PLAN_FILE TASK_ID
9
9
  # Prints:
10
10
  # brief: <path to the task's brief file>
11
11
  # base: <full SHA of HEAD>
12
12
  set -euo pipefail
13
13
 
14
14
  if [ $# -ne 2 ]; then
15
- echo "usage: task-start PLAN_FILE TASK_NUMBER" >&2
15
+ echo "usage: task-start PLAN_FILE TASK_ID" >&2
16
16
  exit 2
17
17
  fi
18
18
 
@@ -20,11 +20,23 @@ plan=$1
20
20
  n=$2
21
21
  sdd="$(cd "$(dirname "$0")/../../subagent-driven-development/scripts" && pwd)"
22
22
 
23
+ # Require a committed working tree before capturing HEAD as the task's BASE;
24
+ # the current directory, not the plan's location, chooses the repository.
25
+ repo=$("${BASH:-bash}" "$sdd/sdd-repo" --with-commit)
26
+
23
27
  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
24
28
  # strip Unix exec bits when unpacking marketplace packages (#2040).
25
29
  out=$("${BASH:-bash}" "$sdd/task-brief" "$plan" "$n")
26
- brief=$(printf '%s\n' "$out" | sed -n 's/^wrote \(.*\): [0-9][0-9]* lines$/\1/p')
30
+ # Parse the trailing "wrote <path>: N lines" report robustly: strip only the
31
+ # last ": N lines" suffix so colons inside the path survive, and join
32
+ # continuation lines so an embedded newline in the path is preserved.
33
+ brief=$(printf '%s\n' "$out" | awk '
34
+ /^wrote / { sub(/^wrote /, ""); buf = $0; next }
35
+ buf != "" { buf = buf "\n" $0; next }
36
+ { buf = $0 }
37
+ END { sub(/: [0-9][0-9]* lines$/, "", buf); print buf }
38
+ ')
27
39
  [ -n "$brief" ] || { echo "task-brief did not report a path: $out" >&2; exit 1; }
28
40
 
29
41
  echo "brief: $brief"
30
- echo "base: $(git rev-parse HEAD)"
42
+ echo "base: $(git -C "$repo" rev-parse HEAD)"
@@ -5,7 +5,7 @@
5
5
  # cut from. One tool call instead of two, because every call in an inline
6
6
  # session is a turn that re-reads the whole context.
7
7
  #
8
- # Usage: ./task-start.ps1 PLAN_FILE TASK_NUMBER
8
+ # Usage: ./task-start.ps1 PLAN_FILE TASK_ID
9
9
  # Prints:
10
10
  # brief: <path to the task's brief file>
11
11
  # base: <full SHA of HEAD>
@@ -13,13 +13,18 @@
13
13
  $ErrorActionPreference = "Stop"
14
14
 
15
15
  if ($args.Count -ne 2) {
16
- [Console]::Error.WriteLine("usage: task-start.ps1 PLAN_FILE TASK_NUMBER")
16
+ [Console]::Error.WriteLine("usage: task-start.ps1 PLAN_FILE TASK_ID")
17
17
  exit 2
18
18
  }
19
19
 
20
20
  $plan = $args[0]
21
21
  $n = $args[1]
22
- $sdd = Join-Path $PSScriptRoot "../../subagent-driven-development/scripts"
22
+ $sdd = [System.IO.Path]::GetFullPath((Join-Path $PSScriptRoot "../../subagent-driven-development/scripts"))
23
+
24
+ # Require a committed working tree before recording HEAD as the task's BASE.
25
+ $repoOutput = @(& (Join-Path $sdd "sdd-repo.ps1") "--with-commit")
26
+ if ($LASTEXITCODE -ne 0 -or $repoOutput.Count -eq 0) { exit 2 }
27
+ $repo = ([string]$repoOutput[0]).Trim()
23
28
 
24
29
  $out = @(& (Join-Path $sdd "task-brief.ps1") $plan $n)
25
30
  if ($LASTEXITCODE -ne 0) {
@@ -35,4 +40,4 @@ if ([string]::IsNullOrEmpty($brief)) {
35
40
  }
36
41
 
37
42
  Write-Output "brief: $brief"
38
- Write-Output "base: $((& git rev-parse HEAD).Trim())"
43
+ Write-Output "base: $((& git -C $repo rev-parse HEAD).Trim())"
@@ -52,7 +52,7 @@ Dispatch a `general-purpose` subagent, filling the template at [code-reviewer.md
52
52
 
53
53
  You: Let me request code review before proceeding.
54
54
 
55
- BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
55
+ BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | cut -d' ' -f1)
56
56
  HEAD_SHA=$(git rev-parse HEAD)
57
57
 
58
58
  [Dispatch code reviewer subagent]
@@ -136,10 +136,16 @@ sequences — the single most expensive failure observed. Track progress in
136
136
  a ledger file, not only in todos.
137
137
 
138
138
  - Each plan owns a workspace: at skill start, run this skill's
139
- `bash scripts/sdd-workspace PLAN_FILE` — it prints the plan's git-ignored
139
+ `bash scripts/sdd-workspace PLAN_FILE` by its absolute path, from the
140
+ working tree you're executing in — it prints the plan's git-ignored
140
141
  directory (under `<repo-root>/.superpowers/sdd/`), home to
141
142
  every artifact for THIS plan: ledger, briefs, reports, review packages.
142
- Another plan's directory is never yours to read or write.
143
+ Another plan's directory is never yours to read or write. Helpers act on the
144
+ current directory's git working tree, never the plan file's repository; use
145
+ `-C DIR` when a helper supports it. They fail closed outside a working tree
146
+ so an invocation from a skill cache cannot write there. In a new project,
147
+ run `git init` before creating the workspace and make an initial commit
148
+ before `task-start` records BASE.
143
149
  - Check for this plan's ledger at `<workspace>/progress.md`. If its first
144
150
  line names your plan file, tasks with a `Task <N>: complete` line are DONE
145
151
  — do not re-dispatch them; resume at the first task without one. A task
@@ -273,9 +279,10 @@ Record BASE (`git rev-parse HEAD`) before dispatching — the review package
273
279
  and fix-round diffs need it.
274
280
 
275
281
  - **Task brief:** before dispatching an implementer, run this skill's
276
- `bash scripts/task-brief PLAN_FILE N` (or `scripts/task-brief.ps1 PLAN_FILE N` on
277
- Windows PowerShell) — it extracts the task's full text to a
278
- uniquely named file and prints the path. Compose the dispatch so the
282
+ `bash scripts/task-brief PLAN_FILE TASK_ID` (or `scripts/task-brief.ps1 PLAN_FILE TASK_ID` on
283
+ Windows PowerShell) by its absolute path, from the working tree you're
284
+ executing in — it extracts the task's full text to a uniquely named file
285
+ and prints the path. Compose the dispatch so the
279
286
  brief stays the single source of
280
287
  requirements. Your dispatch should contain: (1) one line on where this
281
288
  task fits in the project; (2) the brief path, introduced as "read this
@@ -344,7 +351,7 @@ Template: [implementer-prompt.md](implementer-prompt.md)
344
351
 
345
352
  Implementer subagents report one of four statuses. Handle each appropriately:
346
353
 
347
- **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell, 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.
354
+ **DONE:** Generate the review package (`bash scripts/review-package PLAN_FILE BASE HEAD`, or `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell) by its absolute path, from the working tree you're executing in — 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.
348
355
 
349
356
  **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.
350
357
 
@@ -372,8 +379,9 @@ needed.
372
379
 
373
380
  - Hand the reviewer its diff as a file: run this skill's
374
381
  `bash scripts/review-package PLAN_FILE BASE HEAD` (or
375
- `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell) and
376
- pass the reviewer the file path
382
+ `scripts/review-package.ps1 PLAN_FILE BASE HEAD` on Windows PowerShell) by
383
+ its absolute path, from the working tree you're executing in, and pass the
384
+ reviewer the file path
377
385
  it prints (or, without bash: `git log --oneline`, `git diff --stat`,
378
386
  and `git diff -U10` for the range, redirected to one uniquely named
379
387
  file). The output never enters your own context, and the reviewer sees
@@ -466,7 +474,8 @@ whole suite.
466
474
 
467
475
  **The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
468
476
  (or `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell)
469
- where FIX_BASE is the head the previous review saw, and dispatch
477
+ by its absolute path, from the working tree you're executing in, where FIX_BASE
478
+ is the head the previous review saw, and dispatch
470
479
  [re-review-prompt.md](re-review-prompt.md) with the findings list, the
471
480
  brief, the report file, the review file to append its verdicts to, and the
472
481
  printed diff path. The re-reviewer verdicts
@@ -553,9 +562,9 @@ parked-with-ruling at the cap.
553
562
 
554
563
  The final whole-branch review gets a package too: run
555
564
  `bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (or
556
- `scripts/review-package.ps1 PLAN_FILE MERGE_BASE HEAD` on Windows PowerShell;
557
- MERGE_BASE = the commit the branch started from, e.g. `git merge-base main HEAD`)
558
- and include the
565
+ `scripts/review-package.ps1 PLAN_FILE MERGE_BASE HEAD` on Windows PowerShell)
566
+ by its absolute path, from the working tree you're executing in; MERGE_BASE is
567
+ the commit the branch started from, e.g. `git merge-base main HEAD`. Include the
559
568
  printed path in the final review dispatch, so the final reviewer reads
560
569
  one file instead of re-deriving the branch diff with git commands. Dispatch
561
570
  on the most capable available model (see Model Selection), using
@@ -575,9 +584,9 @@ Per-finding fixers each rebuild context and re-run suites; a real
575
584
  session's final-review fix wave cost more than all its tasks combined.
576
585
  Then run exactly one scoped re-review of the fix wave
577
586
  (`bash scripts/review-package PLAN_FILE FIX_BASE HEAD`, or
578
- `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell,
579
- over the fix range,
580
- [re-review-prompt.md](re-review-prompt.md)).
587
+ `scripts/review-package.ps1 PLAN_FILE FIX_BASE HEAD` on Windows PowerShell)
588
+ by its absolute path, from the working tree you're executing in, over the fix
589
+ range, [re-review-prompt.md](re-review-prompt.md).
581
590
  Adjudicate any residual findings as in the task loop's breaker: park with
582
591
  rulings, or rule on the load-bearing ones and ledger what you decided. Only
583
592
  the four classes above stop you here. There is no second fix wave —