summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2026-10-23 00:08:14 +0000
committerJesse Vincent <jesse@fsck.com>2026-10-23 00:22:00 +0000
commit402cfdeed9665ada0b220be12f6ddbd417fb956c (patch)
tree118c5ab2df6ea789c60a90d97cef66be6eea8663
parent74500c1deba9ba141c9c147e4c78e566282b195f (diff)
docs(sdd): say "by its absolute path" at every helper invocation, and test itfix/2429-sdd-invocation-text
The SKILL.md change left skill-relative helper calls elsewhere under skills/: final-review.md (the final whole-branch review package and its re-review), fix-loop.md (the scoped re-review), the reviewer prompt templates' placeholder descriptions, and executing-plans' task-start and task-done. Each now carries the same qualifier: run the script by its absolute path, from the working tree you're executing in. Nothing else in those files changes. tests/sdd-helper-paths/test-sdd-helper-paths.sh is a structural test that fails when any skills/ markdown names a helper (sdd-workspace, task-brief, review-package, task-start, task-done) by a relative scripts/ path without "by its absolute path" within the next few lines. It failed on 8 references before this change and passes on all 14 after. Claude-Session: https://claude.ai/code/session_01SHANcr4A71nzuU9et4Fnba
-rw-r--r--skills/executing-plans/SKILL.md5
-rw-r--r--skills/subagent-driven-development/re-review-prompt.md1
-rw-r--r--skills/subagent-driven-development/references/final-review.md6
-rw-r--r--skills/subagent-driven-development/references/fix-loop.md2
-rw-r--r--skills/subagent-driven-development/task-reviewer-prompt.md6
-rwxr-xr-xtests/sdd-helper-paths/test-sdd-helper-paths.sh49
6 files changed, 62 insertions, 7 deletions
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md
index a2631b7..ea23196 100644
--- a/skills/executing-plans/SKILL.md
+++ b/skills/executing-plans/SKILL.md
@@ -170,7 +170,8 @@ in the workspace and read its tail; read a brief, not the whole plan.
### 1. Take the task
-- Run this skill's `scripts/task-start PLAN_FILE N`. It prints the brief
+- Run this skill's `scripts/task-start PLAN_FILE N` by its absolute path,
+ from the working tree you're executing in. It prints the brief
path and BASE (the commit the task's range is cut from) in one call.
Read the brief for every task, including ones you remember from setup:
what you remember is a summary, the brief has the exact values,
@@ -223,7 +224,7 @@ the claim. If any item is missing, the task is not complete: finish it.
### 4. Complete the task
Run this skill's `scripts/task-done PLAN_FILE N BASE -- <test command>`
-with the test command the brief names for the whole task. It runs the
+by its absolute path, from the working tree you're executing in, with the test command the brief names for the whole task. It runs the
tests, keeps the full output in the workspace, prints the tail, and — only
if they pass — appends the completion line to the ledger:
diff --git a/skills/subagent-driven-development/re-review-prompt.md b/skills/subagent-driven-development/re-review-prompt.md
index d49c182..eb520df 100644
--- a/skills/subagent-driven-development/re-review-prompt.md
+++ b/skills/subagent-driven-development/re-review-prompt.md
@@ -110,6 +110,7 @@ Subagent (general-purpose):
- `[FIX_BASE_SHA]` — the head the previous review saw
- `[HEAD_SHA]` — current commit
- `[DIFF_FILE]` — the path `bash scripts/review-package PLAN_FILE FIX_BASE HEAD` printed
+ (run by its absolute path, from the working tree you're executing in)
**Re-reviewer returns:** per-finding verdicts (ADDRESSED / NOT ADDRESSED),
new breakage in the fix diff, out-of-scope observations, and a round verdict.
diff --git a/skills/subagent-driven-development/references/final-review.md b/skills/subagent-driven-development/references/final-review.md
index 851a5c5..cf03546 100644
--- a/skills/subagent-driven-development/references/final-review.md
+++ b/skills/subagent-driven-development/references/final-review.md
@@ -4,7 +4,8 @@ Part of superpowers:subagent-driven-development. Every task in the plan is
complete.
The final whole-branch review gets a package too: run
-`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` (MERGE_BASE = the commit the
+`bash scripts/review-package PLAN_FILE MERGE_BASE HEAD` by its absolute path,
+from the working tree you're executing in (MERGE_BASE = the commit the
branch started from, e.g. `git merge-base main HEAD`) and include the
printed path in the final review dispatch, so the final reviewer reads
one file instead of re-deriving the branch diff with git commands. Dispatch
@@ -19,7 +20,8 @@ with the complete findings list — not one fixer per finding.
Per-finding fixers each rebuild context and re-run suites; a real
session's final-review fix wave cost more than all its tasks combined.
Then run exactly one scoped re-review of the fix wave
-(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` over the fix range,
+(`bash scripts/review-package PLAN_FILE FIX_BASE HEAD` by its absolute path,
+from the working tree you're executing in, over the fix range,
[re-review-prompt.md](../re-review-prompt.md)).
Adjudicate any residual findings as in the fix loop's breaker
(references/fix-loop.md): park with rulings, or rule on the load-bearing
diff --git a/skills/subagent-driven-development/references/fix-loop.md b/skills/subagent-driven-development/references/fix-loop.md
index 0b476e9..34e4a48 100644
--- a/skills/subagent-driven-development/references/fix-loop.md
+++ b/skills/subagent-driven-development/references/fix-loop.md
@@ -42,7 +42,7 @@ covering test files in the fix message — a one-line fix does not need the
whole suite.
**The re-review is scoped.** Run `bash scripts/review-package PLAN_FILE FIX_BASE HEAD`
-where FIX_BASE is the head the previous review saw, and dispatch
+by its absolute path, from the working tree you're executing in, where FIX_BASE is the head the previous review saw, and dispatch
[re-review-prompt.md](../re-review-prompt.md) with the findings list, the
brief, the report file, and the printed diff path. The re-reviewer verdicts
each finding ADDRESSED or NOT ADDRESSED and flags new breakage in the fix
diff --git a/skills/subagent-driven-development/task-reviewer-prompt.md b/skills/subagent-driven-development/task-reviewer-prompt.md
index 5c619bc..4cf7860 100644
--- a/skills/subagent-driven-development/task-reviewer-prompt.md
+++ b/skills/subagent-driven-development/task-reviewer-prompt.md
@@ -189,7 +189,8 @@ Subagent (general-purpose):
**Placeholders:**
- `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
-- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`
+- `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`,
+ run by its absolute path, from the working tree you're executing in,
prints the path; same file the implementer worked from)
- `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
the plan's Global Constraints section or the spec: exact values, formats,
@@ -200,7 +201,8 @@ Subagent (general-purpose):
- `[BASE_SHA]` — commit before this task
- `[HEAD_SHA]` — current commit
- `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
- package to (`bash scripts/review-package PLAN_FILE BASE HEAD` prints the unique
+ package to (`bash scripts/review-package PLAN_FILE BASE HEAD`, run by its
+ absolute path, from the working tree you're executing in, prints the unique
path it wrote; the package never enters the controller's context)
**Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
diff --git a/tests/sdd-helper-paths/test-sdd-helper-paths.sh b/tests/sdd-helper-paths/test-sdd-helper-paths.sh
new file mode 100755
index 0000000..26c5fcb
--- /dev/null
+++ b/tests/sdd-helper-paths/test-sdd-helper-paths.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Fails when any file under skills/ tells the agent to run an SDD or
+# executing-plans helper (sdd-workspace, task-brief, review-package,
+# task-start, task-done) by a skill-relative `scripts/...` path without
+# saying to run it by its absolute path from the working tree.
+#
+# The helpers act on the git working tree of the current directory, like
+# git. A skill-relative path invites the agent to cd into the skill's own
+# directory (the plugin cache) to make the path work, which puts the
+# helpers outside the working tree it is executing in (#2429). Every such
+# reference must carry the phrase "by its absolute path" within a few
+# lines after it.
+#
+# Usage: tests/sdd-helper-paths/test-sdd-helper-paths.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# A backticked invocation whose path is relative: optional "bash ", then an
+# optional ../<skill>/ prefix, then scripts/<helper>. Absolute paths ($S/...,
+# /...) don't match.
+invocation='`(bash )?(\.\./[a-z-]+/)?scripts/(sdd-workspace|task-brief|review-package|task-start|task-done)'
+phrase='by its absolute path'
+
+failed=0
+checked=0
+while IFS=: read -r file line _; do
+ checked=$((checked + 1))
+ # The phrase may wrap onto the next lines; look at this line and the two
+ # after it, joined (whitespace squeezed, so line-wrap indentation doesn't
+ # split the phrase), starting from the invocation itself.
+ window=$(sed -n "${line},$((line + 2))p" "$file" | tr -s '[:space:]' ' ')
+ after=$(printf '%s\n' "$window" | grep -oE "$invocation.*" | head -n 1)
+ if [[ "${after:0:240}" != *"$phrase"* ]]; then
+ echo "FAIL: ${file#"$REPO_ROOT"/}:$line runs a helper by a relative scripts/ path without \"$phrase\"" >&2
+ failed=1
+ fi
+done < <(grep -rnE --include='*.md' "$invocation" "$REPO_ROOT/skills")
+
+if ((checked == 0)); then
+ echo "FAIL: found no helper invocations under skills/; the pattern is stale" >&2
+ exit 1
+fi
+if ((failed)); then
+ echo "Say to run the script by its absolute path, from the working tree you're executing in." >&2
+ exit 1
+fi
+echo "PASS: all $checked relative helper references under skills/ say to run them by absolute path"