@nklisch/pi-agile-workflow 0.16.1 → 0.16.3

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, 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
 
@@ -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.
@@ -347,7 +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.16.1
+0.16.3