@nklisch/pi-agile-workflow 0.15.3 → 0.16.3

package/skills/convert/SKILL.md

@@ -447,6 +447,9 @@ Run an interactive interview via structured question tool. Six questions, in ord
    leak to future agents. Offer `retain-bodies` only for projects that deliberately keep full terminal
    bodies on disk (same `archived_atop`/late-binding semantics, bodies just not pruned).
 
+Review weight is deliberately not another interview question. Bootstrap writes the balanced default
+in Phase 5; callers can change the project convention later or override it per invocation.
+
 ### Phase 4: Create substrate skeleton
 
 ```bash
@@ -467,11 +470,23 @@ environment, locate the plugin source via the active skill/plugin path or manife
 
 ### Phase 5: Write CONVENTIONS.md
 
-Write `.work/CONVENTIONS.md` from the interview answers, following the format in SPEC.md. The
-`## Terminal-tier retention` section is **value-only** — write the bare `delete-refs`/`retain-bodies`
-value the user chose, not the merged prose (the prose lives in SPEC.md, never duplicated per project).
-This bare-value form is exactly what a later sync classifies as `match`, so a freshly bootstrapped
-repo never self-reports terminal-retention drift.
+Write `.work/CONVENTIONS.md` from the interview answers, following the format in SPEC.md. Also add
+this non-interactive project default:
+
+```markdown
+## Review weight
+review_weight: standard
+```
+
+Allowed values are `none | light | standard | thorough | maximum`. The setting is optional: when it
+is absent, review and autopilot resolve it to `standard`. Keep the level semantics and selection
+policy in `principles/SKILL.md` Part IV and `review/SKILL.md`; do not duplicate their review matrix or
+model guidance here.
+
+The `## Terminal-tier retention` section is **value-only** — write the bare
+`delete-refs`/`retain-bodies` value the user chose, not the merged prose (the prose lives in SPEC.md,
+never duplicated per project). This bare-value form is exactly what a later sync classifies as
+`match`, so a freshly bootstrapped repo never self-reports terminal-retention drift.
 
 ### Phase 6: Write the canonical AGENTS.md section
 
@@ -613,6 +628,22 @@ must already exist at their new home or the dense content is lost.
    All other tags are project-specific (see `.work/CONVENTIONS.md`) and do not
    affect skill routing.
 
+   ### Engineering posture
+
+   Prefer short, clear code and context-appropriate rigor over speculative
+   generality. Not every project needs exhaustive invariants, edge handling,
+   firm determinism, or universal coverage. Test important interfaces, complex
+   units, and regressions learned from bugs—not every line. When touching an
+   area, eliminate unnecessary code, tests, checks, abstractions, and
+   compatibility paths; leave it simpler. Ask before removing meaningful
+   behavior, guarantees, validation, compatibility, or safety.
+
+   Release-bound items define a gate's focus, not a hard scan boundary. Gates
+   may follow concrete evidence into adjacent dependencies, shared
+   infrastructure, or system-wide mechanisms. Bind release-relevant findings;
+   route merely ambient discoveries to the unbound backlog so a scan does not
+   silently expand a release.
+
    ### Test integrity
 
    When running, writing, or modifying tests:
@@ -628,6 +659,11 @@ must already exist at their new home or the dense content is lost.
      green again, if a parked production bug is small enough for a single
      stride, pick it up immediately as `/agile-workflow:scope` → design →
      implement. Larger bugs stay in backlog for prioritization.
+   - **Tests must earn their upkeep.** Prefer tests at stable interfaces,
+     regression tests for real bugs, and unit tests for genuinely complex
+     units. Do not add tests merely to cover every line or surface; remove
+     duplicate, tautological, implementation-bound, or obsolete tests when
+     they add less confidence than maintenance cost.
    - **NEVER game a test to make it pass.** A failing test that documents
      *why* it fails — an inline comment naming the bug, a `skip` linked to a
      backlog id, an `xfail` with a reason — is more honest than a green test
