diff options
| author | Jesse Vincent <jesse@fsck.com> | 2026-10-23 00:08:14 +0000 |
|---|---|---|
| committer | Jesse Vincent <jesse@fsck.com> | 2026-10-23 00:22:00 +0000 |
| commit | 402cfdeed9665ada0b220be12f6ddbd417fb956c (patch) | |
| tree | 118c5ab2df6ea789c60a90d97cef66be6eea8663 | |
| parent | 74500c1deba9ba141c9c147e4c78e566282b195f (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
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" |
