@nklisch/pi-agile-workflow 0.16.1 → 0.16.4

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

@@ -9,7 +9,10 @@ concrete boundary guidance, checklists, or examples.
 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)
+4. [Fail Fast—Where It Matters](#4-fail-fastwhere-it-matters)
+5. [Code Economy](#5-code-economy)
+6. [Tests Earn Their Keep](#6-tests-earn-their-keep)
+7. [Leave It Simpler](#7-leave-it-simpler)
 
 ## 1. Ports & Adapters
 
@@ -84,11 +87,13 @@ Checklist:
 - Generation or inference is part of the build path.
 - No hand-written type mirrors a schema, router, or database definition.
 
-## 4. Fail Fast
+## 4. Fail Fast—Where It Matters
 
-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.
+Validate untrusted input and required external contracts at system boundaries
+before domain logic runs. Add internal guards when a violated precondition is
+plausible and consequential; do not turn every helper into a defensive boundary.
+The project decides how much invariant enforcement, edge handling, and
+determinism it actually needs.
 
 ```typescript
 function processOrder(input: unknown) {
@@ -105,3 +110,55 @@ function applyDiscount(order: Order, pct: number) {
 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.
+
+Checklist:
+- Validate real trust boundaries and explicit contracts.
+- Match defensive rigor to failure consequences and project scope.
+- Do not add checks, retries, invariants, or determinism only because a more
+  general system might need them.
+
+## 5. Code Economy
+
+Prefer the shortest clear expression of the project's actual requirements.
+Every abstraction, option, layer, fallback, and branch creates maintenance cost;
+it must earn that cost in current scope rather than a hypothetical future.
+Terse does not mean cryptic: optimize for fewer concepts, then fewer lines.
+
+Checklist:
+- Choose the direct solution before a configurable framework.
+- Avoid extension points without a current second use or committed need.
+- Delete incidental machinery made obsolete by the change.
+
+## 6. Tests Earn Their Keep
+
+Automated tests are maintained code. Prioritize stable public interfaces,
+important cross-component seams, high-consequence behavior, and regression tests
+for real bugs. Unit tests belong around genuinely complex logic where isolated
+examples add confidence; simple wrappers and implementation details usually do
+not need their own tests.
+
+Checklist:
+- Name the interface, risk, or regression each test protects.
+- Prefer a useful interface test over several implementation-bound unit tests.
+- Do not chase line coverage or enumerate every possible surface by default.
+- Remove duplicate, tautological, brittle, or low-value tests when they no
+  longer justify upkeep.
+
+## 7. Leave It Simpler
+
+Treat elimination as part of feature work, not a separate activity reserved for
+refactors. During exploration and design, identify code, tests, checks,
+abstractions, compatibility paths, and configuration that the proposed feature
+can make unnecessary. During implementation, perform safe cohesive cleanup in
+the touched area and create explicit cleanup/refactor stories for larger work.
+
+Question whole systems as well as local fragments. Removing behavior,
+guarantees, validation, determinism, compatibility, or safety is a product
+choice: explain the trade-off and ask the user rather than silently weakening
+it.
+
+Checklist:
+- Record what the feature can delete or consolidate.
+- Prefer deletion and inlining before extraction or another abstraction.
+- Leave touched code simpler unless doing so would blur scope or alter behavior.
+- Park broader opportunities; ask before reducing meaningful guarantees.

package/skills/principles/references/models.md

@@ -9,8 +9,8 @@
 > "use a different model class".
 
 Model generations move fast — the *families and classes* below are the durable
-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
+abstraction; specific versions and names (for example Claude Fable 5, GPT-5.6
+Luna/Terra/Sol, 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.
 
@@ -19,11 +19,12 @@ the concrete model against current sources when the choice is load-bearing.
 1. [Capability axes (the decision vocabulary)](#1-capability-axes-the-decision-vocabulary)
 2. [Model-family cards](#2-model-family-cards)
 3. [Role → capability → model](#3-role--capability--model)
-4. [Host → cross-class peer pairing](#4-host--cross-class-peer-pairing)
-5. [Multi-class review for deep/complex work](#5-multi-class-review-for-deepcomplex-work)
-6. [Two-phase design review: advisory then adversarial](#6-two-phase-design-review-advisory-then-adversarial)
-7. [peeragent invocation cheatsheet](#7-peeragent-invocation-cheatsheet)
-8. [Fallbacks when no peer is reachable](#8-fallbacks-when-no-peer-is-reachable)
+4. [Conditional prompt tuning](#4-conditional-prompt-tuning)
+5. [Host → cross-class peer pairing](#5-host--cross-class-peer-pairing)
+6. [Multi-class review for deep/complex work](#6-multi-class-review-for-deepcomplex-work)
+7. [Two-phase design review: advisory then adversarial](#7-two-phase-design-review-advisory-then-adversarial)
+8. [peeragent invocation cheatsheet](#8-peeragent-invocation-cheatsheet)
+9. [Fallbacks when no peer is reachable](#9-fallbacks-when-no-peer-is-reachable)
 
 ---
 
@@ -36,49 +37,47 @@ the in-skill prose names; this is what they mean.
   entire value of a cross-model peer is independent blind spots, *not* a more
   authoritative answer. Two models that share training add little over one.
 - **Reasoning depth** — multi-step deduction, proof-like correctness, holding a
-  large logical structure. Raised by high/xhigh effort tiers; strongest in
-  Opus-class, GPT-5.x-Codex at xhigh, GLM-5.2 at xhigh.
+  large logical structure. Raised by high/xhigh effort tiers; high-capability
+  choices include Fable 5, Opus 4.8, GPT-5.6 Sol, and GLM-5.2.
 - **Long-horizon agentic stamina** — sustained self-correcting multi-step tool
-  use over many turns / long autonomous runs. Strongest in Codex, GLM-5.2
-  (built for up-to-8h agentic runs), and Opus-class.
-- **Context window** — how much the model can hold at once. GLM-5.2 (1M),
-  Opus-class (1M), Gemini 3.5 (2M, Deep Think), Sonnet-class (1M beta).
-- **Latency budget** — wall-clock cost. Top-tier reasoning peers (Opus-class,
-  xhigh Codex/GLM) commonly take **10–30 minutes** for large reviews and may be
-  quiet for most of it. Budget for it; do not treat a long quiet period as a hang.
+  use over many turns / long autonomous runs. Fable 5, Opus 4.8, GPT-5.6 Sol,
+  and GLM-5.2 are credible choices, but none makes weak approval or verification
+  boundaries safe.
+- **Context window** — how much the model can hold at once. GLM-5.2 (1M maximum;
+  stable full-window fidelity remains under-tested independently), Fable 5 / Opus
+  4.8 / Sonnet 5 (1M), Gemini 3.5 (2M, Deep Think).
+- **Latency budget** — wall-clock cost. Top-tier reasoning peers (Fable 5,
+  Opus 4.8, Sol, and xhigh GLM) commonly take **10–30 minutes** for large reviews
+  and may be quiet for most of it. Budget for it; do not treat a long quiet
+  period as a hang.
 - **Write fidelity** — code-writing accuracy and instruction-following for
   production edits. The property that earns a model a *worker* role.
 
 ## 2. Model-family cards
 
 **Claude (Anthropic)** — `--agent claude`
-- Tiers include `opus`, `sonnet`, `haiku`, and Claude Fable where available.
-- Effort: `high | xhigh` (default `xhigh`).
-- 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.
+- Current upper tiers are Fable 5, Opus 4.8, and Sonnet 5; Haiku remains the
+  cheap leaf-fan-out tier. Effort: `high | xhigh` (wrapper default `xhigh`).
+- Sonnet 5 high is the capable high-throughput worker/scout; use xhigh for its
+  hardest coding. Opus 4.8 xhigh is the stable premium default for complex
+  coding, debugging, and deep review. Fable 5 high/xhigh is the expensive
+  escalation for the hardest ambiguous, long-running, orchestration, design,
+  and review work—not the routine implementer. Prefer Opus for security-adjacent
+  work where Fable's safety classifier/fallback could interrupt the run.
 
 **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).
-- Effort: `medium | high | xhigh` (default `high`).
-- Strengths: top-tier long-horizon agentic coding, multi-step tool use.
-- Best roles: cross-class peer from a Claude/Gemini/GLM host; highest-tier
-  worker for long agentic write paths.
+- **Luna** is the cost-efficient routine implementation and fan-out workhorse:
+  start at medium, then raise effort for bounded work that still benefits from
+  the cheaper tier. Do not make it the default for every implementation task.
+- **Terra** remains a situational middle pick for moderate work and bounded
+  context reading. Luna at more effort or Sol at less effort often gives a
+  better cost/capability point, so Terra is not a mandatory rung.
+- **Sol** is the quality-first general coding default at medium/high and the
+  preferred model for design, review, and complex/large implementation at
+  higher effort. Reserve max-like modes for measured quality gains behind tight
+  action boundaries; documented over-persistence grows at the highest efforts.
+- Discover current host availability before selection. Luna, Terra, Sol, and
+  Codex share OpenAI lineage, so switching among them is not cross-model evidence.
 
 **Gemini (Google)** — `--agent gemini`
 - Model: `gemini-3.5` (2M context, Deep Think mode).
@@ -86,31 +85,44 @@ the in-skill prose names; this is what they mean.
 - Best roles: cross-class peer; large-context review where 2M context matters.
 
 **Z.AI GLM 5.2** — `--agent zai`
-- Model: `glm-5.2` only (MoE 744B / 40B-active; stable 1M context; DeepSeek
-  Sparse Attention; built for long-horizon agentic engineering, ~8h runs).
-- Effort: `medium | high | xhigh` (default `high`).
-- Best roles: cross-class peer (distinct training lineage → distinct blind
-  spots); long-horizon agentic worker; highest-tier reviewer at `xhigh`.
-- Note: the peeragent `zai` adapter runs GLM 5.2 **through Pi**, and needs a
-  current peeragent build (`zai` agent). Older cached builds only list
+- Model: `glm-5.2` only (MoE 744B / 40B-active; 1M maximum context; DeepSeek
+  Sparse Attention). Effort: `medium | high | xhigh` (wrapper default `high`).
+- Best roles: cross-class peer; cost-efficient localized implementation and
+  parallel inspection; high-tier reviewer when the relevant behavior is named.
+  Independent evidence is strong but variable: use a second pass or stronger
+  model when correctness depends on product rules distributed across files.
+- The peeragent `zai` adapter runs GLM 5.2 **through Pi** and needs a current
+  peeragent build (`zai` agent). Older cached builds only list
   `codex|claude|gemini`.
 
 ## 3. Role → capability → model
 
 | Role | Needs (capability) | Primary models |
 |---|---|---|
-| 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 |
+| Primary worker | write fidelity, agentic stamina | Luna medium→xhigh for routine/high-volume work; Sonnet 5 high or Sol medium/high for substantial work; Opus 4.8 xhigh / Fable 5 high→xhigh / GLM-5.2 high when complexity or horizon earns it |
+| Scanner/scout (deep read-only fan-out) | domain inspection, evidence, scoped artifacts | Haiku / Luna / Sonnet 5 for volume; Sol / Opus 4.8 / Fable 5 / GLM xhigh for subtle gates |
+| Deep reviewer | reasoning depth, fresh context | GPT-5.6 Sol / Claude Opus 4.8 or Fable 5 / GLM-5.2 xhigh, with a second pass for distributed invariants |
 | 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 |
 
-## 4. Host → cross-class peer pairing
+## 4. Conditional prompt tuning
+
+Apply these only when the task shape or an observed trace warrants them; effort
+and a clear success criterion usually beat permanent model-specific boilerplate.
+
+| Model / symptom | Small adjustment |
+|---|---|
+| GPT-5.6 prompt bloat or scope drift | State outcome, success criteria, constraints, approval boundaries, and stop rules once; expose only relevant tools. Avoid generic persistence language. Require tool/diff/test evidence before claiming completion. |
+| Opus 4.8 / Sonnet 5 literalism or low review recall | State the rule's full scope explicitly. For review, ask for coverage first and rank/filter findings afterward. Raise effort before adding process prose; add tool triggers only when tool use is actually weak. |
+| Fable 5 over-planning or unrequested work | Ask for the simplest in-scope result; forbid speculative features/refactors and unrequested side actions. Ground progress claims in tool results. Never request hidden chain-of-thought reproduction. |
+| GLM-5.2 cross-file review misses | Name the behavioral invariant and every surface that must agree. Generic “strict production review” can divert into hardening checklists; for distributed correctness, require explicit validation plus an independent second pass. |
+
+## 5. Host → cross-class peer pairing
 
 The rule: the peer must be a **different model class** than the host, or it is
 not cross-model evidence (fall back to a fresh same-class sub-agent instead).
 For each host, several valid peer classes exist — pick by **maximum blind-spot
-diversity**, and for deep work use **two distinct peer classes** (§5).
+diversity**, and for deep work use **two distinct peer classes** (§6).
 
 | Host class | Valid peer classes (any different class) |
 |---|---|
@@ -123,7 +135,7 @@ When the natural pair is unavailable, fall through to the next class; never
 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
+## 6. Multi-class review for deep/complex work
 
 The risk and `review_weight` policy lives in
 [advisory-review.md](advisory-review.md). At model-selection time, when that
@@ -131,7 +143,7 @@ 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
+## 7. Two-phase design review: advisory then adversarial
 
 The phase order, artifact-specific loop shapes, ceilings, and recording format
 live in [advisory-review.md](advisory-review.md). This model-layer reference adds
@@ -139,7 +151,7 @@ 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
+## 8. peeragent invocation cheatsheet
 
 Resolve the wrapper before calling — never assume `peeragent` is on `PATH`
 (`PEERAGENT_BIN` → bundled `bin/peeragent` → bare `peeragent`). Run in the
@@ -157,7 +169,7 @@ host harness's outside-sandbox mode; never `--full-access` for review.
 Always tell the reviewer **not** to recurse back through peeragent's own
 `peer`/`peer-review` skills or the wrapper — the reviewer is the endpoint.
 
-## 8. Fallbacks when no peer is reachable
+## 9. Fallbacks when no peer is reachable
 
 When peeragent is unavailable, fails, would be same-class, or the needed class
 isn't reachable: spawn a **fresh max-effort generic sub-agent** at the highest

package/skills/refactor-design/SKILL.md

@@ -195,8 +195,8 @@ across the lenses below and skip exploratory fanout. If one area is unclear, use
 focused exploratory sub-agent. Use parallel exploratory sub-agents only when the lenses need separate
 attention across a medium/large target.
 
-The first four scan axes are mandatory. Run them even when a project-specific
-refactor-conventions catalog exists. The catalog adds a fifth scan axis; it
+The first five scan axes are mandatory. Run them even when a project-specific
+refactor-conventions catalog exists. The catalog adds a sixth scan axis; it
 does not narrow or disable the default refactor judgment.
 
 - Use the host's generic/general-purpose subagent prompted with the scanner
@@ -207,28 +207,35 @@ does not narrow or disable the default refactor judgment.
   deployment-provided read-only role only if it is already available; otherwise
   keep the host-local scan fallback.
 
-1. **Code Smells** — "Find code that smells off in <area>. Look for: duplicated
+1. **Elimination First** — "Before proposing extraction or a new abstraction,
+   find code, tests, checks, wrappers, options, compatibility paths, and files
+   that can be deleted, inlined, merged, or made unnecessary. Include whole
+   subsystems whose maintenance cost may exceed their current value, but mark
+   any removal that changes behavior or guarantees as a user decision rather
+   than a pure refactor."
+
+2. **Code Smells** — "Find code that smells off in <area>. Look for: duplicated
    logic across files; long files (>500 lines); deep nesting (>4 levels); god
    functions (>100 lines doing multiple distinct things); god modules (>15
    methods or multiple responsibilities); leaky abstractions (consumers reaching
    past a module's public API). Report each with file:line and a one-line
    explanation."
 
-2. **Missing Abstractions** — "Find places where multiple modules implement
+3. **Missing Abstractions** — "Find places where multiple modules implement
    similar logic that could be extracted. Report each with file:line references
    and which modules would benefit."
 
-3. **Pattern Violations & Naming Inconsistencies** — "Read
+4. **Pattern Violations & Naming Inconsistencies** — "Read
    `.agents/skills/patterns/*.md` and legacy `.claude/skills/patterns/*.md` if
    they exist. Find code that deviates from established patterns. Report
    naming inconsistencies — same concept named differently across modules. Report
    each with file:line."
 
-4. **Dead Weight** — "Find dead code: unused exports (cross-check against grep
+5. **Dead Weight** — "Find dead code: unused exports (cross-check against grep
    for importers), commented-out blocks, TODO/FIXME where the work is clearly
    already done, files with very few callers. Report each with file:line."
 
-5. **Project Refactor Conventions** — Run only when
+6. **Project Refactor Conventions** — Run only when
    `.agents/skills/refactor-conventions/` exists. "Read
    `.agents/skills/refactor-conventions/SKILL.md`, its referenced rule files,
    and the `## Refactor Style Conventions` section in AGENTS.md if present.
@@ -245,7 +252,7 @@ findings.
 ### Phase 4: Categorize findings
 
 Sort the findings into:
-- **High value** — reduces duplication, extracts shared abstractions, consolidates
+- **High value** — eliminates code or concepts, reduces duplication, consolidates
   similar code, or corrects convention drift that materially improves module
   boundaries or repeated project workflow
 - **Medium value** — improves consistency, aligns with established patterns
@@ -262,14 +269,15 @@ run summary.
 
 For each step, specify:
 - **Step name and value tier** (High / Medium / Low)
-- **Source lens**: code smell / missing abstraction / pattern drift /
+- **Source lens**: elimination / code smell / missing abstraction / pattern drift /
   dead weight / refactor convention `<rule>` (if applicable)
 - **Files affected**: paths
 - **Current state**: actual code showing what exists now
 - **Target state**: exact code showing what it should look like after
 - **Implementation notes**: how to get from current to target; non-obvious considerations
-- **Acceptance criteria**: build passes, tests pass, plus specific structural/behavioral
-  check
+- **Acceptance criteria**: relevant verification passes plus a specific
+  structural/behavioral check; add or retain tests only where they protect an
+  important interface, complex unit, or regression
 - **Risk**: Low / Medium / High — what could go wrong
 - **Rollback**: how to revert this step if it breaks something
 
@@ -308,7 +316,7 @@ Append to the feature file's body:
 ### Step 1: <name>
 **Priority**: High/Medium/Low
 **Risk**: Low/Medium/High
-**Source Lens**: code smell / missing abstraction / pattern drift / dead weight / refactor convention `<rule>`
+**Source Lens**: elimination / code smell / missing abstraction / pattern drift / dead weight / refactor convention `<rule>`
 **Files**: `src/path/file.ext`, ...
 **Story**: `<story-id>` (if spawned)
 
@@ -369,7 +377,9 @@ In conversation:
   add — escalate via `/agile-workflow:scope` instead.
 - Each step is self-contained and committable in isolation. Multi-step PRs lose the
   ability to roll back individual steps.
-- Specify test verification for every step. A refactor without verification is a hope.
+- Specify proportionate verification for every step. Do not require a new unit
+  test for simple structural edits when build, type, integration, or existing
+  interface evidence is more useful.
 - Prioritize measurable improvements (less duplication, clearer boundaries) over
   aesthetic preferences. Beauty that doesn't reduce complexity isn't worth the risk.
 - Project-specific refactor conventions extend the defaults; they never replace

package/skills/review/SKILL.md

@@ -233,19 +233,32 @@ Deep lane:
   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
-
-- **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.
+### 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, a false/stale/contradictory
+  foundation-doc assertion, 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
 
@@ -259,8 +272,10 @@ 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.
+- 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.
 
@@ -315,8 +330,11 @@ 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.
@@ -344,10 +362,12 @@ Nothing blocking or significant to flag."
   concerns evaporate into review prose.
 - Review's security check is lightweight. For a full security gate, use
   `/agile-workflow:gate-security`.
-- Foundation-doc drift is a blocker, not a nit. Rolling foundation is a hard
-  rule.
+- A false, stale, or contradictory foundation-doc assertion is a blocker, not a
+  nit. Missing coverage and future-state claims whose implementation has not yet
+  landed are not drift and must not be flagged or changed.
 - 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/review-lenses.md

@@ -43,10 +43,20 @@ lenses and note any lens skipped with the reason.
 
 ## Foundation-Doc Alignment
 
-- Does implementation invalidate any assertion in foundation docs such as
-  `docs/VISION.md`, `docs/SPEC.md`, or `docs/ARCHITECTURE.md`?
-- If yes, did the implementer roll the doc forward in the same change?
-- Foundation-doc drift is a blocker in substrate mode.
+Foundation docs may describe current state or intended future state and need not
+cover every capability. Review assertions, not omissions:
+
+- Does implementation make an existing current-state assertion in
+  `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`, or another foundation
+  doc false or stale?
+- Does an existing future-state assertion contradict newer accepted intent or
+  another authoritative foundation claim? Lack of implementation alone is not a
+  contradiction.
+- If an assertion is false, stale, or contradictory, did the implementer roll it
+  forward in the same change?
+- Never request a foundation-doc addition merely because the change is missing
+  from those docs. Assertion drift is a blocker in substrate mode; omission is
+  not a finding.
 
 ## Naming And Comments
 

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/review/references/target-resolution.md

@@ -40,7 +40,8 @@ or story should already have passed review. Gather:
   children.
 
 Use the aggregate scope to spot cross-cutting concerns: public API shifts,
-foundation-doc drift, release gaps, and capability completeness.
+false/stale/contradictory foundation-doc assertions (not omissions or
+unimplemented future intent), release gaps, and capability completeness.
 
 ## Empty Diff Handling
 

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.16.1
+0.16.4