scope-lock: prevent agent rescoping, PR collapse, and demo-rush on locked plans

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "5.3.0",
+      "version": "5.6.0",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.3.0",
+  "version": "5.6.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers",
   "displayName": "Superpowers",
   "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "5.3.0",
+  "version": "5.6.0",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

README.md

@@ -101,22 +101,48 @@ Per-skill host-conditional audit: [tests/cross-llm-coverage.md](tests/cross-llm-
 
 ## The Basic Workflow
 
-1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
+1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, lists load-bearing assumptions, runs a self-challenge round, presents design in sections for validation. Soft cap of 5 question-batches; on exceed, agent presents best-current-approximation and asks user to approve / refine / extend the budget. Saves design document.
 
-2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
+2. **adversarial-design-review (design phase)** - Activates after design doc is committed. Adversarially attacks the *ideas* in the design (not just structure): unstated assumptions, repo-precedent conflicts, YAGNI violations, missing failure modes, security gaps, rollback story, simpler alternatives, user-intent drift. PASS/FAIL with max 2 revision cycles.
 
-3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
+3. **recording-decisions** - Activates inside brainstorming and writing-plans whenever a non-trivial choice is made (divergence from precedent, trade-off between ≥2 plausible approaches, adversarial-review override, cross-skill structural change). Adds a numbered ADR in `decisions/` so the *why* survives renames and refactors.
 
-4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
+4. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
 
-5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
+5. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. Runtime-affecting tasks include rollback notes. Plan MUST contain a `## Scope Manifest` block declaring PR Count, Tasks, Out-of-scope items, and a per-PR grouping table — this is the contract `scope-lock` enforces.
 
-6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
+6. **adversarial-design-review (plan phase)** - Activates after plan doc is committed. Inherits the design checklist plus plan-specific scans: task granularity, verification-class match, hidden serial dependencies, rollback wiring.
 
-7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
+7. **alignment-check** - Activates after adversarial review of plan passes. Narrowly structural: every design requirement maps to a plan task; every plan task traces to a design requirement; the Scope Manifest is well-formed (forward + reverse + manifest trace via `tests/plan-scope-check.sh`).
+
+8. **scope-lock** - Activates immediately after `alignment-check` PASS. Stamps the plan with `Locked <timestamp>`, computes the manifest's sha256 into `<plan>.scope-lock`, commits both. From this point until completion (or an explicit user-approved unlock), the task list, PR count, and feature scope are immutable. `subagent-driven-development` re-checks the lock between tasks; `finishing-a-development-branch` re-checks before any PR is created.
+
+9. **subagent-driven-development** or **executing-plans** - Activates with a locked plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality). Between tasks, re-runs the scope-lock check; on lock drift, stops the line and surfaces the discrepancy.
+
+10. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
+
+11. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
+
+12. **finishing-a-development-branch** - Activates when tasks complete. Step 1d (Scope Completeness Check) verifies every manifest task has implementing commits and that the autonomous run produces the planned number of PRs (no silent collapse). Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.
+
+13. **pr-monitoring** - Activates after autonomous PR creation (one monitor per PR in the manifest). Watches CI and review comments; fixes failures and responds to feedback until green.
+
+14. **post-merge-retrospective** - Activates after `pr-monitoring` exits successfully on a merged PR with green CI. Reads the design, plan, adversarial-review reports, code-review threads, and CI history; produces a short retro in `docs/retros/` scoring each adversarial finding (Prescient / Resolved upfront / False positive / Inconclusive), naming gate misses, and surfacing plugin-level follow-ups when patterns emerge across retros.
 
 **The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions.
 
+## Auditing skill activations
+
+`tests/skill-activation-audit.sh` reads `.claude/superpowers-state/in-progress.jsonl` (the activity log written by the `record-activity` hook) and reports which pipeline gates fired during a session. Use it post-hoc when you want to confirm whether the autonomous pipeline ran end-to-end or stopped earlier than expected. Strictly local — never transmits anything.
+
+`tests/skill-cross-refs.sh` verifies that cross-skill references inside `skills/` and `agents/` markdown resolve (skill names, `Step N` references, `superpowers:<name>` mentions). Run it before committing any skill edit that renames a skill or renumbers a step.
+
+`tests/plan-scope-check.sh` verifies the Scope Manifest invariant. Three modes: `--plan <path>` (well-formedness — PR Count matches the grouping table; every task in the body appears in the table; etc.), `--verify-lock <path>` (manifest sha256 matches the `.scope-lock` file written at alignment time), and `--against-branch <plan>` (planned branches in the manifest exist locally or on origin). The autonomous pipeline runs all three at the appropriate gates; CI can run `--plan` against every plan in `docs/plans/`.
+
+## Strict-interpretation invariant
+
+Once a plan is locked, ambiguous user phrases — "reorder as needed", "create a PR", "test locally", "ship a demo", "be quick" — do NOT authorize rescoping, PR collapse, or partial-scope shipping. The agent picks the most-faithful-to-the-locked-manifest interpretation; if multiple strict readings remain plausible, it stops and asks. See the table in `skills/using-superpowers/SKILL.md` § "Strict-interpretation invariant" for the full mapping and the unlock path.
+
 ## What's Inside
 
 ### Skills Library
@@ -129,14 +155,20 @@ Per-skill host-conditional audit: [tests/cross-llm-coverage.md](tests/cross-llm-
 - **verification-before-completion** - Ensure it's actually fixed
 
 **Collaboration** 
-- **brainstorming** - Socratic design refinement
-- **writing-plans** - Detailed implementation plans
+- **brainstorming** - Socratic design refinement (with assumption-listing, self-challenge round, and a 5-batch question budget)
+- **adversarial-design-review** - Adversarial attack on design and plan ideas before execution (two phases: design, plan)
+- **recording-decisions** - ADRs in `decisions/` for non-trivial trade-offs, rejected alternatives, and user-approved scope reductions
+- **writing-plans** - Detailed implementation plans (with mandatory Scope Manifest)
 - **executing-plans** - Batch execution with checkpoints
+- **alignment-check** - Structural design ↔ plan trace (forward + reverse + manifest)
+- **scope-lock** - Once a plan passes alignment, the task list, PR count, and feature scope are immutable until completion or explicit user-approved reduction
 - **dispatching-parallel-agents** - Concurrent subagent workflows
 - **requesting-code-review** - Pre-review checklist
 - **receiving-code-review** - Responding to feedback
 - **using-git-worktrees** - Parallel development branches
-- **finishing-a-development-branch** - Merge/PR decision workflow
+- **finishing-a-development-branch** - Merge/PR decision workflow (with Step 1d Scope Completeness Check)
+- **pr-monitoring** - Watches CI and reviews after autonomous PR creation
+- **post-merge-retrospective** - Closes the loop on merged PRs; scores each adversarial finding and surfaces gate misses
 - **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality)
 
 **Meta**