@nklisch/pi-agile-workflow 0.15.3 → 0.16.3

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,22 +229,36 @@ 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.
-
-### Phase 5: Classify Findings
-
-- **Blocker**: must be fixed before advancing or merging. Examples:
-  correctness bug, security vulnerability, undocumented breaking change,
-  foundation-doc drift, or a test that proves the change is wrong.
-- **Important**: should be addressed but is not strictly blocking. Examples:
-  missing tests for meaningful logic, questionable design, unclear naming, minor
-  security gap, or refactor opportunity.
-- **Nit**: optional improvement, style polish, small documentation improvement,
-  or nonessential refactor.
-
-If there are zero blockers and zero important findings, say so plainly. Do not
-pad the review with invented concerns.
+- 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: Adjudicate And Classify Findings
+
+The host/receiving agent owns classification. Treat fresh-reviewer severities as
+proposals, verify concrete claims, and weigh each finding against repository
+context: acceptance criteria, supported deployment and users, likelihood, blast
+radius, recoverability, existing safeguards, and delay cost. Reviewer confidence,
+model strength, or repeated mention does not make a finding blocking.
+
+- **Blocker**: a credible, material current-cycle risk to required correctness,
+  security, data integrity, public contracts, acceptance criteria, release
+  safety, or trustworthy verification. It must be fixed or kept active before
+  advancing. Examples include a demonstrated correctness bug, exploitable
+  vulnerability, unintended breaking change, material foundation-doc drift, or
+  a test that proves required behavior is wrong.
+- **Important**: valid work below the current-cycle blocker bar. Park it in the
+  unbound backlog with the risk rationale and advance the reviewed item. Examples
+  include unlikely low-consequence edges, worthwhile hardening, nonessential
+  tests, design cleanup, naming, or refactor opportunities.
+- **Nit**: optional polish that does not warrant a substrate item.
+- **Rejected**: unsupported, inapplicable, or cost-disproportionate advice;
+  record a brief reason when it came from an independent reviewer.
+
+Rarity alone is not dismissal: a corner case with severe consequences may still
+block. Conversely, a real issue does not block merely because a reviewer found
+it. If there are zero receiver-confirmed blockers and zero important findings,
+say so plainly. Do not pad the review with invented concerns.
 
 ### Phase 6: Finish
 
@@ -205,10 +272,39 @@ Standalone mode:
 
 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.
+- File receiver-accepted findings according to their disposition: current-cycle
+  blockers active, important findings in the unbound backlog, and nits nowhere.
+- Advance the item if there are no receiver-confirmed blockers, or bounce it if
+  blockers exist.
+- 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
 
@@ -234,12 +330,17 @@ Approve | Approve with comments | Request changes | Block
 ### Nits
 - Nit: <brief note> (`file:line`)
 
+### Rejected proposals
+- <reviewer proposal>: <repository-context rationale>
+
 ## Notes
-<mode, depth, skipped lenses, limitations, or anything else worth recording>
+<mode, depth, risk context, skipped lenses, limitations, or anything else worth recording>
 ```
 
 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."
@@ -264,4 +365,8 @@ Nothing blocking or significant to flag."
 - Foundation-doc drift is a blocker, not a nit. Rolling foundation is a hard
   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.
+  with comments. Pushing through receiver-confirmed material blockers defeats
+  the point of the stage; parking lower-risk findings does not.
+- 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/skills/review/references/substrate-side-effects.md

@@ -8,15 +8,21 @@ commit unless the user explicitly asks for that side effect.
 
 ## Triage Findings Into Items
 
-For each finding above nit level, create a substrate item so it does not
-disappear into prose:
-
-- **Blocker**: either fix inline if small, or create a story in
-  `.work/active/stories/` with `stage: implementing` and tags such as `[bug]`,
-  `[security]`, `[tests]`, or the appropriate category.
-- **Important**: park as a backlog item in `.work/backlog/`, or scope as a
-  feature if substantial.
-- **Nit**: keep in conversation only; nits do not warrant items.
+The receiving agent first adjudicates reviewer proposals under
+`principles/SKILL.md` Part IV. Reviewer severity labels are not authoritative.
+For each accepted finding above nit level, preserve the chosen disposition so it
+does not disappear into prose:
+
+- **Blocker**: a receiver-confirmed material current-cycle risk. Either fix
+  inline if small, or create a story in `.work/active/stories/` with
+  `stage: implementing` and tags such as `[bug]`, `[security]`, `[tests]`, or the
+  appropriate category. It prevents the reviewed item from advancing.
+- **Important**: valid work below the blocker bar. Park it as an unbound backlog
+  item in `.work/backlog/` with the contextual risk rationale; do not scope it
+  active merely because it is substantial or a reviewer called it blocking.
+- **Nit**: keep in review notes only; nits do not warrant items.
+- **Rejected**: create no item; record a brief reason in the review record when
+  independent review proposed it.
 
 Review-created items use `gate_origin: null`; gate-produced findings set
 `gate_origin`.
@@ -140,8 +146,9 @@ Append this section to the reviewed item:
 **Blockers**: <list with item ids> (or "none")
 **Important**: <list with item ids> (or "none")
 **Nits**: <inline notes - not items>
+**Rejected**: <reviewer proposals and brief reasons> (or "none")
 
-**Notes**: <mode, depth, skipped lenses, limitations, or anything else worth recording>
+**Notes**: <mode, depth, risk context, skipped lenses, limitations, or anything else worth recording>
 ```
 
 ## Commit