@@ -639,8 +675,11 @@ must already exist at their new home or the dense content is lost.
    override agile-workflow defaults. When peeragent is available with a different
    model class, large/risky autopilot design decisions may use one advisory pass;
    small/low-risk work skips it. Autopilot also runs a final peer-review loop
-   before reporting completion and fixes or files accepted findings first.
-   Same-model peers fall back to local sub-agents instead. Claude Opus peeragent
+   before reporting completion. Reviewer findings are proposals: the receiving
+   orchestrator verifies them against repository context and actual risk. Only
+   credible material current-cycle risks block; park valid lower-priority
+   findings in the unbound backlog and continue. Same-model peers fall back to
+   local sub-agents instead. Claude Opus peeragent
    calls can take 10 to 30 minutes on large reviews; no return after a few minutes
    is not evidence that the call has hung.
 
@@ -655,7 +694,7 @@ must already exist at their new home or the dense content is lost.
    this managed-section overwrite — content verification, NOT just a non-empty +
    end-marker check): confirm `.agents/rules/agile-workflow.md` exists AND that the
    dense rule content the slim removes from AGENTS actually landed there — each
-   section is present (`### Tag semantics`, `### Test integrity`, the
+   section is present (`### Tag semantics`, `### Engineering posture`, `### Test integrity`, the
    advisory-review paragraph, and Broad entry points), or recompute per the Phase
    1.8 provenance check. Only when the content is verified present do you write or
    refresh the slim AGENTS section (Phase 6), overwriting the managed AGENTS block.
@@ -1047,6 +1086,10 @@ path list), plus deeper checks:
   - `.claude/rules/patterns.md` state (legacy content vs AGENTS shim)
   - `.work/CONVENTIONS.md` load-bearing tag entries (see below). The rest of
     CONVENTIONS is user-owned and untouched.
+  - `.work/CONVENTIONS.md` `review_weight` — preserve any existing value unchanged; review validates
+    the five-value boundary when it consumes the setting. Absence is also valid and resolves to
+    `standard`, so sync neither inserts the default into older projects nor asks a migration question.
+    The allowed values and canonical policy are in Phase 5.
   - `.work/CONVENTIONS.md` **Terminal-tier retention** state (the merged convention — see
     "Terminal-tier retention drift" below). The per-project CONVENTIONS template is **value-only** (a
     `## Terminal-tier retention` heading + a bare `delete-refs`/`retain-bodies` value); the merged
@@ -1337,9 +1380,10 @@ These are NEVER touched in sync mode:
   user confirmation, are: (a) load-bearing tag entries (`refactor`, `perf`) when they match a known
   prior plugin default verbatim, and (b) the `## Terminal-tier retention` convention when it is
   `missing`/`partial`/a bespoke `## Done-item archival` overlap (add / reconcile / converge). A bare
-  `delete-refs`/`retain-bodies` value is `match` and is left untouched. Everything
-  else in CONVENTIONS — release mapping, project tags, slug conventions, gate config, any user
-  prose — is untouched.
+  `delete-refs`/`retain-bodies` value is `match` and is left untouched. `review_weight` is optional
+  and is never added, reset, or rewritten by sync; preserve an existing value byte-for-byte, while
+  absence continues to mean `standard`. Everything else in CONVENTIONS — release mapping, project
+  tags, slug conventions, gate config, any user prose — is untouched.
 - Everything under `.work/active/`, `.work/backlog/`, `.work/releases/`,
   `.work/archive/`
 - User-authored rule references under `.agents/skills/refactor-conventions/`.

package/skills/epic-design/SKILL.md

@@ -125,9 +125,9 @@ Instead:
 
 ### Phase 2: Ground yourself
 
-The principles skill auto-loads — both code-design (Ports & Adapters, SSOT,
-Generated Contracts, Fail Fast) and substrate-execution (Item-IS-the-Work,
-Rolling-Foundation, Late-Binding) are active.
+The principles skill auto-loads — code-design includes proportional rigor, code
+economy, useful tests, and leaving touched areas simpler; substrate-execution
+includes Item-IS-the-Work, Rolling-Foundation, and Late-Binding.
 
 Read:
 1. `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md` — foundation that
