superpowers-mcp 6.3.6 → 6.3.8

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,14 +42,17 @@ 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)
-root=$(CDPATH= cd -- "$root" && pwd -P)
+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"
 
 # Normalize the plan path (physical directory, so relative/absolute/../
 # spellings of one plan compare equal) and express it as the marker value:
 # repo-relative when the plan lives under the repo root, absolute otherwise.
-plan_dir=$(CDPATH= cd -- "$(dirname -- "$plan")" && pwd -P)
+plan_dir=$(CDPATH='' cd -- "$(dirname -- "$plan")" && pwd -P)
 plan_abs="$plan_dir/$(basename -- "$plan")"
 case "$plan_abs" in
   "$root"/*) plan_id=${plan_abs#"$root"/} ;;
@@ -76,4 +83,4 @@ if ! owns "$dir"; then
 fi
 
 printf '*\n' > "$base/.gitignore"
-CDPATH= cd -- "$dir" && pwd
+CDPATH='' cd -- "$dir" && pwd

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 '\\', '/'
@@ -76,7 +97,11 @@ function Test-And-Claim-Workspace($targetDir, $id) {
         return ($existingId -eq $id)
     } else {
         New-Item -ItemType Directory -Force -Path $targetDir | Out-Null
-        Set-Content -LiteralPath $markerPath -Value $id -Encoding ascii
+        [System.IO.File]::WriteAllText(
+            $markerPath,
+            $id + [Environment]::NewLine,
+            [System.Text.UTF8Encoding]::new($false)
+        )
         return $true
     }
 }

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/systematic-debugging/find-polluter.ps1

@@ -1,17 +1,19 @@
 #!/usr/bin/env pwsh
 # Bisection script to find which test creates unwanted files/state.
-# Usage: ./find-polluter.ps1 <file_or_dir_to_check> <test_pattern>
+# Usage: ./find-polluter.ps1 <file_or_dir_to_check> <test_pattern> <test command and arguments>
 
 $ErrorActionPreference = "Stop"
 
-if ($args.Count -ne 2) {
-    Write-Output "Usage: ./find-polluter.ps1 <file_to_check> <test_pattern>"
-    Write-Output "Example: ./find-polluter.ps1 '.git' 'src/**/*.test.ts'"
+if ($args.Count -lt 3) {
+    Write-Output "Usage: ./find-polluter.ps1 <file_to_check> <test_pattern> <test command and arguments>"
+    Write-Output "Example: ./find-polluter.ps1 '.git' 'src/**/*.test.ts' npx vitest run"
     exit 1
 }
 
 $pollutionCheck = $args[0]
 $testPattern = $args[1]
+$testCommand = $args[2]
+$testCommandArgs = if ($args.Count -gt 3) { @($args[3..($args.Count - 1)]) } else { @() }
 
 Write-Output "Searching for test that creates: $pollutionCheck"
 Write-Output "Test pattern: $testPattern"
@@ -53,7 +55,7 @@ foreach ($testFile in $testFiles) {
     }
 
     Write-Output "[$count/$total] Testing: $($testFile.FullName)"
