@nklisch/pi-agile-workflow 0.15.3 → 0.16.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agile-workflow",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner. See docs/VISION.md.",
-  "version": "0.15.3",
+  "version": "0.16.3",
   "author": {
     "name": "nklisch"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agile-workflow",
-  "version": "0.15.3",
+  "version": "0.16.3",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner.",
   "author": {
     "name": "nklisch"

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Autonomous review convergence
+
+- **Removed the two-bounce circuit-breaker** — autopilot no longer parks an item
+  at review or blocks the run after two failed correction passes. Review findings
+  re-enter implementation until they pass; recurring findings trigger deeper
+  root-cause/design diagnosis and fresh context where useful. Only a separate,
+  genuine blocker may stop autonomous progress.
+
 ### Dynamic subagent prompting
 
 - **No shipped custom agents** — removed agile-workflow's Claude/Pi agent

package/docs/ARCHITECTURE.md

@@ -59,14 +59,19 @@ An item flows through tiers as work progresses on it.
                        (design written into body; child stories spawned)
                               │
                               ▼
-                  /implement-orchestrator (default; scope-driven,
-                  cross-feature waves) or /implement (inline alternative)
+                  /implement-orchestrator (delegated topology)
+                  or /implement (cohesive inline delivery)
                               │
                               ▼
                        stage: review
+                  (real state; optional stop boundary)
                               │
                               ▼
-                       /review (advance to done)
+                  risk-appropriate /review lane
+                  (production skills invoke it by default)
+                              │
+                              ▼
+                       stage: done
                               │
             ┌─────────────────┼─────────────────┐
             ▼                 ▼                 ▼
@@ -98,11 +103,20 @@ Stages advance only when work completes; they are never pre-populated.
 
 | Kind | drafting | implementing | review | done |
 |---|---|---|---|---|
-| epic | initial state when scoped | once children are designed and started | once all children are at review/done | once all children are at done |
-| feature | initial state when scoped | once design is written into body and acceptance criteria clear | once code lands and tests pass | once user-facing review approves |
-| story | optional initial state | initial state more often (skips drafting) | once code lands | once user/code-review approves |
+| epic | initial state when scoped | once children are designed and started | once all children are terminal and the epic is ready for its own review | once the epic's selected review lane approves |
+| feature | initial state when scoped | once design is written into the body and acceptance criteria are clear | once implementation is verified, or all child work is terminal, and the feature is ready for its own review | once the feature's selected review lane approves |
+| story | optional initial state | initial state more often (skips drafting) | once implementation and required verification complete | once the story's selected review lane approves |
 | release | initial state when cut | once gates begin running (`stage: quality-gate`) | n/a | n/a — terminal stage is `released` |
 
+`review` is a real state but not a mandatory user handoff. `implement`, `fix`,
+and `implement-orchestrator` continue through the selected review lane in the
+same invocation by default. An explicit `stop-at-review` request or stable
+project convention leaves the item there. Approval advances to `done`; a bounce
+returns to `implementing` with durable findings, and blockers remain recorded in
+the item body. Child completion only makes an ancestor eligible for its own
+review: conservative roll-up never substitutes child evidence for parent
+approval.
+
 The PostToolUse hook auto-bumps `updated:` whenever an item file is edited;
 skills only need to advance `stage:` explicitly.
 
@@ -291,7 +305,7 @@ git log --since='1 day ago' -- .work/
 ## Foundation docs (rolling-forward principle)
 docs/ holds standing context: VISION.md, SPEC.md, ARCHITECTURE.md, etc.
 - Foundation docs describe the system's current state or intended future state
-- Never add "previously this was…" or "note: in v1.2 we…"
+- Never retain superseded behavior descriptions or versioned migration notes
 - When implementation changes a foundation-doc assertion, update the doc
 - Git history is the audit trail; the doc carries the active truth
 ````
@@ -336,45 +350,29 @@ Direct skill invocation remains supported: `/agile-workflow:autopilot
 maintain a progress file; harness goal/continuation owns long-running
 persistence and `.work/active/` is the resume point.
 
-### Pre-flight: align on strategic questions first
-
-**Before kicking off autopilot, run `epic-design --only-questions` over the
-epics you're about to drain.** This is the single highest-leverage step in
-the agile-workflow loop and should generally always be done.
-
-```bash
-# Per-epic — align on one epic before autopilot picks it up
-/agile-workflow:epic-design --only-questions <epic-id>
-
-# Cover the whole active queue at once — recommended before a --all autopilot goal
-/agile-workflow:epic-design --only-questions --all
-```
-
-What the pass does (see `epic-design` SKILL Phase 4.7): for each epic at
-`stage: drafting`, it grounds in foundation docs + codebase, surfaces the
-2–5 directional product / architecture / scope questions specific to that
-epic, asks the user via `AskUserQuestion`, and writes the answers under
-`## Design decisions` in the epic body. It does NOT decompose into child
-features and does NOT advance stage — that's left to the real design pass.
-
-Why it matters:
-
-- **Autopilot inherits the answers.** When `epic-design` (full pass) runs
-  later under autopilot, it reads the already-captured `## Design decisions`
-  and skips Phase 4.7 — no autonomous judgment on directional choices,
-  because they're already locked in by the user.
-- **Cheap up front, expensive later.** Five minutes of interactive Q&A on
-  the whole drafting queue prevents autopilot from committing to a wrong
-  architectural direction across multiple features before the user notices.
-- **One human checkpoint instead of N.** A single `--only-questions --all`
-  pass answers every strategic question across the queue in one sitting,
-  rather than autopilot pausing per-epic mid-run (or worse, not pausing and
-  guessing).
-
-`--only-questions` mode refuses to run under autopilot itself — it's
-explicitly a pre-autopilot, human-in-the-loop step. The right invocation
-shape is: `--only-questions --all` first, review the captured decisions,
-then start an autopilot goal for `--all` (or `<epic-id>`).
+### Strategic alignment before autonomous work
+
+Normal design resolves routine, reversible decisions with judgment and records
+the rationale. Use the structured question tool only for choices that set
+product direction, materially affect user-facing behavior or an external
+contract, or commit the project to an expensive, difficult-to-reverse path.
+
+`epic-design --only-questions <id>` (or `--all`) remains the explicit
+interactive alignment mode when the operator wants those strategic decisions
+captured under `## Design decisions` before autonomous work. It does not design,
+decompose, or advance an item, and it refuses to run inside autopilot. Autopilot
+does not stop for ordinary ambiguity: it uses the existing decisions and
+foundation evidence, chooses the least irreversible sound path, and records the
+rationale.
+
+Advisory review follows risk in both direct and autopilot design. Independent
+review uses completeness/advisory before adversarial posture, is labeled
+cross-model only for a known different model class, and is non-blocking at
+design time. Final autopilot completion still requires the successful review
+path selected by the effective review weight. The receiving orchestrator owns
+finding disposition: it verifies reviewer proposals in repository context,
+keeps only credible material current-cycle risks blocking, and parks valid
+lower-priority work in the unbound backlog.
 
 ### Queue selection algorithm
 
@@ -392,22 +390,52 @@ then start an autopilot goal for `--all` (or `<epic-id>`).
    - created ascending (FIFO tie-break)
 5. Pop the first item.
 6. Work it:
-   - if drafting → invoke /design (or /refactor-design / /perf-design by tag)
+   - if drafting → invoke the design skill selected by kind and tags
    - if implementing → invoke /implement-orchestrator with the autopilot
-     scope (the picked item is an anchor; the orchestrator drains the whole
-     in-scope implementing band as one batch, cross-feature is fine).
-     /implement is reserved for the inline small-delivery case.
-   - if review → invoke /review (autonomous: produces verdict, advances
-     review→done or sends back to implementing)
-7. Advance stage on completion. Commit.
-8. Goto 1 unless stop condition.
+     scope (the picked item is an anchor; the orchestrator derives execution
+     topology from the unified graph, ownership, repository shape, and risk).
+     Use /implement when one cohesive delivery is safer in the host context.
+   - if review → invoke /review (autonomous: produces a verdict, advances
+     review→done, or sends the item back to implementing)
+7. Re-read substrate state after the production skill returns; it may already
+   have completed review and eligible parent roll-up. Commit each item
+   transition separately.
+8. If review bounced an item, treat only receiver-confirmed material blockers as
+   the next implementation input and keep cycling implementation → verification
+   → review. Park valid lower-priority findings unbound; they do not reopen the
+   scoped queue. Bounce count is diagnostic history, never a stop condition.
+   Recurring blockers trigger deeper root-cause/design diagnosis and fresh
+   context where useful, but repetition alone does not elevate severity.
+9. Goto 1 unless a stop condition applies.
 ```
 
+The implementation orchestrator guarantees outcomes rather than prescribing a
+recipe: dependency-graph scheduling, cycle validation, write-set-independent
+parallelism, explicit ownership, per-wave integration verification, one commit
+per item, worker self-containment, and conservative parent roll-up. It chooses
+bundle shape, wave width, isolation, and worker briefs for the actual work; no
+fixed sizes or prompt templates are part of the contract. Worker capability is
+chosen from scope and risk unless an explicit caller or stable project
+convention overrides it, and the choice is recorded rather than routinely
+asked.
+
+Autopilot resolves one effective `review_weight` for the run: explicit
+invocation selector, then `.work/CONVENTIONS.md`, then `standard`. The five
+levels — `none`, `light`, `standard`, `thorough`, and `maximum` — scale
+independent-review intent from administrative evidence-only closure through
+multi-model, multi-pass review. They do not prescribe reviewer counts or exact
+orchestration. Even `none` requires green implementation verification and
+acceptance evidence.
+
 ### Stop conditions
 
 - Empty queue (all candidates exhausted)
 - User invokes a halt command or sends a manual prompt
-- A skill reports a blocker that can't be resolved autonomously
+- A skill reports a genuine blocker that autonomous diagnosis and correction
+  cannot resolve
+
+Repeated review bounces are not a stop condition. Autopilot keeps correcting and
+re-reviewing until the item passes or exposes a separate genuine blocker.
 
 ### Harness goal continuation
 
@@ -476,6 +504,9 @@ session epoch:
 Code-design capsule:
 - Ports & Adapters: keep domain logic independent of DB/filesystem/HTTP/time/randomness.
 - Single Source of Truth: define growing variant sets once; derive downstream behavior.
+- Proportional rigor: validate real boundaries; add invariants, edge handling, and determinism only when context warrants them.
+- Code economy: prefer the shortest clear solution; test useful interfaces, complex units, and bug regressions.
+- Leave it simpler: eliminate unnecessary code, tests, checks, abstractions, and compatibility paths; ask before reducing guarantees.
 ...
 ```
 
@@ -524,14 +555,19 @@ Override via `gates_for_release` in `.work/CONVENTIONS.md`.
 
 ### Gate-as-item-producer pattern
 
-Each gate scans the bundle of items at `release_binding: <current-version>`
-and produces new items rather than emitting a pass/fail report:
+Each gate focuses on the bundle of items at
+`release_binding: <current-version>` and produces new items rather than
+emitting a pass/fail report. The bundle is a center of gravity, not a hard scan
+boundary: gates may follow concrete evidence into adjacent dependencies, shared
+infrastructure, or system-wide mechanisms. Findings caused by, exposed by, or
+materially relevant to the release bind to it; merely ambient discoveries go
+to the unbound backlog so the gate does not silently expand release scope.
 
 | Gate | What it scans | What it produces |
 |---|---|---|
 | `gate-security` | Bound items' code changes against security checklist | Items with `gate_origin: security`, tagged `[security]`, `release_binding` set |
-| `gate-tests` | Coverage of bound items' acceptance criteria | Items with `gate_origin: tests`, tagged `[testing]` for gaps |
-| `gate-cruft` | Dead code introduced or revealed by the bundle | Items with `gate_origin: cruft`, tagged `[cleanup]` |
+| `gate-tests` | Useful coverage at stable interfaces, complex units, and bug regressions; low-value tests exposed by the bundle | Items with `gate_origin: tests`, tagged `[testing]` for valuable gaps or removals |
+| `gate-cruft` | Local or system-wide code, tests, checks, compatibility paths, and abstractions that may no longer earn their cost | Items with `gate_origin: cruft`, tagged `[cleanup]`; guarantee-reducing removals require user confirmation |
 | `gate-docs` | Foundation-doc alignment with the bundle's behavior changes | Items with `gate_origin: docs`, tagged `[documentation]` — enforces rolling-foundation |
 | `gate-patterns` | Reusable patterns that emerged in the bundle | Detailed pattern-skill files in `.agents/skills/patterns/` (single source of truth) with optional Claude mirror, the generated hook-loaded `.agents/rules/patterns.md` digest (slug+one-liner index pointing back at the skill, with banner + source hash), plus a tracking item with `gate_origin: patterns` |
 
@@ -642,6 +678,15 @@ cross-model only when the host explicitly spawns the subagent with a different
 model class; otherwise use `peeragent` only when a cross-harness different model
 class is needed and allowed.
 
+Concrete model guidance lives in `skills/principles/references/models.md` and is
+resolved against current availability when selection matters. GPT-5.6 Luna is
+the implementation workhorse; Sol is preferred for design, review, complex code,
+and as the low-thinking bridge above Luna; Terra is a situational middle pick;
+and Claude Fable is a high-cost design, orchestration, and review specialist
+rather than the default implementer. These are capability recommendations, not
+fixed routing. Luna, Terra, Sol, and Codex share OpenAI lineage, so moving among
+them can provide fresh context but is not cross-model evidence.
+
 ### Bootstrap (user-invocable only)
 
 | Skill | Role | Trigger |
@@ -656,7 +701,7 @@ class is needed and allowed.
 |---|---|---|
 | `park` | Capture an unscoped idea, context note, or roadmap-style thought into `.work/backlog/`. Minimal frontmatter; body sized to the supplied context. | "park this", "remind me about X", "add to backlog" |
 | `scope` | Promote backlog item or fresh request to `.work/active/`. Sizes as epic/feature/story. If large, rolls foundation docs forward. Declares dependencies. | "scope this", "promote this", "let's track this" |
-| `fix` | Park-and-implement quick bug as a story. Single-stride: creates story at `stage: implementing`, writes fix, advances to review. | "fix bug X", "fix the typo in", "fix this issue" |
+| `fix` | Diagnose a verified bug as a cohesive story, reproduce it, add the failing test, apply the bounded repair, verify it, and continue through the selected review lane to `done` by default. Honors an explicit `stop-at-review` boundary and records bounces/blockers. | "fix bug X", "fix the typo in", "fix this issue" |
 | `groom` | Backlog-hygiene sweep over `.work/backlog/`. Classifies items DONE/SUPERSEDED/DUPLICATE/STALE/MERGEABLE/VALID via mechanical signals (`work-view --stale`, missing-field, cites-done-work) + a grounded semantic pass; writes a triage report. Propose-not-prune: dispositions are operator-confirmed and route through terminal-tier retention; never auto-prunes. Not a release gate. Opt-in; staleness face inert unless `backlog_staleness_days` is set. | "groom the backlog", "backlog hygiene", "find stale/dead/duplicate items" |
 
 ### Design family (model-invocable, kind- and tag-routed)
@@ -672,14 +717,19 @@ class is needed and allowed.
 
 | Skill | Role | Trigger |
 |---|---|---|
-| `implement-orchestrator` | Default. Orchestrates implementation sub-agents over a scope (feature, epic, --all, or explicit list). Builds a unified `depends_on` graph across the scope (cross-feature is fine), chooses bundles/waves/write-scope isolation, and advances every parent feature whose children all reach `review`. | item(s) at `stage: implementing` |
-| `implement` | Inline alternative. Read item body, write code, run build+tests, advance stage. | small / focused work where sub-agent fan-out wouldn't pay off, or user asks to implement inline |
+| `implement-orchestrator` | Delegated implementation over a feature, epic, `--all`, or explicit set. Derives ownership and waves from the unified dependency graph, write-set independence, repository shape, and risk; verifies every wave, keeps one commit per item, rolls eligible parents conservatively, and continues through review by default. | implementing scope where separate ownership, isolation, or sequencing improves the result |
+| `implement` | Cohesive inline delivery. Grounds in the item, implements and verifies it in the host context, records capability and evidence, then continues through the selected review lane to `done` by default. | work best kept under one ownership context, or an explicit inline request |
+
+Choose between these production lanes from cohesion, write ownership,
+dependency sequencing, isolation needs, and uncertainty. Line or file counts may
+inform judgment but never gate the choice. Both honor `stop-at-review`, and
+neither substitutes inline self-approval for a required fresh-context lane.
 
 ### Review & delivery (mixed invocability)
 
 | Skill | Invocability | Role | Trigger |
 |---|---|---|---|
-| `review` | model-invocable | Code review of changes for an item. Triages findings into items with proper tags. Advances to done if approved. | item at `stage: review` |
+| `review` | model-invocable | Selects fast, standard, or deep review from effective weight, risk, evidence, and kind as a heuristic; preserves fresh context for deep review, records durable findings, advances or bounces the item, and conservatively rolls approved children through each eligible ancestor's own review. | item at `stage: review` or explicit review target |
 | `board` | user-invocable | Launch the live localhost substrate board through `work-view board`. Opens a browser after binding when a desktop session is available; prints the URL in headless sessions. | User-invoked when the user wants to inspect active work visually |
 | `release-deploy` | user-invocable | Bind items to release, run gates, ship, archive. Idempotent. | User-invoked when ready to cut a version |
 | `bold-refactor` | user-invocable | Multi-feature architectural refactor. Scopes a refactor epic with child features. Aggressive — only on user request. | User-invoked |
@@ -703,11 +753,13 @@ configured in `CONVENTIONS.md` (default: security → tests → cruft → docs
 
 | Skill | Role | Notes |
 |---|---|---|
-| `principles` | Loads code-design + substrate-execution principles | Code-design (Ports & Adapters, SSOT, Generated Contracts, Fail Fast) carried from workflow; substrate-execution (item-IS-the-work, rolling-foundation, late-binding) added |
+| `principles` | Loads code-design + substrate-execution principles | Code-design includes clear boundaries, proportional rigor, code economy, useful tests, and continuous simplification; substrate-execution includes item-IS-the-work, rolling-foundation, and late-binding |
 | `research` | Investigate libraries/APIs | Carried; produces research docs in `docs/research/` (separate from `.work/`) |
 | `refactor-conventions-creator` | Create project-specific refactor conventions skill | Carried |
 
-(`repo-eval` and `tool-evaluator` were originally carried here. `repo-eval` now lives in the standalone `code-audit` plugin as the supported report-only scorecard, while `tool-evaluator` was extracted to `nates-toolkit` and renamed `agent-reflection`.)
+Holistic report-only repository scoring is provided by `code-audit:repo-eval`;
+end-of-session tool and skill reflection is provided by
+`nates-toolkit:agent-reflection`.
 
 ---
 

package/docs/PRINCIPLES.md

@@ -2,8 +2,8 @@
 
 The plugin's `principles` skill loads two distinct paradigms:
 
-- **Code-design principles** — Ports & Adapters, Single Source of Truth,
-  Generated Contracts, Fail Fast. Carried from the `workflow` plugin.
+- **Code-design principles** — clear boundaries and sources of truth,
+  proportional rigor, code economy, useful tests, and continuous simplification.
   These tell the agent how to write good code at design time and
   implementation time.
 - **Substrate-execution principles** — Item-IS-the-Work, Rolling-Foundation,
@@ -18,7 +18,7 @@ shapes how work moves through the system.
 
 # Part I — Code-Design Principles
 
-These four principles govern both architectural decisions and how code is
+These principles govern both architectural decisions and how code is
 written. Each section has guidance for design time and implementation time.
 
 ## 1. Ports & Adapters
@@ -213,21 +213,20 @@ If a generated type needs extending, use
 `type MyType = GeneratedType & { extra: string }` — extend the source of
 truth, don't replace it.
 
-## 4. Fail Fast (implementation only)
+## 4. Fail Fast—Where It Matters
 
-Catch bad data at the door, not three calls deep where the stack trace is
-useless. Validate inputs at the entry point of every function or system
-boundary.
+Catch bad data at real trust boundaries, not three calls deep. Validate
+untrusted input and required external contracts before domain logic runs. Add
+internal checks only where a violated precondition is plausible and
+consequential for this project.
 
 - At system boundaries (HTTP handlers, CLI args, external API responses,
-  config files): parse with Zod or equivalent before any logic runs
-- At internal function boundaries: assert preconditions at the top of the
-  function — guard clauses, not nested ifs
-- Prefer `throw`/`return early` over propagating bad state deep into call
-  chains
-- Errors should be loud and specific at the point of violation —
-  "expected positive number, got -3" beats a cryptic null reference five
-  layers down
+  config files): parse before logic runs
+- At internal boundaries: add guards when they protect a real invariant, not
+  mechanically at every function
+- Prefer early, specific failure when failure is part of the required contract
+- Do not manufacture exhaustive edge handling, invariants, retries, or firm
+  determinism that the project's scope and consequences do not need
 
 **Good:**
 ```typescript
@@ -250,6 +249,73 @@ function processOrder(input: any) {
 }
 ```
 
+## 5. Code Economy
+
+Short, direct code is a virtue when it stays clear. Prefer fewer concepts,
+layers, branches, options, and lines over speculative generality. Terse does not
+mean cryptic: simplify the model first, then its expression. Every abstraction
+or extension point must earn its maintenance cost in current scope.
+
+### At design time
+
+- Start with the most direct solution that satisfies the actual brief
+- Reject hypothetical flexibility without a current second use or committed need
+- Compare approaches by concepts removed as well as capabilities added
+
+### At implementation time
+
+- Delete obsolete paths and incidental machinery exposed by the change
+- Inline or consolidate before extracting another abstraction
+- Match rigor to the project's context rather than treating every codebase as
+  critical infrastructure
+
+## 6. Tests Earn Their Keep
+
+Tests are maintained code. Prioritize stable public interfaces, important seams,
+high-consequence behavior, and regressions learned from real bugs. Unit tests
+belong around genuinely complex isolated logic, not every wrapper, branch, or
+line. Coverage numbers are evidence, not goals.
+
+### At design time
+
+- Name the interface, risk, or regression each proposed test protects
+- Prefer one useful interface test over several implementation-bound unit tests
+- Do not require one automated test per unit, edge, or acceptance statement
+
+### At implementation time
+
+- Add regression tests when bugs reveal meaningful risk
+- Remove duplicate, tautological, brittle, obsolete, or low-value tests
+- Keep simple code simple when an isolated test adds no useful confidence
+
+## 7. Leave It Simpler
+
+Exploration, design, and implementation include an elimination pass. Look for
+code, tests, checks, abstractions, configuration, and compatibility paths the
+feature can make unnecessary. Fold safe cohesive cleanup into the task or create
+explicit cleanup/refactor stories; park broader opportunities.
+
+Question whole systems, not only local fragments. A validation layer, invariant
+system, test suite, compatibility mechanism, or defensive subsystem may no
+longer justify its cost. Removing behavior, guarantees, validation, determinism,
+compatibility, or safety is a product decision: explain the trade-off and ask
+the user rather than silently weakening it.
+
+### Review proportionality
+
+Reviewer output is evidence, not authority. The receiving agent verifies claims
+and judges their current-cycle risk against the repository's acceptance criteria,
+supported users and deployment shape, likelihood, blast radius, recoverability,
+safeguards, and delay cost. Credible material risks to required correctness,
+security, data, public contracts, acceptance, release safety, or trustworthy
+verification block. Valid lower-priority concerns are parked unbound; nits stay
+in review notes; unsupported advice is rejected with a brief rationale.
+
+A successful independent review path requires adjudicating every proposal, not
+implementing every suggestion. A rare severe case may still block, while a real
+corner case with negligible consequence need not. Reviewer labels, model
+strength, and repeated mention do not replace the receiving agent's judgment.
+
 ---
 
 # Part II — Substrate-Execution Principles
@@ -259,7 +325,7 @@ shape stage transitions, item bodies, foundation-doc evolution, and
 release binding. The agent applies these whenever operating on `.work/`
 or `docs/`.
 
-## 5. Item-IS-the-Work
+## 8. Item-IS-the-Work
 
 The unit of work is its file. The brief, the design, the implementation
 notes, and the review findings all accumulate in the item's body as
@@ -314,7 +380,7 @@ stages advance. Reading the file IS reading the state of the work.
 - [ ] Item body at completion is a complete record
 - [ ] Code does not reference item IDs; only logical concepts
 
-## 6. Rolling-Foundation
+## 9. Rolling-Foundation
 
 Foundation docs (`docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`,
 and any others) describe the project's vision (future-looking) and current
@@ -398,7 +464,7 @@ which timing style was used.
 - [ ] `git log docs/<file>.md` shows the audit trail; the doc shows the
       present
 
-## 7. Late-Binding
+## 10. Late-Binding
 
 Items advance stages when work actually completes. Releases bind items
 only when the user cuts a version. Foundation docs are not pre-decided

package/docs/SPEC.md

@@ -12,7 +12,7 @@ Located at `plugins/agile-workflow/.claude-plugin/plugin.json`:
 {
   "name": "agile-workflow",
   "description": "Markdown-based work-tracking substrate for AI-driven projects. Items as files in .work/, late-binding releases, gates that produce items, goal-backed autopilot queue runner. See docs/VISION.md.",
-  "version": "0.10.0",
+  "version": "0.15.3",
   "author": { "name": "nklisch" },
   "repository": "https://github.com/nklisch/skills",
   "license": "MIT"
@@ -81,7 +81,59 @@ release: planned → quality-gate → released
 task:    [ ] → [x]                       (checklist line in parent body)
 ```
 
-Stages advance only when work completes. No pre-population.
+Stages advance only when work completes. No pre-population. For epics,
+features, and stories, `review` is a real evaluation state and `done` means the
+selected review lane approved the item. It is not a mandatory user handoff:
+production skills drive verified work through the risk-appropriate review lane
+in the same invocation by default. An explicit `stop-at-review` request (or
+project convention) leaves the item at `review`. Approval advances to `done`;
+a review bounce returns the item to `implementing` with durable findings, and a
+blocker remains recorded in the item body.
+
+Review effort is selected from risk, evidence, effective `review_weight`, and
+item kind as a starting heuristic. Low-risk stories can close from recorded
+green verification, while risky stories, features, and epics receive the
+fresh-context coverage allowed by the effective weight. Child completion may
+make a parent eligible for its own review, but never approves the parent by
+itself. Fresh-reviewer findings are proposals: the receiving agent verifies and
+classifies them against repository context. Only credible material current-cycle
+risk blocks advancement; valid lower-priority findings are parked unbound.
+
+### Questions and advisory review
+
+Normal design resolves routine, reversible decisions with judgment and records
+the rationale. The structured question tool is reserved for choices that set
+product direction, materially change user-facing behavior or an external
+contract, or commit the project to an expensive, difficult-to-reverse path.
+`--only-questions` remains an explicit interactive alignment mode and does not
+design or advance an item; an active autopilot run instead chooses the least
+irreversible sound option and logs it.
+
+Advisory review is risk-driven in direct and autopilot modes. When independent
+review is warranted, completeness/advisory review precedes adversarial review,
+and a pass is called cross-model only when the reviewer is a known different
+model class. Design-time advisory failure is non-blocking; final autopilot
+completion must clear the review path required by its effective weight. The
+effective `review_weight` resolves from an explicit invocation, then project
+convention, then `standard`:
+
+- `none` — no independent reviewer; green implementation verification and
+  acceptance evidence are still required.
+- `light` — minimal independent ceremony with focused scrutiny where risk
+  clearly warrants it.
+- `standard` — balanced, risk-driven independent review.
+- `thorough` — increased fresh-context breadth and depth for meaningful risk.
+- `maximum` — multi-model, multi-pass complementary-then-adversarial review is
+  available for the highest-risk scopes.
+
+These levels state review intent and ceilings, not fixed reviewer counts or pass
+recipes. A successful review path requires every proposed finding to be
+adjudicated, not implemented. The receiving orchestrator weighs acceptance
+criteria, supported users and deployment shape, likelihood, blast radius,
+recoverability, safeguards, and delay cost. It fixes or activates material
+current-cycle blockers, parks valid lower-priority concerns in the unbound
+backlog, and rejects unsupported advice with a rationale. Reviewer labels and
+repetition are evidence, not authority.
 
 ### Backlog item shape
 
@@ -153,12 +205,22 @@ gate_refactor_scan_library_roots:
   - .claude/skills
 binding_guard: warn
 epic_cohesion: phased
+review_weight: standard
 backlog_staleness_days: 90
 ```
 
 The default `gates_for_release` order is fixed: **security → tests → cruft
 → docs → patterns**. Override only if the project has a justified reason.
 
+Release-bound items define each gate's focus, not a hard scan boundary. A gate
+may follow concrete evidence into adjacent dependencies, shared infrastructure,
+or system-wide mechanisms. Findings caused by, exposed by, or materially
+relevant to the release bind to it. Merely ambient discoveries must be written
+to the unbound backlog, so wider inspection does not silently expand release
+scope. Any cruft proposal that reduces behavior, validation, determinism,
+compatibility, safety, or another meaningful guarantee requires explicit user
+confirmation before it becomes active removal work.
+
 **`gate-refactor` is an opt-in gate** — not in the default list. Add it when your project has
 scan-rule libraries installed under `gate_refactor_scan_library_roots` (defaults:
 `{project}/.agents/skills/scan-*/SKILL.md`, then
@@ -204,6 +266,12 @@ treats them as mismatches acted on per `binding_guard`, like CONFLICTs (the proj
 ship whole"). CONFLICTs (a child bound to a *different* version than its bound parent, or a done
 parent unbound while its children are bound) always follow `binding_guard` regardless of this dial.
 
+**`review_weight`** is optional and defaults to **`standard`** when absent. Valid values are
+`none`, `light`, `standard`, `thorough`, and `maximum`. An explicit invocation selector overrides
+the project value. The setting controls independent-review intent; it never relaxes implementation
+verification or acceptance evidence. The canonical level semantics and lane selection live in the
+`principles` and `review` skills rather than in project bootstrap configuration.
+
 **`backlog_staleness_days`** (integer; **absent ⇒ feature inert**) is the age threshold for the
 opt-in backlog staleness query `work-view --stale`. When set, `--stale` lists `.work/backlog/`
 items whose last-touched date — `updated` if present, else `created` — is more than this many days