@nklisch/pi-agile-workflow 0.15.3 → 0.16.1

package/skills/principles/references/advisory-review.md

@@ -0,0 +1,69 @@
+# Advisory Review Mechanics
+
+The detailed companion to the risk-driven invariants in
+`principles/SKILL.md` Part IV. Model classes, host-to-peer pairing, and concrete
+peer mechanism flags remain in [models.md](models.md).
+
+## Review weight and scope defaults
+
+Start from the effective `review_weight` in Part IV (`standard` when unset), then
+adapt to risk. `light` narrows independent breadth, `thorough` raises
+fresh-context scrutiny, and `maximum` permits multi-class multi-pass depth;
+`none` skips this independent-review table without skipping implementation
+verification or acceptance evidence. These are ceilings and intent, never fixed
+reviewer or pass counts.
+
+Apply the scope defaults below in both direct and autopilot design modes.
+Explicit caller and project review rules override them.
+
+| Scope and risk | Default |
+|---|---|
+| Small, low-risk | Skip advisory review. |
+| Small or medium with material uncertainty | Optionally run one focused different-class pass. |
+| Large, risky, or architectural, without prior `--only-questions` / `## Design decisions` alignment | Run one focused different-class pass when available. |
+| Deep or complex | Use two different model classes across the two phases when available. |
+| Completed feature or epic in a deep review lane | Use a fresh-context lens review; prefer different-class, otherwise strongest same-harness fresh context. |
+| Final autopilot completion | Run the required fresh-context completion path described in Part IV. |
+
+Stories normally fast-advance on recorded green verification, but risk can
+escalate them. Use a full iterative review loop for a completed substantial
+artifact or explicit review request only when that depth is warranted.
+
+## Two-phase mechanics
+
+Always run completeness before attack:
+
+1. **Completeness / complementary / advisory.** Ask what is missing, which
+   alternatives strengthen the artifact, and which questions or risks deserve
+   weight. An open design gets one pass before decisions lock. A complete
+   artifact can iterate until substantive findings stabilize; when a dedicated
+   iterative mechanism exists, converge to nits and cap the loop at roughly five
+   passes rather than chasing perfection.
+2. **Adversarial.** After Phase 1, ask what is broken, contradictory, based on a
+   false assumption, or likely to fail in operation. Open designs get a focused
+   attack pass; completed artifacts may use the same bounded convergence shape.
+   Verify concrete claims before accepting them.
+
+For deep or complex work, use a different model class for Phase 2 than Phase 1
+when two classes are available. Their disagreement is evidence to investigate,
+not a vote. For routine design, do not turn a focused advisory pass into a
+multi-pass review loop.
+
+## Recording the result
+
+Summarize evidence and decisions in the item body; never paste transcripts:
+
+```markdown
+## Other agent review
+- Invoked because: <risk or uncertainty>
+- Phase 1 — advisory/completeness: <reviewer class and useful gaps>
+- Phase 2 — adversarial: <reviewer class and failure modes>
+- Accepted: <adjustments with phase>
+- Rejected: <points and reasons with phase>
+- Skipped/degraded: <phase and reason, if any>
+```
+
+If only one phase or class was warranted or reachable, record that fact. Limit
+normal design to one advisory pass per item per design stage. The final
+autopilot completion review is separate and follows the stricter completion
+invariant in Part IV.

package/skills/principles/references/code-design.md