@@ -207,6 +207,17 @@ Aim for 2-6 child features per epic. Fewer than 2 means the epic was probably
 sized as a feature; flag the user. More than 6 means you're slicing too thin;
 collapse.
 
+### Phase 4.4: Identify simplification arcs
+
+For each area the epic touches, ask what capabilities, code, tests, checks,
+abstractions, compatibility paths, or whole subsystems the new direction can
+make unnecessary. Prefer feature arcs that replace and remove over arcs that
+only layer on more machinery. Fold cohesive elimination into the owning feature
+brief or create an explicit `[refactor]`/`[cleanup]` child feature when it needs
+independent design and review. Park unrelated cleanup. Any arc that removes
+behavior or meaningful guarantees becomes a high-level design decision for user
+confirmation, not an assumed refactor.
+
 ### Phase 4.5: Identify cross-feature dependencies
 
 For each candidate feature, ask:
@@ -248,76 +259,25 @@ decomposition. Child briefs note "mockups pending — see parent epic" so
 
 Skip this phase entirely if `ux-ui-design` is not installed.
 
-### Phase 4.7: Surface high-level design ambiguities
-
-Read the epic and the candidate decomposition you've sketched, and derive
-specific, concrete high-level design questions about *this* epic's actual
-work. These are the directional choices that, if locked in now, will keep
-every child feature's later design pass aligned. Examples of the *shape* of
-question to surface (the actual content must come from the epic):
-
-- "For this epic's auth surface, do we use OAuth via the existing provider,
-  or roll a local session model?"
-- "Should the new sync engine push from server to client, pull from client
-  on-demand, or both?"
-- "Are we committing to multi-tenant data isolation in this epic, or is
-  single-tenant acceptable for v1?"
-- "Does the import pipeline need to handle CSV and Parquet, or just CSV?"
-
-These are product/architecture/scope questions specific to the epic in
-front of you — not generic prompts about boundaries, naming, or sizing.
-Skip anything you can answer from the epic body, foundation docs, or
-codebase. Skip anything that's safely a downstream feature-design call
-(function signatures, exact file paths, per-unit test approach).
-
-Aim for the smallest set of questions that meaningfully resolve direction
-— typically 2-5. Zero is fine if the epic body and foundation docs already
-pin every directional choice.
-
-**Cross-model advisory review under autopilot.** If this skill is running as a
-delegation from active autopilot, the epic has large/risky architectural
-decisions, and the body does not already contain useful `## Design decisions`
-from a prior `--only-questions` pass, apply the cross-model advisory review
-policy from `principles/SKILL.md` before resolving the questions yourself.
-
-Use one focused `peer` pass only when a different model class is available.
-Ask for missing questions, risks, ambiguous constraints, and alternatives for
-this epic's decomposition — not for a final verdict. Do not run the multi-pass
-`peer-review` loop during routine autopilot design. If peeragent is
-unavailable, the peer would use the same model class, or the invocation fails,
-continue with host judgment and note that the advisory pass was skipped.
-If the peeragent target is Claude Opus, allow 10 to 30 minutes for a large
-review; no return after a few minutes is not evidence that it has hung.
-
-Summarize the useful output under `## Other agent review` in the epic body and
-fold accepted questions/risks into the decisions you log. Do not paste the peer
-transcript into the item.
-
-If this skill is running **as a delegation from an active autopilot run or
-harness goal**, resolve each question with judgment (prioritize: consistent
-with foundation docs > simpler option > defers irreversible decisions) and log
-under `## Design decisions` in the epic body:
-
-```markdown
-## Design decisions
-- **<question>**: <choice> — <one-line rationale>
-```
+### Phase 4.7: Resolve high-level design decisions
 
