@nklisch/pi-agile-workflow 0.15.3 → 0.16.3

package/skills/gate-cruft/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: gate-cruft
 description: >
-  Cruft gate that scans the items bound to a release for AI-accumulated debris (dead code, stale
-  comments, compatibility shims, defensive bloat, over-abstraction) introduced or revealed by the
-  bundle. Delegates the full scan to a deep cleanup scanner agent which runs language-aware
+  Cruft gate focused on release-bound items that may follow relevant evidence into adjacent or
+  system-wide code. Finds dead code, stale comments, low-value tests and checks, compatibility
+  shims, defensive bloat, and over-abstraction, including whole systems that may no longer earn
+  their cost. Delegates the scan to a deep cleanup scanner agent which runs language-aware
   detection plus heuristic pattern-matching, then returns findings. The orchestrator converts findings
   into items in .work/active/ with gate_origin:cruft and tags:[cleanup]. Auto-triggers during
   /agile-workflow:release-deploy.
@@ -11,11 +12,14 @@ description: >
 
 # Gate-Cruft
 
-You orchestrate a cruft gate over the items bound to a release. The actual
-scan runs inside a **deep cleanup scanner agent** (a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`); your role is to prepare the bundle context,
+You orchestrate a cruft gate focused on the items bound to a release. Bound
+items establish the center of gravity, not a hard file boundary: the scanner may
+follow relevant call paths, dependencies, shared infrastructure, tests, or
+system-wide mechanisms needed to understand whether complexity still earns its
+cost. The actual scan runs inside a **deep cleanup scanner agent** (a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`); your role is to prepare the bundle context,
 dispatch the scanner, and convert the findings it returns into items in the
 substrate. Findings get `gate_origin: cruft`,
-`tags: [cleanup]`, with severity tier shaping the stage.
+`tags: [cleanup]`, with confidence shaping placement and stage.
 
 Scanner strength is explicit: spawn exactly one source-read-only deep cleanup
 scanner with the strongest inspection/reviewer setting the host exposes. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Use extra-high reasoning
@@ -70,9 +74,10 @@ confidence, and returns structured findings.
 **Brief template**:
 
 > You are conducting a cruft scan for release `<version>` as an agile-workflow
-> scanner. Use read/search/shell tools as needed. Audit ONLY the bundle's
-> changed files — not the whole repo. Do not spawn nested sub-agents or implement
-> fixes.
+> scanner. Use read/search/shell tools as needed. Start with the bundle's
+> changed files, then follow relevant evidence into adjacent dependencies,
+> shared infrastructure, tests, or system-wide mechanisms. Do not perform an
+> aimless whole-repo sweep, spawn nested sub-agents, or implement fixes.
 >
 > **Bundle scope**:
 > ```
@@ -90,8 +95,9 @@ confidence, and returns structured findings.
 >    `Cargo.toml`, `go.mod`, `pyproject.toml`, `Makefile`. This determines
 >    which language-aware detection tools are available.
 >
-> 2. **Language-aware detection (high confidence)** — run against the
->    bundle's changed files only:
+> 2. **Language-aware detection (high confidence)** — run against the bundle
+>    files first; expand a tool's scope only when needed to establish callers,
+>    duplication, reachability, ownership, or system-level cost:
 >    - **TypeScript/JavaScript** — `tsc --noUnusedLocals --noUnusedParameters
 >      --noEmit`, eslint unused rules
 >    - **Python** — `ruff check --select F811,F841,F401`, `vulture`
@@ -99,7 +105,8 @@ confidence, and returns structured findings.
 >    - **Rust** — compiler warnings for `#[warn(dead_code)]`
 >    Capture output and parse into findings.
 >
-> 3. **Heuristic pattern-matching** via Grep on bundle files:
+> 3. **Heuristic pattern-matching** via Grep, beginning with bundle files and
+>    following concrete references where the evidence leads:
 >
 >    **Medium confidence:**
 >    - Comments containing "removed", "backwards compat", "for backwards
