Skip to content

feat(sdd): bind nested instruction files and enclosing-function context in reviews - #2

Merged
stanlrt merged 12 commits into
mainfrom
feat/review-enclosing-context
Nov 2, 2026
Merged

stanlrt merged 12 commits into
mainfrom
feat/review-enclosing-context

Conversation

@stanlrt

@stanlrt stanlrt commented Nov 2, 2026

Copy link
Copy Markdown
Owner

This fork has no dev branch; this PR targets the fork's main.

Who is submitting this PR? (required)

Field Value
Your model + version Claude Opus 5.5 (claude-opus-5-5) as controller; Sonnet implementers; Opus final reviewers
Harness + version Claude Code 2.1.316
All plugins installed superpowers-custom 6.0.4-fork.10, caveman, cloudflare, rebel-workspace-skills, rebel-design-skills, design, frontend-design, pdf-viewer, cowork-plugin-management
Human partner who reviewed this diff @stanlrt — approved the design and spec; full-diff review pending

What problem are you trying to solve?

Review and implementer subagents look at diff hunks, not at the code the hunks land in. On a downstream project, two bugs got past eight reviewer passes, and an external bot caught both:

  1. A new scheduled mutation read a whole table into memory. The rule against that lived only in a nested <subdir>/AGENTS.md. No brief or reviewer read it.
  2. A task moved component-local state into a child component. The child sat inside an existing keyed wrapper (an unchanged line) that remounts on every data refetch, so the state was lost. The reviewer saw the wrapper only as context and praised it.

Both bugs come from new code meeting unchanged code.

What does this PR change?

  • A new scripts/instruction-files helper gathers every AGENTS.md / CLAUDE.md from the repo root down to each file's directory. review-package and task-brief inline those files with line numbers.
  • review-package widens each hunk to its enclosing function (git diff --function-context). A file over SDD_CONTEXT_CAP lines falls back to -U10 and is marked.
  • The reviewer and implementer templates treat the instruction files as binding, and they check new state, effects and resources against the enclosing unchanged code. Script tests now run in CI.

Is this change appropriate for the core library?

Yes. Nothing here is specific to a stack: the change has no framework, language or product wording, uses only bash 3.2 and POSIX awk, and relies on git's own funcname rules or the repo's .gitattributes diff drivers.

What alternatives did you consider?

  • A custom brace/indent scan to find enclosing blocks: more code, and worse on languages without brace or indent conventions. Rejected in favour of --function-context plus a per-file cap.
  • Inlining only nested instruction files: chose root + nested, because a harness may not auto-load the root file.
  • Template wording that tells reviewers to find AGENTS.md themselves: rejected, because it relies on memory. Gathering the files by script is the point.
  • Parsing the human wrote <path>: line: replaced with --print-path.

Does this PR contain multiple unrelated changes?

The PR contains a few side changes. All of them came up in this work:

  • sdd-workspace exec bit (100644 → 100755): without it, the repo's own scripts fail on a fresh checkout. The new CI step exposed this.
  • scripts/snapshot index seeding: under core.fileMode=false, review packages showed mode changes that were not real.
  • --print-path: chosen during branch-finish triage of a refactor finding.

Existing PRs

  • I have reviewed all open AND closed PRs for duplicates or prior art
  • Related PRs: none checked (personal fork)

Environment tested

Harness (e.g. Claude Code, Cursor) Harness version Model Model version/ID
Claude Code 2.1.316 Claude Opus 5.5 claude-opus-5-5

New harness support (required if this PR adds a new harness)

Not applicable: no new harness.

Evaluation

  • Initial prompt: a request to widen review and implementer context, motivated by the two misses above, run through brainstorming → writing-plans → subagent-driven-development.
  • Eval sessions after the change: none in a separate session. The branch's own reviews ran on packages built by the new review-package: Tasks 2 and 3, and every final review.
  • Outcome:
    • Packages carried the root AGENTS.md and whole enclosing functions.
    • Reviewers ran focused adversarial checks in temp repos: colour/ext-diff config, renames, typechanges, binary files, symlinks, macOS git < 2.28 and mawk.
    • These checks found 3 + 1 + 1 Important issues across three final-review rounds, all fixed.
  • Tests: tests/claude-code/test-sdd-review-context.sh (new) and test-sdd-workspace.sh pass locally, and CI now runs both.

Rigor

  • If this is a skills change: I used superpowers-custom:writing-skills and completed adversarial pressure testing (paste results below) — not done; template edits are additive
  • This change was tested adversarially, not just on the happy path (scripts: see Evaluation)
  • I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

Human review

  • A human has reviewed the COMPLETE proposed diff before submission — pending @stanlrt

🤖 Generated with Claude Code

https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8

stanlrt and others added 12 commits November 2, 2026 13:10
review-package, task-brief, and snapshot exec it directly; mode 100644
made them fail with "Permission denied" in a fresh checkout.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Prints every AGENTS.md / CLAUDE.md from the repo root down to each given
path's directory, with line numbers and byte-identical files deduped,
from the working tree or a given tree-ish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Reviewer and implementer templates treat the package's or brief's
AGENTS.md / CLAUDE.md files as binding (violations Important, cited as
path:line) and check new state, effects, and resources against the
unchanged code that encloses them. requesting-code-review builds a
review package before dispatch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
…ctions