@@ -0,0 +1,107 @@
+# Code-Design Mechanics
+
+The detailed companion to the load-bearing code-design capsule in
+`principles/SKILL.md` Part I. Load this when a design or implementation needs
+concrete boundary guidance, checklists, or examples.
+
+## Contents
+
+1. [Ports & Adapters](#1-ports--adapters)
+2. [Single Source of Truth](#2-single-source-of-truth)
+3. [Generated Contracts](#3-generated-contracts)
+4. [Fail Fast](#4-fail-fast)
+
+## 1. Ports & Adapters
+
+At design time, identify every database, filesystem, HTTP, queue, clock, and
+randomness dependency. Define the interface the domain needs in the domain
+layer; implement it in infrastructure; wire the adapter only at a composition
+root. Domain functions receive ports as typed parameters and never import
+adapters directly.
+
+```text
+src/
+  domain/ports.ts         # UserRepository, EmailSender
+  domain/user-service.ts  # imports ports, not infrastructure
+  infrastructure/db.ts    # implements UserRepository
+  app/wire.ts             # assembles domain + adapters
+```
+
+```typescript
+// Domain
+export function createUser(repo: UserRepository, email: string) {
+  return repo.insert({ email })
+}
+
+// Composition root
+const repo = new DrizzleUserRepo(db)
+app.post('/users', (c) => createUser(repo, c.req.body.email))
+```
+
+Checklist:
+- Every external dependency has a domain-owned interface.
+- Domain modules do not import databases, filesystems, or transport adapters.
+- Infrastructure is referenced only from composition roots.
+
+## 2. Single Source of Truth
+
+When a variant set can grow, define one typed registry and derive types,
+validation, routing, and display from it. Do not repeat unions or literals in
+consumers.
+
+```typescript
+const ROLE_CONFIG = {
+  admin: { level: 2, canDelete: true },
+  editor: { level: 1, canDelete: false },
+  viewer: { level: 0, canDelete: false },
+} as const satisfies Record<string, RoleConfig>
+
+type Role = keyof typeof ROLE_CONFIG
+const ROLES = Object.keys(ROLE_CONFIG) as Role[]
+```
+
+Checklist:
+- One authoritative constant or schema owns the variants.
+- Downstream types and behavior derive from that registry.
+- Adding a variant changes the registry, not a collection of switches and
+  validators.
+
+## 3. Generated Contracts
+
+Choose one source for each system boundary and derive consumers from it:
+
+- HTTP API: OpenAPI schema to generated client.
+- Typed router: share or infer the router contract.
+- Database: infer application types from the schema.
+- GraphQL: generate types from SDL.
+
+Build generation into the normal pipeline. Consumers import generated or
+inferred types rather than maintaining mirrors. Extend a generated type with
+intersection/composition when needed; do not replace it with a hand copy.
+
+Checklist:
+- Every cross-boundary interface names its source of truth.
+- Generation or inference is part of the build path.
+- No hand-written type mirrors a schema, router, or database definition.
+
+## 4. Fail Fast
+
+Validate unknown input at system boundaries before domain logic runs. Assert
+internal preconditions at function entry with specific guard errors and early
+returns; do not propagate invalid state into deeper call chains.
+
+```typescript
+function processOrder(input: unknown) {
+  const order = OrderSchema.parse(input)
+  return computeTotal(order)
+}
+
+function applyDiscount(order: Order, pct: number) {
+  if (pct < 0 || pct > 1) throw new Error(`Invalid discount: ${pct}`)
+  // ...
+}
+```
+
+Boundary examples include HTTP handlers, CLI arguments, external API responses,
+and configuration files. Internal checks should report the violated
+precondition and received value whenever that is safe.

package/skills/principles/references/models.md

@@ -1,7 +1,7 @@
 # Model Selection & Decision Matrix
 
 > The concrete model-layer companion to the **model-agnostic** dispatch and
-> cross-model policy in `principles/SKILL.md` (Parts IV & VIII) and the
+> cross-model policy in `principles/SKILL.md` Part IV and the
 > "different model class" decision points across the plugin. In-skill prose is
 > deliberately written in capability/role terms; **this file is where those
 > capabilities map to actual models and `peeragent` flags.** Load it whenever a
@@ -9,8 +9,9 @@
 > "use a different model class".
 
 Model generations move fast — the *families and classes* below are the durable
-abstraction; specific version numbers (e.g. Opus 4.x, GPT-5.x-Codex, Gemini 3.5,
-GLM-5.2) are the current resolution of each class as of writing. Always resolve
+abstraction; specific versions and names (for example Claude Fable, GPT-5.6
+Luna/Terra/Sol, GPT-5.x-Codex, Gemini 3.5, and GLM-5.2) are current resolutions
+of each class as of writing. Always resolve
 the concrete model against current sources when the choice is load-bearing.
 
 ## Contents
@@ -51,11 +52,26 @@ the in-skill prose names; this is what they mean.
 ## 2. Model-family cards
 
 **Claude (Anthropic)** — `--agent claude`
-- Tiers: `opus` (deepest reasoning + agentic, 1M context; slowest), `sonnet`
-  (strong coding + speed; 1M beta), `haiku` (fast, near-frontier, cheap).
+- Tiers include `opus`, `sonnet`, `haiku`, and Claude Fable where available.
 - Effort: `high | xhigh` (default `xhigh`).
-- Best roles: `opus` → deep reviewer / adversarial peer / highest-tier worker;
-  `sonnet` → primary worker / scout; `haiku` → leaf tasks, cheap fan-out.
+- Recommendations: Opus for deep review/adversarial work, Sonnet for primary
+  work and scouting, Haiku for cheap leaf fan-out. Fable is a strong but
+  expensive design, orchestration, and review choice; it can implement, but its
+  cost usually makes another capable worker preferable.
+
+**GPT-5.6 (OpenAI; host-native where available)**
+- **Luna** is the recommended implementation workhorse: medium thinking for
+  simple/routine work, scaling through xhigh for fairly complicated work short
+  of the hardest tier.
+- **Terra** remains a situational middle pick. Current practitioner preference
+  often favors Sol at low thinking as the bridge above Luna rather than treating
+  Terra as a mandatory rung.
+- **Sol** is preferred for design, review, and complex/large implementation. Low
+  thinking bridges above Luna; raise thinking for the hardest architecture,
+  review, and coding work.
+- These are recommendations, not fixed capability facts. Discover current host
+  availability before selection. Luna, Terra, Sol, and Codex share OpenAI
+  lineage, so switching among them is not cross-model evidence.
 
 **Codex (OpenAI)** — `--agent codex`
 - Current class: GPT-5.x-Codex (model auto-selected; no `--model` flag).
@@ -83,9 +99,9 @@ the in-skill prose names; this is what they mean.
 
 | Role | Needs (capability) | Primary models |
 |---|---|---|
-| Primary worker | write fidelity, agentic stamina | Sonnet-class / Codex high / GLM-5.2 high |
-| Scanner/scout (deep read-only fan-out) | domain inspection, evidence, scoped artifacts | Haiku / Sonnet medium / Sonnet for volume; Opus/Codex xhigh/GLM xhigh for subtle gates |
-| Deep reviewer | reasoning depth, fresh context | Opus-class xhigh / Codex xhigh / GLM-5.2 xhigh |
+| Primary worker | write fidelity, agentic stamina | GPT-5.6 Luna medium→xhigh / Sonnet-class / Codex high / GLM-5.2 high; Sol for complex/large implementation |
+| Scanner/scout (deep read-only fan-out) | domain inspection, evidence, scoped artifacts | Haiku / Luna or Sonnet for volume; Sol/Opus/Codex xhigh/GLM xhigh for subtle gates |
+| Deep reviewer | reasoning depth, fresh context | GPT-5.6 Sol / Claude Fable or Opus / Codex xhigh / GLM-5.2 xhigh |
 | Advisory peer (Phase 1) | blind-spot diversity, augmentation | a **different class** than the host |
 | Adversarial peer (Phase 2) | blind-spot diversity, attack posture | a **different class** than host + than Phase 1 |
 
@@ -98,67 +114,30 @@ diversity**, and for deep work use **two distinct peer classes** (§5).
 
 | Host class | Valid peer classes (any different class) |
 |---|---|
-| Claude | codex · gemini · zai |
-| Codex | claude (opus) · gemini · zai |
-| Gemini | claude (opus) · codex · zai |
-| Z.AI GLM | claude (opus) · codex · gemini |
+| Claude (including Fable) | openai · gemini · zai |
+| OpenAI (GPT-5.6 or Codex) | claude · gemini · zai |
+| Gemini | claude · openai · zai |
+| Z.AI GLM | claude · openai · gemini |
 
 When the natural pair is unavailable, fall through to the next class; never
-peer with the same class as the host.
+peer within the host lineage and call it cross-model. A same-lineage reviewer
+may still provide fresh context when labeled accurately.
 
 ## 5. Multi-class review for deep/complex work
 
-For **deep or complex work** — architectural design points, large/risky
-features or epics, the final autopilot completion review, whole-repo scans — a
-single peer is the floor, not the ceiling. **If two different model classes are
-available, use both.** Different training lineages have different blind spots;
-two independent peers catch more than one, and their disagreements are
-themselves signal (re-read both before deciding).
-
-Concretely: pair the two peers across the two review phases in §6 — one class
-runs the **advisory** pass, a *different* class runs the **adversarial** pass.
-That realizes the 2-class rule through the phase ordering and maximizes both
-augmentation diversity and adversarial independence. For routine/small work a
-single peer (or none) remains correct — this escalation is for deep/complex
-scope only.
+The risk and `review_weight` policy lives in
+[advisory-review.md](advisory-review.md). At model-selection time, when that
+policy calls for two classes, choose two distinct training lineages that also
+differ from the host where availability permits. Pair one with each phase;
+disagreement is evidence to investigate, not a vote.
 
 ## 6. Two-phase design review: advisory then adversarial
 
-Designs and reviews are both evaluated in a fixed **two-phase order** —
-**completeness/complementary/advisory first, adversarial second.** Never reverse
-the phases and never skip Phase 1 to jump straight to attack: a design or review
-reviewed only adversarially gets torn apart before anyone checks whether it is
-complete. The two phases have **different loop shapes depending on whether the
-artifact is a design (open) or a review (complete)**:
-
-**Phase 1 — Completeness / Complementary / Advisory.** Augmentation, not
-judgment. Ask what is missing, what alternatives strengthen it, and what
-questions/risks should be weighed.
-- *Design (open artifact, before decisions lock)*: **a single pass.** You don't
-  iterate an open design to convergence. The host chooses and records rationale.
-  This is the default autopilot design-time peer ask.
-- *Review (complete artifact — feature/epic/out-of-band review)*: **a multi-step
-  convergence loop**, not a single ask — the artifact is complete, so iterate
-  until findings stabilize. The ideal is the full `peer-review` convergence loop
-  (≥3 review→refine passes, continue while substantive issues surface, stop on
-  nits, cap ~5); run that loop in the advisory/complementary posture when
-  `peer-review` is available. When only a single peer pass is available, run as
-  many rounds as the mechanism allows and say it did not reach full convergence.
-
-**Phase 2 — Adversarial (after Phase 1 converges or, for designs, completes).**
-Attack posture. Ask a **different** reviewer (ideally a different class than
-Phase 1, per the 2-class rule in §5) what is broken, contradictory, built on a
-false assumption, or will fail in operation. For reviews this is the same
-`peer-review`-style convergence loop applied in the attack posture; for designs
-it is a focused adversarial pass. Verify concrete claims against code/foundation
-docs before accepting or rejecting.
-
-Record both phases in the item body under `## Other agent review`, labeling each
-finding's phase, the reviewer class, and (for reviews) how far the convergence
-loop ran (converged on nits / hit cap / single pass only). Peer failures in
-either phase are non-blocking (fall back to a fresh same-class sub-agent); the
-final autopilot completion review must still clear through at least one
-cross-class pass.
+The phase order, artifact-specific loop shapes, ceilings, and recording format
+live in [advisory-review.md](advisory-review.md). This model-layer reference adds
+one constraint: when two classes are selected, Phase 2 should differ from both
+the host and Phase 1 where the available class set permits it. Never label an
+unknown or same-class reviewer cross-model.
 
 ## 7. peeragent invocation cheatsheet
 

package/skills/prose-author/SKILL.md

@@ -160,10 +160,15 @@ fan-out. Do not route prose features to `/agile-workflow:implement-orchestrator`
 (agent-spawning + worktrees) just because they exceed a line count; the
 orchestrator's value is parallel coordination, which prose work does not need.
 
-For a large deliverable, the inline `implement` is the **write** stride and
-`review` is a genuine **revise/coherence** pass — not a rubber stamp. For the
-common small case, implement is the one stride that finishes the work and review
-is light.
+For a large deliverable, inline `implement` is the **write** stride and the
+review lane is a genuine **revise/coherence** pass — never a rubber stamp. For a
+small deliverable, the same review may be light, but it still evaluates the work.
+In both cases, `/agile-workflow:implement` continues through that review lane to
+`done` by default in one invocation, forwarding the effective review weight, or
+returns with a documented bounce or blocker. Even when policy skips independent
+review, closure still requires green verification and acceptance evidence. The
+lane stops at `review` only when the caller explicitly requests `stop-at-review`
+(or the project convention sets that boundary).
 
 ## Output
 

package/skills/refactor-design/SKILL.md

@@ -143,14 +143,13 @@ drafting features. Iterate over the target set:
 3. Read-first map of the feature's area; use one exploratory sub-agent only if the
    area is still unclear. Include `.agents/skills/refactor-conventions/` as
    context when present.
-4. Surface strategic ambiguities specific to the refactor (e.g., "preserve API
-   shape or break consumers?", "in-place or shadow-then-swap?", "rollback
-   strategy when atomic?"). Use structured question tool.
+4. Use the structured question tool for refactor-specific strategic ambiguities
+   such as API compatibility, migration shape, or rollback strategy.
 5. Capture answers under `## Design decisions` in the feature body
 6. Do NOT design or advance stage — let the design family pick up later
 7. Commit per feature: `refactor-design --only-questions: <id>`
 
-Requires interactive mode; refuse to run under an active autopilot run or goal.
+Requires interactive mode; refuse under autopilot. Otherwise defer question and advisory policy to `principles/SKILL.md` Parts III–IV.
 
 ## Workflow — per-feature mode
 

package/skills/review/SKILL.md

@@ -44,45 +44,82 @@ Load only the reference needed for the selected lane:
 | `review --all` | Drain every item at `stage: review`. |
 | `review <NL filter>` | Drain a filtered subset of the review queue. Interpret the filter against item bodies, tags, and parent chains. |
 | `review <branch/commit/range/PR/wip>` | Out-of-band review. Review the target diff and print a verdict. |
-| `deep review <target>` / `review --deep <target>` | Use deep mode for a substrate item or out-of-band target. |
+| `review --review-weight <level> <target>` | Set independent-review effort: `none`, `light`, `standard`, `thorough`, or `maximum`. An explicit selector wins over caller notes and project configuration. |
+| `deep review <target>` / `review --deep <target>` | Request deep risk coverage; reviewer topology still respects the effective review weight. |
 
 In batch modes (`--all` / NL filter), loop through the matched set and output a
 single consolidated summary at the end: verdicts per item plus total finding
 counts.
 
-## Review Lanes
+## Review Weight And Lanes
 
-Review cost should match what the target can actually surface. Resolve mode
-first, then pick the lane:
+Resolve one effective `review_weight` before choosing a lane. The valid scale is
+`none | light | standard | thorough | maximum`; reject unknown values at the
+boundary. Precedence is:
 
-| Target | Lane | What runs |
+1. explicit `--review-weight <level>` or an unambiguous natural-language caller selector
+2. an autopilot/production-skill caller note carrying the effective level
+3. `review_weight` in `.work/CONVENTIONS.md`
+4. `standard`
+
+The weight is an effort budget, not a verdict and not a fixed orchestration
+recipe. Risk, evidence, and item tier determine how to spend it; current models
+choose the exact topology within the stated ceiling/intent. Record the effective
+weight, its source, selected lane, and decisive risk/evidence signals in Review
+Notes.
+
+| Weight | High-level review intent |
+|---|---|
+| `none` | No independent reviewer. Perform an administrative review of the target's own green verification and acceptance evidence; close only when both are sufficient. |
+| `light` | Stories remain verification-only. Larger items receive at most one focused fresh-context pass. |
+| `standard` | Balanced risk-based default: fast low-risk stories, focused Standard work out of band, and fresh-context Deep review for features, epics, and escalated stories. |
+| `thorough` | Increase independent coverage with additional fresh-context passes or reviewers where the risk surface benefits; keep complementary before adversarial. |
+| `maximum` | For features/epics, use multi-model, multi-pass complementary → adversarial review when those capabilities exist. Dynamically escalate stories according to risk rather than reviewing every story identically. |
+
+Lane selection is `weight + risk + evidence + kind-as-heuristic`. Resolve mode
+first, gather enough context to identify risk, then choose:
+
+| Starting point | Default lane | Evidence or risk adjustment |
 |---|---|---|
-| **story item** | **Fast** | Confirm the green implementation verification already recorded by `implement`, then advance and roll up. No lens walk, no diff re-analysis, no peer. |
-| **out-of-band target** | **Standard** | Review the diff in the current context using the core lenses. Print a structured verdict. No substrate writes, no stage changes, no commit. |
-| **feature / epic item** | **Deep** | Full lens review using fresh-context evaluation when available. |
-| **explicit `--deep` target** | **Deep** | Use the deep lens set even for an out-of-band target. For a story item, keep the fast lane unless the caller explicitly asked for `--deep`. |
+| **story item** | **Fast** | Keep Fast only with recorded green verification and no escalation signal. Escalate to Deep for a caller-interface change, security or correctness surface, cross-cutting scope, a touched foundation-doc claim, or explicit `--deep`. |
+| **out-of-band target** | **Standard** | Use Deep only when explicitly requested; otherwise calibrate the Standard lens walk to the observed risk. |
+| **feature / epic item** | **Deep** | Kind signals aggregate contract risk; green child evidence informs the review but does not replace the parent's own review. |
+| **explicit `--deep` target** | **Deep** | Request the strongest depth the effective weight permits; depth overrides the kind heuristic, not an explicit weight ceiling. |
+
+Risk is not inferred from size alone. A tiny authentication or public-contract
+change can require Deep; a broad mechanical change can remain Standard when its
+evidence and contracts make that safe. `none` is the explicit exception to
+independent fresh-context review: it still performs the item's own acceptance
+check and records a verdict, so it never turns child completion into automatic
+parent approval.
 
 ### Fast Lane
 
-Stories use the fast lane by default:
+A genuinely low-risk story uses the fast lane; `none` also uses this
+administrative shape for every tier:
 
-1. Read the story body.
+1. Read the item body, recorded implementation scope, and acceptance criteria.
 2. Confirm an implementation/verification record exists and reports green build
-   and tests.
-3. If verification is present and green, load
+   and tests (or an explicit reason the change needs no executable checks).
+3. Confirm the recorded evidence addresses the item's acceptance criteria.
+4. Check explicitly for the escalation signals above. At `standard` or higher,
+   switch a risky story to Deep before issuing a verdict. At `none` or `light`,
+   stay within the selected effort ceiling and record the unexamined risk.
+5. If verification and acceptance evidence are green, load
    [substrate-side-effects.md](references/substrate-side-effects.md) and advance
-   `review -> done` with a one-line record:
-   `Verdict: Approve - story verified by implement; fast-lane advance`.
-4. If verification is absent or failing, either run cheap verification yourself
-   or bounce `review -> implementing` with a `## Review findings` note.
+   `review -> done` with a one-line record naming the weight and evidence.
+6. If evidence is absent or failing, run only cheap verification that fits the
+   selected weight or bounce `review -> implementing` with a
+   `## Review findings` note.
 
-Skip the lens walk for fast-lane stories. Do not deep-review a story unless the
-caller explicitly requested `--deep`.
+Skip the lens walk only when evidence and the effective weight permit it. Kind
+alone never grants an advance, and `none` never means "done because children
+are done."
 
 ### Standard Lane
 
-Standalone reviews use the standard lane. Load
-[target-resolution.md](references/target-resolution.md) and
+Standalone reviews use the standard lane unless the caller explicitly requests
+Deep. Load [target-resolution.md](references/target-resolution.md) and
 [review-lenses.md](references/review-lenses.md), read enough surrounding code to
 understand the change, then print the structured review. Do not create `.work`
 items, advance stages, archive files, or commit metadata unless the user
@@ -90,37 +127,48 @@ explicitly converts the findings into substrate work.
 
 ### Deep Lane
 
-Feature, epic, and explicit deep reviews use the deep lane. Load
+Feature, epic, escalated-story, and explicit deep reviews use the deep lane when
+the effective weight permits independent review. Load
 [deep-review.md](references/deep-review.md) plus any target or lens reference it
-points to. Prefer fresh-context evaluation when available; if no fresh reviewer
-is reachable, do a degraded inline deep review and record that limitation in
-Notes rather than skipping the review. Deep reviews follow the two-phase order
-— **completeness/complementary, then adversarial** — and because a review target
-is a complete artifact, each phase is a **convergence loop to nits**, not a
-single pass (the ideal is the full `peer-review` loop when available). For a
-feature/epic (deep or complex scope) use **two different model classes** when
-available, one per phase (see
-[../principles/references/models.md](../principles/references/models.md) §6 for
-the design-vs-review loop distinction).
+points to. The evaluation must run in fresh context: use a different-class peer
+when reachable; otherwise use the strongest same-harness fresh-context
+sub-agent prompted with the reviewer posture. If the selected weight calls for
+fresh review and neither is available, record the limitation and block rather
+than approving from the host context. Deep reviews never become inline
+self-review; this requirement overrides any older inline-fallback wording in a
+lane reference.
+
+Calibrate depth from the weight table instead of treating Deep as one fixed
+recipe. `light` caps a larger item's review at one fresh pass; `standard`
+balances coverage against observed risk; `thorough` adds complementary and
+adversarial coverage where useful; `maximum` seeks multi-model, multi-pass
+complementary → adversarial convergence for features/epics and dynamically
+escalates risky stories. These are ceilings and intent, not mandatory agent
+counts. Preserve complementary-before-adversarial order whenever both run (see
+[../principles/references/models.md](../principles/references/models.md) §6).
 
 ## Workflow
 
-### Phase 0: Resolve Mode And Depth
+### Phase 0: Resolve Mode, Weight, And Depth
 
 Default to substrate mode when the target looks like a work item id, when any
 item is at `stage: review`, or when autopilot delegated the review. Use
 standalone mode when the user names a branch, commit, commit range, PR number,
 `wip`, working tree, or otherwise asks for an out-of-band code review.
 
+Resolve and validate effective `review_weight` using the precedence above before
+any mutation. Explicit caller selection always wins.
+
 If both interpretations are plausible, prefer substrate mode but ask the user
 before mutating `.work`. If the caller is autopilot or a harness goal, do not
 ask: choose substrate mode and the next review item.
 
-Depth:
-- **Fast**: story item with green implementation verification.
-- **Standard**: out-of-band target or explicitly lightweight review.
-- **Deep**: feature/epic item, explicit `--deep`, or a review where the user asks
-  for robustness across design, contracts, release, and operational dimensions.
+Depth after applying the weight ceiling:
+- **Fast/administrative**: low-risk story with green evidence, any story at
+  `light`, or any tier at `none`.
+- **Standard**: out-of-band target unless explicitly deep.
+- **Deep**: feature/epic item, risk-escalated story, explicit `--deep`, or a
+  robustness request when the weight permits fresh-context evaluation.
 
 ### Phase 1: Identify The Target
 
@@ -139,8 +187,10 @@ Standalone mode:
 
 Substrate mode:
 - Read the item file.
-- Internalize the brief, design, implementation notes, and verification evidence.
-- For a feature, also read each child story body.
+- Internalize the brief, design, implementation notes, acceptance criteria, and
+  verification evidence.
+- For a feature or epic, read direct child bodies and their review evidence;
+  children inform but never replace the parent's own review.
 
 Standalone mode:
 - Read the user's stated target.
@@ -156,8 +206,11 @@ All modes:
 
 ### Phase 3: Determine The Change Scope
 
-Load [target-resolution.md](references/target-resolution.md). Use it to gather
-the diff, PR metadata, commit messages, or epic aggregate scope.
+For Standard and Deep lanes, load
+[target-resolution.md](references/target-resolution.md). Use it to gather the
+diff, PR metadata, commit messages, or epic aggregate scope. Fast uses the
+recorded implementation scope and verification instead of re-analyzing the
+diff.
 
 If the non-epic diff is empty:
 - Autopilot substrate mode: advance only if the item has complete green
@@ -176,8 +229,9 @@ Standard lane:
 
 Deep lane:
 - Load [deep-review.md](references/deep-review.md).
-- Use fresh-context evaluation when available.
-- Apply the core lenses plus the deep dimensions.
+- Run the evaluation in fresh context at the effective weight; do not approve
+  inline when the selected weight requires a fresh reviewer and none is available.
+- Apply the core lenses plus the applicable deep dimensions.
 
 ### Phase 5: Classify Findings
 
@@ -207,8 +261,35 @@ Substrate mode:
 - Load [substrate-side-effects.md](references/substrate-side-effects.md).
 - File above-nit findings into the substrate.
 - Advance the item if there are no blockers, or bounce it if blockers exist.
-- Append the review record.
-- Commit the substrate changes.
+- Append the review record and commit the reviewed item's transition.
+- After an approval reaches `done`, run Conservative Parent Roll-Up below.
+
+### Conservative Parent Roll-Up
+
+A child's approval is evidence that an ancestor may be ready for review; it is
+never approval of the ancestor itself. After advancing any item to `done`:
+
+1. Find its immediate parent. If there is none, stop.
+2. Count all direct children across active and terminal tiers. If any child is
+   non-terminal, stop the entire roll-up at this ancestor.
+3. If the parent is `implementing`, advance it to `review`, append a `Children
+   complete` note, and commit that transition. If it is already `review`, leave
+   the stage unchanged. Never change an implementing/review parent directly to
+   `done` just because its children are done.
+4. Run this skill on the parent using the normal weight/risk/evidence lane
+   selection. Features and epics therefore receive their own Deep review when
+   independent review is enabled, or their own administrative acceptance review
+   at `none`.
+5. Only an Approve or Approve-with-comments verdict may advance the parent to
+   `done`; commit that review transition. A bounce or block stops roll-up.
+6. Once the parent is approved and `done`, repeat from step 1 for its parent.
+
+This recursion can complete story → feature → epic in one review invocation,
+but every ancestor crosses its own real `review` stage and receives its own
+selected review lane at the same effective weight. Preserve active parent bodies
+while walking the chain; terminal retention/archive handling applies only where
+the substrate-side-effects contract says the item is no longer needed for an
+active parent.
 
 ## Output
 
@@ -240,6 +321,8 @@ Approve | Approve with comments | Request changes | Block
 
 If no findings above nit level in substrate mode: "This change looks good.
 Nothing blocking or significant to flag. Item advanced to `stage: done`."
+Also report each ancestor moved to `review`, approved to `done`, bounced, or
+left waiting on a non-terminal child.
 
 If no findings above nit level in standalone mode: "This change looks good.
 Nothing blocking or significant to flag."
@@ -265,3 +348,6 @@ Nothing blocking or significant to flag."
   rule.
 - Do not advance an item past review unless the verdict is Approve or Approve
   with comments. Pushing through blockers defeats the point of the stage.
+- Child completion never substitutes for a parent's review. Roll-up may move an
+  implementing parent to `review`, but only that parent's selected lane may move
+  it to `done`.

package/work-view/crates/cli/.work-view-version

@@ -1 +1 @@
-0.15.3
+0.16.1