@@ -117,12 +124,27 @@ confidence, and returns structured findings.
 >    - Single-use helper functions that could be inlined
 >    - Config/options parameters that only ever receive one value
 >    - Abstractions with a single implementation
+>    - Duplicate, tautological, obsolete, or implementation-bound tests
+>    - Validation/check layers whose guarantees exceed the project's actual scope
 >
-> 4. **Cross-check existing patterns** — read `.agents/skills/patterns/` and
+> 4. **System-level challenge** — inspect whether an entire validation layer,
+>    invariant/check system, test suite, compatibility mechanism, defensive
+>    subsystem, or abstraction family exposed by the bundle still justifies its
+>    maintenance cost. State its current purpose, evidence of cost, what removal
+>    would simplify, and which behavior or guarantee would be lost. Classify
+>    these as `Decision required`; never assume the guarantee should disappear.
+>
+> 5. **Cross-check existing patterns** — read `.agents/skills/patterns/` and
 >    legacy `.claude/skills/patterns/` if
 >    present. Intentional repetition documented as a pattern is NOT cruft.
 >
-> 5. **Triage by confidence**:
+> 6. **Triage by confidence, release relevance, and decision need**:
+>    - `Release-relevant`: caused by, exposed by, or materially affects the bundle.
+>    - `Ambient`: useful discovery outside release scope; propose as unbound backlog.
+>    - `Decision required: yes`: any whole-system removal candidate, especially
+>      one that changes behavior or guarantees; ask before creating removal work.
+>
+>    Then triage confidence:
 >    | Confidence | Stage of produced item |
 >    |---|---|
 >    | High (tool-detected) | `stage: implementing` |
@@ -139,7 +161,11 @@ confidence, and returns structured findings.
 > - **Confidence**: High | Medium | Low
 > - **Category**: unused import | dead function | stale comment |
 >   compatibility shim | passthrough wrapper | defensive try/catch |
->   single-use helper | over-abstraction
+>   single-use helper | over-abstraction | low-value test | redundant checks |
+>   system-level simplification
+> - **Relevance**: Release-relevant | Ambient
+> - **Decision required**: yes | no
+> - **Guarantee affected**: none | <behavior/validation/determinism/compatibility/safety>
 > - **Location**: `<file>:<line>`
 > - **Evidence**:
 >   ```<lang>
@@ -162,7 +188,8 @@ confidence, and returns structured findings.
 > ```
 >
 > **Rules**:
-> - Scan only Bundle scope. Don't expand.
+> - Bundle scope is the focus, not a hard boundary. Expand only by following
+>   concrete evidence; record why each out-of-bundle file or system was inspected.
 > - Cite file:line for every finding.
 > - Don't fabricate. If a tool produces no output, don't invent findings.
 > - Skip already-tracked. Patterns documented in
@@ -172,9 +199,19 @@ confidence, and returns structured findings.
 >   used externally?" — if you can't confirm zero callers, downgrade to
 >   medium confidence rather than high).
 
-### Phase 4: Convert findings to items
+### Phase 4: Resolve system-level removal decisions
+
+For each `Decision required` candidate, present the system's purpose, current
+cost, proposed simplification, and guarantees or behavior removal would weaken.
+Ask the user whether to remove, reduce, retain, or park it. Group related
+candidates and use the structured question tool in batches when available.
+Never turn a guarantee-reducing proposal into active work without confirmation.
+In a non-interactive gate path, write an unbound backlog decision proposal and
+continue; do not assume consent or block unrelated release work.
 
-For each finding the scanner returned:
+### Phase 5: Convert findings to items
+
+For each confirmed or ordinary finding the scanner returned:
 
 Read `gate_finding_routing` from `.work/CONVENTIONS.md` before writing items.
 If absent, use the default routing below. Normalize cruft confidence to routing