Packages now carry the AGENTS.md / CLAUDE.md files governing the changed
files (read from the HEAD tree-ish) and widen each hunk to its enclosing
function via git diff --function-context. A file over SDD_CONTEXT_CAP
lines (default 400) falls back to -U10 and is marked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
- review-package: --no-color/--no-ext-diff and fixed prefixes on every diff,
  guard against an empty Diff, stream per-file chunks to temp files (was
  quadratic), take capped paths from name-only output, build the range once.
- instruction-files: resolve symlinked entries in tree mode, reject unknown
  flags, exit 2 outside a repo.
- task-brief: ignore fenced Files blocks; end the block at the first blank
  line after its list.
- snapshot: seed the temp index from the real index so file modes survive
  core.fileMode=false.
- Templates: refactor reviewer leaves rule violations to the correctness
  reviewer; missing-package fallbacks use function context and read the
  instruction files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
- instruction-files accepts -- as end of options; task-brief and
  review-package pass it, so a Files token starting with - is a path.
- instruction-files refuses symlinks that resolve outside the repository.
- review-package pairs chunks with --name-status so typechanges stay
  aligned; diffs use --submodule=short and --no-relative.
- task-brief keeps wrapped Files items in the block and uses one fence
  rule for both passes.
- Tests share repo/commit/exit helpers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
…cape

- Replace --no-relative with -c diff.relative=false (older git has no
  relative mode and rejects the flag).
- instruction-files resolves link directories physically (cd -P), so a
  directory symlink plus a ../ target cannot escape the repository check.
- Portable newline escaping for path labels; one symlink hop limit.
- Tests grouped by script; task-brief header rewrapped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Callers read the output path directly instead of parsing the human
"wrote <path>: ..." line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AZoP36KqiDZhD3gJ6o8f8
Copilot AI balanced review requested due to automatic review settings November 2, 2026 12:57

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

A critical symlink-validation flaw can include out-of-repository file contents in task briefs, while rename and newline-path handling can omit governing instructions.

3 open issues
What changed in this PR

This PR strengthens the fork’s subagent review workflow by supplying governing instruction files and enclosing-function context, helping agents assess changes against both repository rules and unchanged code.

Changes:

  • Add instruction-file collection to review packages and task briefs, plus capped function-level diff context.
  • Update reviewer and implementer guidance to use these inputs and check surrounding code.
  • Add script tests to CI, correct snapshot file-mode handling, and bump release manifests to 6.0.4-fork.11.
File Description
tests/​claude-code/​test-sdd-review-context.sh Adds coverage for instruction collection, context, paths, and snapshots.
skills/​subagent-driven-development/​task-reviewer-prompt.md Requires governing rules and enclosing-code checks.
skills/​subagent-driven-development/​SKILL.md Documents richer packages and task briefs.
skills/​subagent-driven-development/​scripts/​task-brief Appends governing instructions and adds path-only output.
skills/​subagent-driven-development/​scripts/​snapshot Seeds snapshots from the real index to preserve modes.
skills/​subagent-driven-development/​scripts/​sdd-workspace Makes the workspace helper executable.
skills/​subagent-driven-development/​scripts/​review-package Adds instruction files, capped function context, and path-only output.
skills/​subagent-driven-development/​scripts/​instruction-files Collects and deduplicates governing instruction files.
skills/​subagent-driven-development/​refactor-reviewer-prompt.md Adds instruction constraints and surrounding-code checks.
skills/​subagent-driven-development/​implementer-prompt.md Adds instruction citations and enclosing-code self-review.
skills/​requesting-code-review/​SKILL.md Adds package generation before reviewer dispatch.
skills/​requesting-code-review/​code-reviewer.md Integrates review packages and binding instructions.
package.json Bumps the package version.
gemini-extension.json Bumps the Gemini extension version.
docs/​superpowers/​specs/​2026-11-02-review-enclosing-context-design.md Records the design and acceptance criteria.
docs/​superpowers/​plans/​2026-11-02-review-enclosing-context.md Records implementation and verification steps.
AGENTS.md Documents the fork’s expanded review context.
.kimi-plugin/​plugin.json Bumps the Kimi plugin version.
.github/​workflows/​release-checks.yml Runs both SDD script test suites in CI.
.cursor-plugin/​plugin.json Bumps the Cursor plugin version.
.codex-plugin/​plugin.json Bumps the Codex plugin version.
.claude-plugin/​plugin.json Bumps the Claude plugin version.
.claude-plugin/​marketplace.json Synchronizes the marketplace version.

Review effort: Balanced

while [ -L "$p" ]; do
[ "$hops" -lt "$max_hops" ] || return 1
hops=$((hops + 1))
t=$(readlink -- "$p")
d=$(dirname -- "$p")
[ "$d" = . ] && continue
acc=""
IFS=/ read -r -a parts <<< "$d"
Comment on lines +104 to +117
changed=()
nl=$'\n'
esc='\n'
: > "$tmp/names"
while IFS= read -r -d '' status; do
IFS= read -r -d '' f
case $status in R*|C*) IFS= read -r -d '' f ;; esac
changed+=("$f")
shown=${f//$nl/$esc}
printf '%s\n' "$shown" >> "$tmp/names"
case $status in T*) printf '%s\n' "$shown" >> "$tmp/names" ;; esac
done < <("${gitdiff[@]}" --name-status -z "${range[@]}")

"$scripts/instruction-files" --tree "$head" -- ${changed[@]+"${changed[@]}"} > "$tmp/instr"
@stanlrt
stanlrt merged commit 8fa3390 into main Nov 2, 2026
2 checks passed
@stanlrt
stanlrt deleted the feat/review-enclosing-context branch November 2, 2026 13:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants