scope-lock: prevent agent rescoping, PR collapse, and demo-rush on locked plans#24
Merged
Merged
Conversation
…s (v5.4.0) Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/00b94a42-65c9-443f-a930-36d72c87dd30 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/1e87f44a-1b33-4b41-a3fc-f111acd5069e Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
…ort guidance, audit dedup note) Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/1e87f44a-1b33-4b41-a3fc-f111acd5069e Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
…g (v5.6.0) Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/1e9d2946-d531-4ae1-a466-1a9a285d6230 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
intel352
May 1, 2026 03:48
View session
…op, SubagentStop, PreCompact) Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/eb1c005b-4d4e-4c5d-9f2f-07785768e3f7 Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
…Bash commands Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/333dd4a3-c249-43c5-911a-56193578cb9c Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a “scope-lock” contract for autonomous runs: after alignment passes, the plan’s Scope Manifest (tasks/PR count/grouping/out-of-scope) becomes immutable and is continuously enforced via tests and Claude Code hooks to prevent silent rescoping, PR collapse, and “demo-mode” partial shipping.
Changes:
- Added a mandatory Scope Manifest + lock hash workflow (
tests/plan-scope-check.sh,skills/scope-lock, and updated pipeline skills to checkpoint/verify it). - Added hook-level enforcement and reminders (PreToolUse guardrails, completion blocking on lock drift, strict-interpretation prompt injection, subagent stop protection, pre-compact snapshots).
- Added operational auditing/consistency tooling (
tests/skill-cross-refs.sh,tests/skill-activation-audit.sh) and documentation updates (README, release notes, roadmap, ADR template).
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/skill-cross-refs.sh | New cross-reference consistency test for skills/agents markdown (paths, superpowers:<name>, and “Step N” refs). |
| tests/skill-activation-audit.sh | New local audit tool for .claude/superpowers-state/in-progress.jsonl to summarize skill/agent activity and detect missing pipeline gates. |
| tests/plan-scope-check.sh | New Scope Manifest validator + lock verifier + (partial) branch-layout checker to enforce scope-lock invariants. |
| tests/cross-llm-coverage.md | Documents host-neutral vs host-conditional status for newly added/updated skills. |
| skills/writing-plans/SKILL.md | Requires Scope Manifest in plans; inserts adversarial review (plan phase) before alignment; adds rollback note requirement for runtime-affecting tasks. |
| skills/using-superpowers/SKILL.md | Extends the canonical autonomous pipeline chain and adds the strict-interpretation invariant mapping ambiguous phrases → required strict meanings. |
| skills/subagent-driven-development/SKILL.md | Adds a per-task scope-lock checkpoint (well-formed + verify-lock) and reinforces “no rescope/PR collapse” rules. |
| skills/scope-lock/SKILL.md | New skill defining lock semantics, prohibited actions, unlock path, and integration points. |
| skills/recording-decisions/SKILL.md | New ADR protocol skill; includes scope-reduction ADR requirement. |
| skills/pr-monitoring/SKILL.md | On successful merge + green CI, triggers post-merge retro generation; clarifies behavior when PR closed without merge. |
| skills/post-merge-retrospective/SKILL.md | New retrospective skill producing docs/retros/* based on artifacts, CI, reviews, and activation logs. |
| skills/finishing-a-development-branch/SKILL.md | Adds mandatory “Scope Completeness Check” (Step 1d) and enforces one PR per manifest row in autonomous mode. |
| skills/brainstorming/SKILL.md | Adds assumption listing, self-challenge, and mandatory adversarial design review (design phase) before writing plans. |
| skills/alignment-check/SKILL.md | Narrows alignment-check to structural trace; adds manifest trace requirement and invokes scope-lock after PASS. |
| skills/adversarial-design-review/SKILL.md | New adversarial review skill with explicit checklists and PASS/FAIL semantics for design and plan phases. |
| hooks/subagent-scope-guard | New SubagentStop hook to block accepting subagent output that modified protected scope-lock/locked-plan files. |
| hooks/prompt-strict-interpretation | New prompt injection hook to remind strict-interpretation rules when trigger phrases appear under a locked plan. |
| hooks/pre-tool-scope-guard | New PreToolUse hook to block self-bypass env var setting, destructive git operations, and pushing/PR actions when lock verification fails. |
| hooks/pre-compact-snapshot | New PreCompact hook to snapshot lock state into activity log and inject into compacted context. |
| hooks/hooks.json | Wires in the new hooks (PreToolUse, UserPromptSubmit, Stop, SubagentStop, PreCompact). |
| hooks/completion-claim-guard | New Stop hook to block “done” claims while any locked plan fails scope verification. |
| docs/roadmap.md | Updates roadmap to reflect shipped items and preserves explicitly rejected items. |
| docs/retros/README.md | Adds docs for where post-merge retros live and why they exist. |
| decisions/README.md | Introduces ADR directory conventions and an index table. |
| decisions/0000-template.md | Adds the ADR template (Nygard format). |
| RELEASE-NOTES.md | Adds v5.6.0 release notes describing scope-lock and new gates/hooks/tests. |
| README.md | Updates workflow documentation to include adversarial review, scope-lock, auditing tools, and strict-interpretation invariant. |
| .cursor-plugin/plugin.json | Version bump to 5.6.0. |
| .claude-plugin/plugin.json | Version bump to 5.6.0. |
| .claude-plugin/marketplace.json | Version bump to 5.6.0. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+53
to
+57
| # Hash of the lock file (the manifest hash stored at lock time) | ||
| if [ -f "$lock_file" ]; then | ||
| lock_hash=$(sha256_file "$lock_file") | ||
| state_section="${state_section} ${plan_name}: ${status_line} (lock-file sha256: ${lock_hash})\n" | ||
| else |
Comment on lines
+69
to
+73
| # Legacy plans (no manifest section AND no `# scope-manifest: required` marker | ||
| # in a hidden HTML comment) are skipped — only plans that opt into the format | ||
| # are enforced. New plans created by writing-plans always include the section, | ||
| # so this only matters for grandfathering historical plans pre-dating the | ||
| # scope-lock skill. |
Comment on lines
+58
to
+71
| case "$tool_name" in | ||
| Bash) | ||
| cmd=$(printf '%s' "$hook_input" | jq -r '.tool_input.command // empty' 2>/dev/null || true) | ||
| [ -z "$cmd" ] && exit 0 | ||
|
|
||
| # ── 0. Self-bypass prevention (ALWAYS first; NOT gated by SUPERPOWERS_HOOKS_DISABLE) ── | ||
| # An agent setting a SUPERPOWERS_* env var poisons its own shell session for | ||
| # subsequent tool calls, allowing it to bypass every downstream gate. | ||
| # Patterns caught: | ||
| # export SUPERPOWERS_HOOKS_DISABLE=1 | ||
| # SUPERPOWERS_ALLOW_DEFAULT_BRANCH=1 git push origin main | ||
| # env SUPERPOWERS_SCOPE_LOCK_WRITE=1 bash -c '...' | ||
| # SUPERPOWERS_PLAN_LOCK_WRITE=1; git commit ... (before semicolon) | ||
| if printf '%s' "$cmd" | grep -qE '(^|[;&|[:space:]])(export[[:space:]]+)?SUPERPOWERS_[A-Z_]+='; then |
Comment on lines
+111
to
+113
| - Before dispatching the next task, run `tests/plan-scope-check.sh --plan <plan-path>` to verify (a) the plan's manifest hash still matches `<plan-path>.scope-lock`, (b) every commit on the feature branch traces to a task in the manifest, (c) no manifest task is missing. | ||
| - On any FAIL, stop dispatching new work; surface the discrepancy to the user. | ||
| - After all tasks complete, run the same check before invoking `finishing-a-development-branch`. |
Comment on lines
+45
to
+49
| if command -v git >/dev/null 2>&1; then | ||
| ( | ||
| cd "$cwd_dir" 2>/dev/null || exit 0 | ||
|
|
||
| # Uncommitted changes to scope-lock files |
Comment on lines
+115
to
+118
| jq -r 'select(.tool=="Agent" or .tool=="Task") | .detail' "$STATE_FILE" 2>/dev/null \ | ||
| | sed -nE 's/.*agent=([A-Za-z0-9_-]+).*/\1/p' | ||
| else | ||
| grep -E '"tool":"(Agent|Task)"' "$STATE_FILE" 2>/dev/null \ |
Comment on lines
+34
to
+35
| known_skills="$(find skills -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | sort -u)" | ||
| known_agents="$(find agents -mindepth 1 -maxdepth 1 -type f -name '*.md' -printf '%f\n' | sed -E 's|\.md$||' | sort -u)" |
Comment on lines
+15
to
+20
| # --against-branch <plan> Verify the actual git branch layout matches the | ||
| # PR Grouping table: every commit since the merge-base | ||
| # with the plan's base branch is reachable from a | ||
| # branch listed in the table; every branch in the | ||
| # table exists locally or on origin. | ||
| # |
Comment on lines
+71
to
+85
| PIPELINE_GATES=( | ||
| brainstorming | ||
| adversarial-design-review | ||
| writing-plans | ||
| alignment-check | ||
| subagent-driven-development | ||
| finishing-a-development-branch | ||
| pr-monitoring | ||
| ) | ||
|
|
||
| # Optional gates — present only when conditions trigger them. Reported | ||
| # but their absence is NOT a failure. | ||
| OPTIONAL_GATES=( | ||
| recording-decisions | ||
| post-merge-retrospective |
Contributor
|
@copilot apply changes based on the comments in this thread |
Agent-Logs-Url: https://github.com/GoCodeAlone/claude-superpowers/sessions/333f45fb-54f9-4471-a162-9d3bdd01cb0e Co-authored-by: intel352 <77607+intel352@users.noreply.github.com>
Contributor
Author
Applied all 9 fixes in ee9ea53:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
hooks/pre-compact-snapshot— read stored manifest hash from lock file, not sha256-of-lock-file; remove unusedsha256_filehelpertests/plan-scope-check.sh— remove undocumentedscope-manifest: requiredmarker reference from commenthooks/pre-tool-scope-guard— tighten SUPERPOWERS_* detector to strip quoted strings first (best-effort), soecho "SUPERPOWERS_..."andgrep 'SUPERPOWERS_...='are no longer blockedskills/scope-lock/SKILL.md— correct per-task checkpoint command (--plan→--verify-lock)hooks/subagent-scope-guard— fix subshell losing violations variable; use_saved_pwd/cdsave-restore instead of( ... )tests/skill-activation-audit.sh—extract_agents()now matches Task* tools (TaskCreate etc.); PIPELINE_GATES now includesscope-lockandpost-merge-retrospectivetests/skill-cross-refs.sh— replace GNU-onlyfind -printfwith portablefind | sed; replacemapfilewithwhile IFS= read -rloopstests/plan-scope-check.sh— narrow--against-branchdocs to match actual implementation (branch exists, not commit reachability)tests/skill-activation-audit.sh—PIPELINE_GATESupdated to includescope-lockandpost-merge-retrospectiveper canonical chain inusing-superpowers/SKILL.md