@@ -191,7 +228,7 @@ stage: implementing | drafting    # by confidence
 tags: [cleanup]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient or unconfirmed decision proposals
 gate_origin: cruft
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -217,12 +254,17 @@ High | Medium | Low
 <what to remove and what to fix in the surroundings — imports, whitespace, etc.>
 ```
 
+Release-relevant findings use the normal confidence mapping and bind to the
+release. Ambient findings and unconfirmed decision proposals always go to the
+unbound backlog regardless of confidence. A confirmed system removal may bind
+only when the user explicitly includes it in the current release.
+
 Default confidence -> placement mapping:
 - **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
 - **Low** → backlog file in `.work/backlog/`
 
-### Phase 5: Commit
+### Phase 6: Commit
 
 ```bash
 git add .work/active/stories/ .work/backlog/
@@ -233,7 +275,7 @@ git commit -m "gate-cruft: <N> findings for <version>"
 
 In conversation:
 - **Bundle**: `<version>` — `<N>` items audited, `<M>` files changed
-- **Findings**: count by confidence (High / Medium / Low)
+- **Findings**: count by confidence and relevance (release / ambient / decision)
 - **Items created**: count, with new ids
 - **Already-tracked**: count skipped
 
@@ -247,10 +289,13 @@ and parallelizes well."
 
 - **The scan happens in the scanner agent, not here.** Your job is bundle
   prep, dispatch, and item-writing. Don't replicate the scanner's analysis.
-- Audit only the bundle's changed files, not the whole repo.
+- Release-bound items define focus, not a hard boundary. Follow concrete
+  evidence into adjacent or system-wide code, but do not turn the gate into an
+  unfocused whole-repo audit.
 - Never remove code in this skill — produce items only.
-- Cleanup items must be surgical when implemented. They remove cruft and fix
-  the immediate surroundings only. They do NOT improve, refactor, or enhance.
+- Local cleanup items should stay surgical. Whole-system simplification is
+  allowed as a proposal, but any reduction in behavior or guarantees requires
+  explicit user confirmation and appropriately scoped design work.
 - Patterns documented in `.agents/skills/patterns/` or legacy
   `.claude/skills/patterns/` are intentional, not
   cruft. The scanner cross-checks; don't override.

package/skills/gate-docs/SKILL.md

@@ -155,6 +155,7 @@ returns structured findings.
 >   changelog-gap | repo-skill-staleness | pattern-skill-staleness |
 >   generated-file-needs-regen | doc-misplacement
 > - **Confidence**: High | Medium
+> - **Relevance**: Release-relevant | Ambient
 > - **Doc location**: `<file>:<line>`
 > - **Code location**: `<file>:<line>` (for assertion drift; omit for gaps)
 > - **Current doc text**:
@@ -179,8 +180,9 @@ returns structured findings.
 > ```
 >
 > **Rules**:
-> - Scan only the bundle's changes plus the docs that own those areas.
->   Don't audit every doc in the repo.
+> - Bundle changes and their owning docs are the focus, not a hard boundary.
+>   Follow concrete references into adjacent docs, generated catalogs, or
+>   system-wide documentation when needed; do not perform an aimless doc sweep.
 > - Cite file:line for every finding.
 > - Required edits ENFORCE rolling-foundation: replace stale assertions in
 >   place. Do NOT propose adding "previously" or "in v1.x" prose. Git is the
@@ -210,7 +212,7 @@ stage: implementing       # high-confidence drift
 tags: [documentation]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: docs
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -239,6 +241,10 @@ no "previously" prose, no "in v1.x" notes. Replace the assertion in place.>
 For generated files needing regeneration, the item describes the regeneration
 command rather than a manual edit.
 
+Release-relevant drift uses the normal confidence mapping and binds to the
+release. Ambient staleness merely discovered while following references goes to
+the unbound backlog.
+
 Default confidence -> placement mapping:
 - **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -272,7 +278,8 @@ In conversation:
   place. Do NOT propose adding "previously" or "in v1.x" prose.
 - Don't fix the docs in this skill — produce items only. Implementation of
   the fixes happens via `/agile-workflow:implement` on each item.
-- Audit only the bundle's changes plus the docs that own those areas — the
-  scanner enforces this; don't override.
+- Release-bound changes define focus, not a hard boundary. Follow concrete
+  documentation ownership and reference chains; route merely ambient drift to
+  the unbound backlog rather than silently expanding the release.
 - Generated files get items describing the regeneration command, not manual
   edits.

package/skills/gate-patterns/SKILL.md

@@ -107,7 +107,7 @@ output.
 > Use read/search/shell tools as needed. Do not spawn nested sub-agents or modify
 > source files.
 >
-> **Bundle scope**:
+> **Bundle focus** (start here; follow recurring shapes across the repository):
 > ```
 > <bundle-files>
 > ```
@@ -120,8 +120,10 @@ output.
 >
 > **Methodology**:
 >
-> 1. **Pattern discovery passes** — inspect the bundle's changed files plus
->    their immediate consumers (since reuse implies multiple call sites):
+> 1. **Pattern discovery passes** — inspect the bundle's changed files first,
+>    then follow candidate shapes through consumers and the wider repository
+>    where needed to establish genuine recurrence. Bound files are the focus,
+>    not a hard scan boundary:
 >    - **Shared abstractions & utilities** — find new shared/reusable code
 >      introduced in the bundle: utility functions, base classes, common
 >      helpers, types used across multiple modules. List each with
@@ -225,6 +227,8 @@ output.
 >   the divergence instead.
 > - Don't fabricate patterns. If discovery yields nothing, return an empty
 >   "New patterns" section.
+> - Expansion beyond the bundle must follow a concrete candidate pattern or
+>   inconsistency; do not perform an unfocused whole-repo style audit.
 
 ### Phase 4: Write pattern files
 

package/skills/gate-refactor/SKILL.md

@@ -139,8 +139,10 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 **Brief template**:
 
 > You are conducting a refactor gate scan for release `<version>` as an agile-workflow
-> scanner. Use read/search/shell tools as needed. Scan ONLY the bundle's changed files —
-> not the whole repo. Do not spawn nested sub-agents or implement fixes.
+> scanner. Use read/search/shell tools as needed. Start with the bundle's changed
+> files and follow concrete rule-relevant references into adjacent consumers,
+> dependencies, or shared systems. Do not perform an aimless whole-repo sweep,
+> spawn nested sub-agents, or implement fixes.
 >
 > **Bundle scope** (files changed by the bundle):
 > ```
@@ -169,6 +171,7 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 >
 > 1. Read every file in the bundle scope.
 > 2. For each file, check against all rules from all loaded libraries in a single pass.