package/skills/scope/SKILL.md

@@ -170,18 +170,21 @@ second confirmation round.
 
 ### Phase B8: Promote each confirmed cluster
 
-For each cluster, run the single-idea-mode Phases 3-6 inline:
+For each cluster, run the single-idea-mode Phase 1.9 and Phases 3-6 inline:
 
-1. **Declare dependencies** — within-cluster (child stories under a feature)
+1. **Frame simplification opportunities** — record what the cluster can delete,
+   consolidate, replace, or make unnecessary; separate cohesive cleanup from
+   unrelated backlog work.
+2. **Declare dependencies** — within-cluster (child stories under a feature)
    and cross-cluster (one feature depends on another's output). Use
    `work-view --blocking` for cycle detection.
-2. **Foundation-doc roll-forward** (large clusters only) — full Phase 4 of
+3. **Foundation-doc roll-forward** (large clusters only) — full Phase 4 of
    single-idea mode, scoped to that cluster's impact.
-3. **Write item files** — the parent (epic or feature) plus any child files.
+4. **Write item files** — the parent (epic or feature) plus any child files.
    Use `git mv` to move backlog files into the new structure where they map
    1:1; reference the backlog idea in the parent's brief and `git rm` the
    backlog file where it was absorbed without a direct child.
-4. **Commit per cluster** — `scope: <cluster-id> (<kind>, <size>)` with a
+5. **Commit per cluster** — `scope: <cluster-id> (<kind>, <size>)` with a
    foundation-doc roll-forward note where applicable.
 
 Promote leftovers per the Phase B7 decision (one commit per promoted leftover,
@@ -267,7 +270,7 @@ interfaces).
 Aim for 2-5 questions. Zero is fine if the user's brief and foundation docs
 already pin every strategic choice. For small (story) and medium (feature)
 scope, the bar is higher — only ask if a strategic ambiguity genuinely
-affects framing; otherwise skip directly to Phase 2.
+affects framing; otherwise continue through Phases 1.8 and 1.9 without questions.
 
 Use `structured question tool` to ask. Capture answers in the item body under a
 `## Strategic decisions` section so the downstream design family inherits
@@ -306,7 +309,14 @@ journey before the item is written.
 
 Skip this phase if `ux-ui-design` is not installed.
 
-Then proceed to Phase 2.
+Then proceed to Phase 1.9.
+
+### Phase 1.9: Frame simplification opportunities
+
+Record what the idea could delete, consolidate, replace, or make unnecessary—code,
+tests, checks, abstractions, compatibility paths, configuration, or whole subsystems.
+Fold cohesive cleanup into the brief, note independent `[refactor]`/`[cleanup]`
+children, and park unrelated work. Removing guarantees requires a strategic decision.
 
 ### Phase 2: Size the scope
 
@@ -414,6 +424,9 @@ updated: YYYY-MM-DD
 ## Brief
 <one to three paragraphs describing what this is and why it exists>
 
+## Simplification opportunity
+<what this work may delete, consolidate, replace, or deliberately retain; "none identified" is valid>
+
 <!-- Subsequent sections (Design, Implementation Notes, etc.) accumulate as
 work progresses. -->
 ```

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

@@ -1 +1 @@
-0.15.3
+0.16.3