-In every other invocation — including direct user invocation under harness
-auto mode (`permissions.defaultMode: "auto"`) — ask the user via
-`structured question tool` before locking in, then write the answers under `## Design
-decisions` in the epic body. Harness-level "work without pausing" reminders
-do **not** suppress these checkpoints. See `principles/SKILL.md` Part III
-for the full caller-awareness rule.
+Identify the epic-specific product, architecture, scope, and decomposition
+decisions that must align its child features. Ignore points settled by the epic,
+foundation docs, code, or an existing `## Design decisions` section, and leave
+function signatures, file paths, and unit-level tests to feature design. Zero
+open decisions is valid.
 
-The child feature briefs you write in Phase 6 should reference the relevant
-design decisions so each feature's later design pass inherits the locked-in
-direction.
+Apply `principles/SKILL.md` Part III exactly: resolve routine, reversible points
+with judgment and a logged rationale; reserve structured questions for product
+direction, external contracts, and expensive hard-to-reverse choices. Apply
+Part IV's risk-driven advisory policy in both direct and autopilot modes; do not
+restate reviewer topology here.
 
-The exception under autopilot: a 50/50 between two large irreversible
-choices (e.g., SQL vs document store for this epic's persistence layer).
-Append a `## Blocker` section and return without advancing — autopilot will
-skip and surface the blocker.
+Record decisions under `## Design decisions`. When autopilot is the active
+driver, it never asks; use evidence and the least irreversible sound choice.
+Only contradictory state that Part III identifies as a hard halt blocks
+advancement. Child briefs reference the decisions relevant to their later design
+passes.
 
 ### Phase 5: Pre-mortem
 
@@ -360,6 +320,9 @@ capability it covers, why it exists in this epic, what it does NOT cover>
 - Position in epic: <e.g., "foundation feature — others depend on its types"
   / "consumer of feature-X" / "independent capability">
 
+## Simplification opportunity
+- <what this feature should delete, consolidate, replace, or deliberately retain>
+
 ## Foundation references
 - `docs/VISION.md` — relevant section(s) (only if directly relevant)
 - `docs/ARCHITECTURE.md` — relevant component(s)
@@ -413,6 +376,10 @@ feature lands.">
 - `<feature-id-2>` — <one-line description> — depends on: `[<feature-id-1>]`
 - `<feature-id-3>` — <one-line description> — depends on: `[<feature-id-1>]`
 
+### Simplification arcs
+
+- <feature-id> — <code/tests/checks/abstractions/subsystems it should remove or consolidate>
+
 ### Decomposition risks
 
 <from pre-mortem, if any. Otherwise omit the section.>

package/skills/feature-design/SKILL.md

@@ -146,9 +146,9 @@ The body should already have a brief from `scope`. Use it as the seed for design
 
 ### Phase 2: Ground yourself
 
-The principles skill auto-loads — both code-design (Ports & Adapters, SSOT,
-Generated Contracts, Fail Fast) and substrate-execution (Item-IS-the-Work,
-Rolling-Foundation, Late-Binding) are active.
+The principles skill auto-loads — code-design includes proportional rigor, code
+economy, useful tests, and leaving touched areas simpler; substrate-execution
+includes Item-IS-the-Work, Rolling-Foundation, and Late-Binding.
 
 Read:
 1. `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md` (foundation docs that
@@ -201,68 +201,29 @@ agent rules (tag semantics, test integrity, review policy). Treat AGENTS as
 canonical if they disagree. Recency improves adherence. Confirm your approach
 aligns with project conventions.
 
-### Phase 4.5: Surface ambiguities
-
-Read the feature brief and the design space you've started to map, and
-derive specific, concrete design questions about *this* feature's actual
-work — requirements gaps, architecture trade-offs, scope boundaries,
-integration assumptions, UX decisions. The questions must come from the
-feature in front of you; examples of the *shape* only:
-
-- "Should the cache invalidate on write or rely on TTL only?"
-- "Does the upload accept multipart, or a presigned URL flow?"
-- "When the parser hits a malformed row, do we skip and continue or fail
-  the whole batch?"
-- "Is paging cursor-based or offset-based?"
-
-Skip anything the brief, parent epic body, foundation docs, or codebase
-already pin. Skip anything that's safely an implementation-time call.
-
-Aim for the smallest set of questions that meaningfully resolve direction
-— typically 2-5. Zero is fine if everything's already pinned.
-
-**Cross-model advisory review under autopilot.** If this skill is running as a
-delegation from active autopilot, the feature has large/risky architectural
-decisions, and the body does not already contain useful `## Design decisions`
-from a prior `--only-questions` pass, apply the cross-model advisory review
-policy from `principles/SKILL.md` before resolving the questions yourself.
-
-Use one focused `peer` pass only when a different model class is available.
-Ask for missing questions, risks, ambiguous constraints, and alternatives for
-this feature's design — not for a final verdict. Do not run the multi-pass
-`peer-review` loop during routine autopilot design. If peeragent is
-unavailable, the peer would use the same model class, or the invocation fails,
-continue with host judgment and note that the advisory pass was skipped.
-If the peeragent target is Claude Opus, allow 10 to 30 minutes for a large
-review; no return after a few minutes is not evidence that it has hung.
-
-Summarize the useful output under `## Other agent review` in the feature body
-and fold accepted questions/risks into the decisions you log. Do not paste the
-peer transcript into the item.
-
-If this skill is running **as a delegation from an active autopilot run or
-harness goal**, resolve each question with judgment (prioritize: consistent
-with foundation docs > simpler option > defers irreversible decisions) and log
-under `## Design decisions` in the body:
+### Phase 4.5: Resolve design decisions
+
+Identify concrete decisions raised by this feature's requirements, architecture,
+scope, integrations, and UX. Ignore points already settled by the brief, parent,
+foundation docs, code, or an existing `## Design decisions` section, and defer
+safe implementation details. Zero open decisions is valid.
+
+Apply `principles/SKILL.md` Part III exactly: resolve routine, reversible points
+with judgment and a logged rationale; reserve structured questions for product
+direction, external contracts, and expensive hard-to-reverse choices. Apply
+Part IV's risk-driven advisory policy in both direct and autopilot modes; do not
+restate reviewer topology here.
+
+Record decisions in the feature body:
 
 ```markdown
 ## Design decisions
-- **<question>**: <choice> — <one-line rationale>
+- **<decision>**: <choice> — <one-line rationale>
 ```
 
-If the body already contains a `## Design decisions` section (from a prior
-`--only-questions` pass or from `epic-design` Phase 4.7), treat those
-locked-in answers as inputs — do NOT re-ask them.
-
-In every other invocation — including direct user invocation under harness
-auto mode (`permissions.defaultMode: "auto"`) — ask the user via
-`structured question tool` before locking in. Harness-level "work without pausing"
-reminders do **not** suppress these checkpoints. See `principles/SKILL.md`
-Part III for the full caller-awareness rule.
-
-The exception under autopilot: a 50/50 between two large irreversible choices
-(e.g., SQL vs document store). Append a `## Blocker` section and return
-without advancing — autopilot will skip and surface the blocker.
+When autopilot is the active driver, it never asks; use evidence and the least
+irreversible sound choice. Only contradictory state that Part III identifies as
+a hard halt blocks advancement.
 
 ### Phase 4.6: UI surface fallback (runs when ux-ui-design is installed)
 
@@ -320,6 +281,17 @@ For each unit, specify:
 
 Make strong decisions about abstractions, naming, and module boundaries.
 
+#### 5d. Elimination and cleanup pass
+
+Before adding another unit or abstraction, ask what this feature can delete,
+inline, consolidate, or make unnecessary in the area it touches. Consider code,
+tests, checks, configuration, compatibility paths, and existing abstractions.
+Fold safe cohesive cleanup into a unit. Create explicit `[refactor]` or
+`[cleanup]` child stories when the cleanup is worthwhile but independently
+reviewable; park broader work. If a candidate reduces behavior or guarantees,
+record it as a design decision for user confirmation rather than assuming
+removal.
+
 ### Phase 5.5: Pre-mortem
 
 Before finalizing, attack the design:
@@ -334,12 +306,20 @@ feature body.
 
 ### Phase 6: Test approach
 
-For each unit, design:
-- **Unit tests** — behaviors to verify, edge cases, error paths
-- **Integration points** — where does this unit meet other units; what tests prove the seams
-- **Test data** — fixtures, factories, seed data needed
-
-If a unit is hard to test, the design is probably wrong. Note it and revise.
+Design the smallest useful test surface:
+- **Interface tests** — important behavior at stable public boundaries and
+  cross-unit seams
+- **Regression tests** — bugs or demonstrated risks this work must not repeat
+- **Unit tests** — only for genuinely complex isolated logic where examples add
+  confidence
+- **Test removal** — duplicate, tautological, obsolete, or implementation-bound
+  tests this change can safely retire
+- **Test data** — only fixtures or factories the chosen tests actually need
+
+Do not create a test for every unit, branch, edge, or acceptance statement by
+default. State what risk or contract each proposed test protects. Hard-to-test
+important behavior may indicate a bad boundary; simple code needing no isolated
+test is not itself a design flaw.
 
 ### Phase 7: Order and child stories
 
@@ -418,9 +398,13 @@ Update the feature file. Append (after the existing brief) sections like:
 1. <unit / story>
 2. <unit / story>
 
+## Simplification
+- <code/tests/checks/abstractions removed, consolidated, or intentionally retained>
+- <cleanup/refactor stories, if any>
+
 ## Testing
-### Unit Tests: `tests/path/<name>.test.ext`
-<test approach for each unit>
+- <interface, regression, or complex-unit tests and the value each protects>
+- <low-value tests to remove, if any>
 
 ## Risks
 <from pre-mortem, if any>

package/skills/fix/SKILL.md

@@ -2,20 +2,19 @@
 name: fix
 description: >
   ALWAYS invoke this skill when the user asks to fix a specific verified bug — do not just edit code
-  inline. Diagnoses and repairs a specific bug as a single-stride substrate story. Reproduces the
-  issue, identifies the root cause, writes a failing test, applies the minimal fix, confirms, and
-  creates a story item under .work/active/stories/ at stage:review capturing the work. Use when
-  something is verifiably broken — not for unverified hunches, refactors, or feature additions.
-  Triggers on "fix bug X", "fix the typo in", "fix this issue", "this is broken — fix it", and "patch
-  this item".
+  inline. Diagnoses and repairs the bug as a focused substrate story: reproduces it, identifies the
+  root cause, writes a failing test, applies the minimal fix, verifies it, and continues through
+  review to done unless the caller requests stop-at-review. Use when something is verifiably broken,
+  not for unverified hunches, refactors, feature additions, or architectural work. Triggers on "fix
+  bug X", "fix the typo in", "fix this issue", "this is broken — fix it", and "patch this item".
 ---
 
 # Fix
 
-You diagnose and repair a specific reported bug, capturing the work as a single
-substrate story that lands at `stage: review`. The discipline is the same as a
-careful bug-fix workflow — reproduce, diagnose to root cause, write a regression
-test, apply the minimal fix, confirm — but the artifact is a substrate item, not
+You diagnose and repair a specific reported bug, capturing the work as a focused
+substrate story that completes through its review lane by default. The discipline
+is reproduce, diagnose to root cause, write a regression test, apply the minimal
+fix, confirm, and honor review's verdict. The artifact is the substrate item, not
 a separate fix doc.
 
 ## When to invoke
@@ -128,46 +127,65 @@ for separate consideration — don't bundle.
 
 If any step fails, return to diagnosis. Do not ship a fix you can't confirm works.
 
-**Test integrity during Phase 6.** If running the full suite surfaces
-*other* failing tests:
+**Test integrity during Phase 6.** Follow the project's test-integrity rules and
+the worker posture in `../principles/references/subagents.md`: fix bad tests
+in-session, park other production bugs rather than bundling them, and never game
+a test to make it pass.
 
-- Bad tests (stale fixtures, drifted assertions, broken mocks) → fix
-  in-session if the fix is small and scoped to this bug's surface area;
-  otherwise park.
-- Pre-existing real production bugs → park via `/agile-workflow:park`.
-  Do NOT bundle them into this fix's commit; this skill is for *one*
-  bug.
-- NEVER make a test pass by weakening its assertion or silencing it
-  without a documented reason. The regression test you wrote in Phase 3
-  must verify behavior, not "whatever the code returns now".
+### Phase 7: Commit and complete the lifecycle
 
-### Phase 7: Advance to review and commit
-
-1. Update story stage: `implementing → review`. The PostToolUse hook auto-bumps `updated:`.
-2. Append an "Implementation notes" section to the story body capturing:
+1. Update the story stage: `implementing → review`. The PostToolUse hook
+   auto-bumps `updated:`.
+2. Append an "Implementation notes" section capturing:
+   - Execution capability selected from risk and scope, plus the rationale
+   - Effective `review_weight` and its source
    - Files changed
    - Test added
-   - Adjacent issues parked (with their backlog ids)
-3. Commit:
+   - Adjacent issues parked (with backlog ids)
+
+   Choose capability without a routine model-tier question unless the caller or
+   project explicitly overrides it. Resolve review weight from an explicit caller
+   override, then project convention, otherwise `standard`; the principles and
+   review skills own the weight matrix.
+3. Commit the fix:
    ```bash
    git add .work/active/stories/<id>.md <changed-files> <test-file>
    git commit -m "fix: <short description> (<story-id>)"
    ```
+4. Unless the caller explicitly requested `stop-at-review` (including "stop at
+   review", "leave at review", or "hand off for review") or a project convention
+   sets that boundary, invoke `/agile-workflow:review <id>` in the same invocation
+   and forward the effective `review_weight`. The review lane owns its required
+   context and verdict:
+   - approve: advance and commit `review → done`
+   - bounce: append `## Review findings`, return the story to `implementing`, and
+     report the bounce
+   - blocker: append `## Blocker` and report it without claiming completion
+
+A weight of `none` skips independent review, but the review lane still requires
+the same green verification and acceptance evidence before administrative
+closure. Review remains a real lifecycle act, not silent self-approval. With
+`stop-at-review`, leave the committed story at `review` and report the explicit
+boundary.
 
 ## Output
 
 Brief report in conversation:
-- **Story**: `<id>` at `stage: review`
+- **Story**: `<id>` at `stage: done`, `stage: review` by explicit override, or
+  `stage: implementing` after a documented bounce
+- **Review**: lane verdict, limitation, or blocker
 - **Root cause**: one sentence
 - **Fix**: file(s) changed
-- **Test**: file path, what it asserts
-- **Parked for separate consideration**: any adjacent issues you noticed but didn't bundle
+- **Test**: file path and behavior asserted
+- **Execution capability**: choice and rationale
+- **Review weight**: effective value and source
+- **Parked for separate consideration**: adjacent issues not bundled
 
 ## Guardrails
 
 - Do NOT skip the test (Phase 3). Fixes without tests recur.
 - Do NOT bundle refactoring or unrelated improvements into the fix's commit.
-- Do NOT advance the story past `review` — the user reviews and runs
-  `/agile-workflow:review` to advance to `done`.
-- If the fix would touch > 5 files or change a public interface, stop. This isn't a
-  fix; it's a feature with refactor implications. Use `/agile-workflow:scope` instead.
+- Do not self-approve at `review`; invoke the review lane and honor its verdict.
+- Broad scope (for example, many files, a public-interface change, or multiple
+  subsystems) is a signal that this is a feature rather than a targeted fix, not
+  a review-stop rule. Route it through `/agile-workflow:scope`.