-    & npm test $testFile.FullName *> $null
+    & $testCommand @testCommandArgs $testFile.FullName *> $null
 
     if (Test-Path -LiteralPath $pollutionCheck) {
         Write-Output ""

package/skills/systematic-debugging/find-polluter.sh

@@ -1,18 +1,19 @@
 #!/usr/bin/env bash
 # Bisection script to find which test creates unwanted files/state
-# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
-# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern> <test command ...>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts' npx vitest run
 
 set -e
 
-if [ $# -ne 2 ]; then
-  echo "Usage: $0 <file_to_check> <test_pattern>"
-  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+if [ $# -lt 3 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern> <test command ...>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts' npx vitest run"
   exit 1
 fi
 
 POLLUTION_CHECK="$1"
 TEST_PATTERN="$2"
+TEST_COMMAND=("${@:3}")
 
 echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
 echo "Test pattern: $TEST_PATTERN"
@@ -24,7 +25,7 @@ TEST_PATTERN="${TEST_PATTERN#./}"
 # find -path can't match '**/' against zero directory levels, so a pattern
 # like src/**/*.test.ts would skip src/top.test.ts; also try the pattern
 # with '**/' collapsed to cover files directly under the base directory.
-TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) | sort -u)
+TEST_FILES=$(find . \( -path "./$TEST_PATTERN" -o -path "./${TEST_PATTERN//\*\*\//}" \) -print | sort -u)
 if [ -z "$TEST_FILES" ]; then
   TOTAL=0
 else
@@ -35,7 +36,8 @@ echo "Found $TOTAL test files"
 echo ""
 
 COUNT=0
-for TEST_FILE in $TEST_FILES; do
+while IFS= read -r TEST_FILE; do
+  [ -n "$TEST_FILE" ] || continue
   COUNT=$((COUNT + 1))
 
   # Skip if pollution already exists
@@ -48,7 +50,7 @@ for TEST_FILE in $TEST_FILES; do
   echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
 
   # Run the test
-  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+  "${TEST_COMMAND[@]}" "$TEST_FILE" > /dev/null 2>&1 || true
 
   # Check if pollution appeared
   if [ -e "$POLLUTION_CHECK" ]; then
@@ -65,7 +67,7 @@ for TEST_FILE in $TEST_FILES; do
     echo "  cat $TEST_FILE         # Review test code"
     exit 1
   fi
-done
+done <<< "$TEST_FILES"
 
 echo ""
 echo "✅ No polluter found - all tests clean!"

package/skills/systematic-debugging/root-cause-tracing.md

@@ -101,10 +101,10 @@ If something appears during tests but you don't know which test:
 Use the bisection script `find-polluter.sh` in this directory:
 
 ```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts'
+./find-polluter.sh '.git' 'src/**/*.test.ts' npx vitest run
 
 # Windows PowerShell:
-./find-polluter.ps1 '.git' 'src/**/*.test.ts'
+./find-polluter.ps1 '.git' 'src/**/*.test.ts' npx vitest run
 ```
 
 Runs tests one-by-one, stops at first polluter. See script for usage.

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:
 

package/skills/using-git-worktrees/SKILL.md

@@ -93,10 +93,19 @@ git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/d
 # Determine path based on chosen location
 path="$LOCATION/$BRANCH_NAME"
 
+# Basing on current HEAD:
 git worktree add "$path" -b "$BRANCH_NAME"
+# Basing on any other ref (origin/main, origin/production, a tag) —
+# --no-track is REQUIRED, not optional:
+git worktree add "$path" -b "$BRANCH_NAME" --no-track <base-ref>
 cd "$path"
+
+# REQUIRED final check: the new branch must track no shared branch
+git branch -vv | grep -F "$BRANCH_NAME"
 ```
 
+**If that check shows `[origin/<shared branch>]`** (e.g. `[origin/main]`, `[origin/production]`): run `git branch --unset-upstream` now, before any commit. Inherited upstream is a git default, not anyone's intent — a later plain `git push`, an editor auto-sync, or a future session will land this work directly on that shared branch. A feature branch tracking a shared branch is never the correct end state, and mentioning it in your report while leaving it set does not count as handling it.
+
 **Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
 
 ## Step 2: Project Setup
@@ -152,6 +161,7 @@ Ready to implement <feature-name>
 | Both exist | Use `.worktrees/` |
 | Neither exists | Check instruction file, then default `.worktrees/` |
 | Directory not ignored | Add to .gitignore + commit |
+| New branch tracks a shared remote branch | `git branch --unset-upstream` before committing (Step 1b) |
 | Permission error on create | Sandbox fallback, work in place |
 | Tests fail during baseline | Report failures + ask |
 | No package.json/Cargo.toml | Skip dependency install |
@@ -165,3 +175,5 @@ Ready to implement <feature-name>
 | "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
 | "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
 | "The workspace is fresh — baseline tests can wait" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |
+| "It tracks origin/production, but nobody is pushing today" | The trap outlives today: the next plain `git push`, editor auto-sync, or session lands work on the shared branch. `git branch --unset-upstream` now — a warning note in your report doesn't disarm it. |
+| "Tracking the base ref is expected — I branched from it" | Inherited upstream is a git default, not an intent. Pass `--no-track` at creation, or `--unset-upstream` the moment the check shows a shared branch. |

package/skills/using-superpowers/SKILL.md

@@ -32,7 +32,7 @@ When multiple skills apply, process skills come first — they set the approach,
 
 ## Skill Compositions & Pipelines
 
-Complex engineering workflows chain multiple skills end-to-end (see `docs/skill-compositions.md`):
+Complex engineering workflows chain multiple skills end-to-end. The complete published guide is available from the MCP resource `guide://superpowers/skill-compositions`:
 
 - **Feature Pipeline:** `brainstorming` → `writing-plans` → `using-git-worktrees` → `subagent-driven-development` (with `test-driven-development`) → `verification-before-completion` → `requesting-code-review` → `finishing-a-development-branch`
 - **Troubleshooting Pipeline:** `systematic-debugging` → `using-git-worktrees` → `dispatching-parallel-agents` → `test-driven-development` → `verification-before-completion` → `requesting-code-review`

package/skills/verification-before-completion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; for work with no test command (reports, research, recipes, correspondence, audits) requires re-opening the artifact and accounting for every part of the request; evidence before assertions always
 ---
 
 # Verification Before Completion
@@ -118,3 +118,56 @@ Skip any step = lying, not verifying
 - Paraphrases and synonyms
 - Implications of success
 - ANY communication suggesting completion/correctness
+
+---
+
+## When There Is No Test Command
+
+### Why this section exists
+
+Everything above assumes an external judge: a test suite, a linter, an exit code.
+The machine says pass or fail and you cannot argue with it.
+
+Most work has no such judge. Nothing can run a report, a recipe or a research
+answer and return "correct". The rule does not change — **no completion claim
+without evidence** — only what evidence means.
+
+### The failure this stops
+
+Reporting what you INTENDED to produce rather than what is actually on disk.
+
+**If you have not re-opened the artifact in this message, you have not checked
+it.** You are remembering your own intentions, which is exactly the state in
+which things get missed.
+
+### Two levels, in this order
+
+#### 1. Prove whatever CAN be proven
+
+Some things are as binary as a test suite:
+
+| Claim | Evidence |
+|---|---|
+| Followed the required structure | Open the file. Name each required section and where it appears. |
+| Sources cited | Every claim carries a reference, present and in the required format |
+| Standing constraints held | Re-read start to finish. A constraint honoured in step 1 and dropped in step 8 is a failure. |
+| Findings are real | Every finding points at a location — a line, a quoted span. A finding with no location was recalled, not read. |
+| Data reconciles | Totals add up; numbers in the summary match numbers in the table |
+| Nothing was truncated | The output ends where it should, not mid-section |
+
+#### 2. For everything else, account for the request in full
+
+- Break what was asked into its separate parts.
+- Open what you actually produced.
+- Confirm each part is addressed.
+- **State plainly anything you did not do.**
+
+Four of five things done is not "done". Say which four.
+
+### What this does NOT claim
+
+Confirming that work is complete, consistent and within spec does not make it
+correct. A recipe can hang together perfectly and still taste wrong; a report can
+follow its structure and still reach the wrong conclusion.
+
+**Say which you verified: that the work is *complete*, not that it is *right*.**

package/skills/writing-plans/SKILL.md

@@ -179,15 +179,30 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 
 ## Execution Handoff
 
-After saving the plan, offer execution choice:
+After saving and self-reviewing the plan, link it for your human partner
+to read. If they have already explicitly supplied an execution method, ask
+them to review the plan and confirm it captures what they want; wait for that
+review before implementation, then use the preserved method. Otherwise, ask
+them to review the plan and choose an execution method before implementation.
 
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+**When no execution method has already been supplied:**
 
-**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options:**
 
-**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+**1. Subagent-Driven** - fresh subagent per task, review between tasks, fast iteration
 
-**Which approach?"**
+**2. Inline Execution** - tasks in a session via executing-plans, batched with checkpoints
+
+**Recommended for this plan: [pick one] — [one-line why].** Then: **Does the plan capture what you want, and which approach should we use?"**
+
+Pick the recommendation from the plan in front of you:
+- **Subagent-driven** when tasks are largely independent, the plan is short-to-medium, and a cold executor could pick up each task from its own task block alone.
+- **Inline** when tasks share interfaces/state, build heavily on each other, the plan is long, or you (the parent) already hold the spec/architecture context that a cold subagent would spend a spawn re-deriving each time.
+Say which and why. Never default to one without looking.
+
+**When an execution method has already been supplied:**
+
+**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"**
 
 **If Subagent-Driven chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development

package/skills/writing-skills/SKILL.md

@@ -371,6 +371,35 @@ pptx/
 ```
 When: Reference material too large for inline
 
+### Moving Content Into a Skill
+
+Relative paths mean nothing on their own - they resolve against the file holding them. Moving content to a different depth invalidates every relative reference inside it.
+
+**Re-resolve links mechanically, never by counting `../` by eye:**
+
+```bash
+# From the moved file's directory, assert every relative target exists
+d=$(dirname "$FILE")
+grep -o ']([^)]*)' "$FILE" | sed 's/^](//;s/)$//' | while read -r l; do
+  case "$l" in http*|\#*|mailto:*|"") continue;; esac
+  [ -e "$d/${l%%#*}" ] || echo "DANGLING: $l"
+done
+```
+
+A link that is one `../` short still renders as a link. The count is not something you verify by looking at it.
+
+Read the output - this is a heuristic, not a parser, so `](` inside a fenced code block shows up as a false positive.
+
+**Then grep the moved text for prose cross-references:**
+
+```bash
+grep -n 'above\|below\|earlier\|later' "$FILE"
+```
+
+"The section above" has no referent once that section lives in a different file. No link checker can catch this - only reading can.
+
+**Why this matters:** a dangling link fails silently. The agent follows it, finds nothing, and proceeds without the context it was supposed to have. No error, no failing test.
+
 ## The Iron Law (Same as TDD)
 
 ```
@@ -660,6 +689,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 - [ ] Common mistakes section
 - [ ] No narrative storytelling
 - [ ] Supporting files only for tools or heavy reference
+- [ ] Content moved from another file: every relative link re-resolved against the new location and verified to exist; prose cross-references (`above`, `below`, `earlier`, `later`) re-read for lost referents
 
 **Deployment:**
 - [ ] Commit skill to git and push to your fork (if configured)