+>    Expand only when a rule or concrete reference requires adjacent/system-wide context.
 > 3. For each finding, record:
 >    - **Library tag**: which library's rule was violated (e.g. `structural`).
 >    - **Rule slug**: which specific rule was violated (from the library's rule inventory).
@@ -176,11 +179,13 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 >    - **Issue**: one-sentence description of the violation.
 >    - **Fix**: specific proposed change (or "needs analysis" for findings requiring judgment).
 >    - **Confidence**: `high` / `medium` / `low` per the library's guidance for that rule.
+>    - **Relevance**: `Release-relevant` or `Ambient`.
 > 4. Deduplicate against the already-tracked set.
 > 5. Return findings as a structured list.
 >
 > **Rules**:
-> - Scan only the bundle scope. Do not expand to the whole repo.
+> - Bundle scope is the focus, not a hard boundary. Follow concrete rule-relevant
+>   evidence and record why any out-of-bundle surface was inspected.
 > - Cite file:line for every finding.
 > - Do not fabricate findings. If a rule produces no matches, emit nothing for it.
 > - Skip already-tracked findings (exact file:line + rule-slug match).
@@ -199,6 +204,7 @@ M-times-N redundant file reads and allows cross-library finding deduplication.
 > - **Library**: <library-tag>
 > - **Rule**: <rule-slug>
 > - **Confidence**: High | Medium | Low
+> - **Relevance**: Release-relevant | Ambient
 > - **Location**: `<file>:<line>`
 > - **Issue**: <one sentence>
 > - **Fix**: <specific proposed change or "needs analysis">
@@ -248,7 +254,7 @@ stage: implementing | drafting    # by gate_finding_routing
 tags: [refactor]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: refactor
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -265,7 +271,7 @@ stage: implementing | drafting    # by gate_finding_routing
 tags: []
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: refactor
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -296,6 +302,10 @@ High | Medium | Low
 <specific proposed change, or "needs analysis" for medium/low>
 ```
 
+Release-relevant findings use the normal confidence mapping and bind to the
+release. Ambient rule violations discovered outside the bundle go to the
+unbound backlog regardless of confidence.
+
 Default confidence -> placement mapping:
 
 | Confidence | Stage | Tier |
@@ -343,7 +353,9 @@ In conversation:
 
 - **The scan happens in the scanner agent, not here.** Your job is library discovery, bundle prep,
   dispatch, and item-writing. Do not replicate the scanner's analysis.
-- Scan only the bundle's changed files, not the whole repo.
+- Release-bound files define focus, not a hard boundary. Follow concrete
+  rule-relevant evidence into adjacent or system-wide code, but do not perform
+  an unfocused whole-repo scan; route ambient findings to the unbound backlog.
 - Never apply fixes in this skill — produce items only.
 - **No-libraries is not an error.** Graceful skip with a log entry is the correct behavior when
   no scan-* libraries are installed.

package/skills/gate-security/SKILL.md

@@ -91,8 +91,8 @@ structured findings.
 > agile-workflow scanner. Use read/search/shell/current-source lookup tools as
 > needed, but do not spawn nested sub-agents or implement fixes.
 >
-> **Bundle scope** (audit ONLY these files; this is a release gate, not a
-> repo-wide audit):
+> **Bundle focus** (start here; follow concrete security-relevant call paths,
+> dependencies, shared infrastructure, and controls as needed):
 > ```
 > <bundle-files>
 > ```
@@ -138,7 +138,8 @@ structured findings.
 >       logs, missing error boundaries, verbose prod errors. All prod apps.
 >
 > 3. **Domain audit passes** — for each selected domain, audit the bundle's
->    changed files against that domain's checklist. Use current-source lookup
+>    changed files against that domain's checklist, following concrete evidence
+>    into adjacent security boundaries, dependencies, and shared controls. Use current-source lookup
 >    when needed to verify best practices for `<stack>+<domain>` combinations
 >    before judging.
 >
@@ -160,6 +161,7 @@ structured findings.
 > - **Title**: <one-line>
 > - **Severity**: Critical | High | Medium | Low
 > - **Domain**: <domain name>
+> - **Relevance**: Release-relevant | Ambient
 > - **Location**: `<file>:<line>`
 > - **Evidence**:
 >   ```<lang>
@@ -182,7 +184,8 @@ structured findings.
 > ```
 >
 > **Rules**:
-> - Audit only the files listed in Bundle scope. Do NOT expand the audit.
+> - Bundle files are the focus, not a hard boundary. Expand only along concrete
+>   security-relevant evidence and record why out-of-bundle surfaces were inspected.
 > - Cite file:line for every finding.
 > - Don't fabricate. If evidence is missing, don't report.
 > - Skip findings that match the already-tracked list.
@@ -211,7 +214,7 @@ stage: implementing      # Critical or High
 tags: [security]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: security
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -237,6 +240,11 @@ Critical | High | Medium | Low
 <what should change — direction, not a finished fix>
 ```
 
+Release-relevant findings use the normal severity mapping and bind to the
+release. Ambient findings discovered outside the release's material risk go to
+the unbound backlog regardless of severity; a genuinely critical repository
+vulnerability is release-relevant when shipping would expose or perpetuate it.
+
 Default severity -> placement mapping:
 - **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -271,5 +279,6 @@ In conversation:
   returns nothing. Don't paper that over.
 - Idempotent re-runs: pass already-tracked findings into the scanner brief so it
   skips duplicates. Double-check on item-write before creating.
-- Audit only the bundle's changes, not the whole repo. Repo-wide audits are
-  a standalone `repo-eval`'s job, not a release gate's.
+- Release-bound items define focus, not a hard boundary. Follow concrete
+  security evidence into adjacent or system-wide controls, but do not perform
+  an unfocused whole-repo audit. Route merely ambient findings to the unbound backlog.