@nklisch/pi-agile-workflow 0.15.3 → 0.16.3

package/skills/gate-tests/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: gate-tests
 description: >
-  Test-quality gate that scans items bound to a release for test coverage gaps. Delegates the full
-  analysis to a deep test scanner agent which derives expected coverage from each bound item's
-  acceptance criteria (NOT from implementation code), maps existing test coverage, identifies gaps,
-  and returns findings. The orchestrator converts findings into gate_origin:tests items in
+  Test-quality gate focused on release-bound items that may follow relevant evidence into adjacent
+  interfaces and test systems. Derives useful coverage from contracts, risk, and bug history—not
+  line coverage—and identifies both valuable gaps and low-value tests worth removing. Delegates the
+  analysis to a deep test scanner agent, which maps existing coverage and
+  returns findings. The orchestrator converts findings into gate_origin:tests items in
   .work/active/. Auto-triggers during /agile-workflow:release-deploy.
 ---
 
@@ -24,16 +25,18 @@ in the release body.
 
 ## Core principle
 
-The gate's principle: **tests derive from specs, not implementations**. Each
-bound item's acceptance criteria IS the spec. The scanner verifies those
-criteria are covered, finds gaps, and returns them. It also checks the seams
-BETWEEN bound items — integration coverage where one item's output feeds
-another.
+The gate's principle: **tests must earn their upkeep**. Tests derive from
+stable contracts, meaningful risks, and regressions learned from real bugs—not
+from implementation shape or a demand to cover every line. Prefer important
+public interfaces and cross-item seams. Unit tests belong around genuinely
+complex isolated logic, not every wrapper or branch. The gate identifies both
+high-value gaps and duplicate, tautological, brittle, obsolete, or
+implementation-bound tests that should be removed.
 
-Tests derived from reading implementation code are tautological — they verify
-that the code does what the code does. Tests derived from specs verify what
-the code *should* do. That's where bugs live. The scanner brief enforces this
-discipline.
+Bound items are the focus, not a hard scan boundary. Follow concrete evidence
+into adjacent interfaces, shared test infrastructure, dependencies, or a whole
+test/check system when needed. Bind findings to the release only when materially
+relevant; route ambient discoveries to the unbound backlog.
 
 ## Trigger
 
@@ -90,8 +93,10 @@ test-design techniques to find gaps, and returns structured findings.
 **Brief template**:
 
 > You are conducting a test-quality gate for release `<version>`. Core
-> principle: **tests derive from specs, not implementations**. Each bound
-> item's acceptance criteria IS the spec.
+> principle: **tests must earn their upkeep**. Derive tests from stable
+> contracts, meaningful risk, and bug regressions—not implementation shape or
+> universal coverage. Acceptance criteria are evidence of intent, not a mandate
+> for one automated test per statement.
 >
 > Use read/search/shell tools as needed. Do not spawn nested sub-agents or implement
 > fixes.
@@ -143,32 +148,35 @@ test-design techniques to find gaps, and returns structured findings.
 >    - Implementation units / unit names
 >    - Public interface surface (functions, types, endpoints exposed)
 >
->    These four axes plus the explicit acceptance criteria form the spec.
+>    These axes and acceptance criteria describe candidate behavior. Rank them
+>    by consequence, stability, complexity, and demonstrated failure history
+>    before deciding that automated coverage is worthwhile.
 >
-> 2. **Map existing test coverage.** For each bound item, find tests that
+> 2. **Map existing test value and coverage.** For each bound item, find tests that
 >    reference its implementation. For files changed by item `<id>`, list all
 >    tests covering those files. For each test, identify which acceptance
->    criterion or behavioral contract it verifies. Cite file:line. Note any
->    tests that appear to mirror implementation step-by-step (tautological —
->    should be reworked or deleted). Do NOT read implementation bodies; only
->    test files and types. Read 2-3 key test files yourself to verify the map.
+>    criterion, interface, regression, or complex unit it protects. Cite
+>    file:line. Flag tests that mirror implementation step-by-step, duplicate
+>    stronger interface coverage, exercise trivial wrappers, or protect obsolete
+>    behavior; recommend deletion when removal preserves useful confidence.
+>    Read implementation only to establish complexity, interfaces, or whether a
+>    test is coupled to internals—not to invent an assertion target. Read 2-3
+>    key test files yourself to verify the map.
 >
-> 3. **Apply test-design techniques** for each acceptance criterion not
->    covered by tests:
->    - **Equivalence partitioning** — one test per valid partition, one per
->      invalid
->    - **Boundary value analysis** — for ranges: just-below, at, just-above
->    - **Decision table** — for criteria with multiple conditions, enumerate
->      combinations
->    - **State transition** — for state changes, test valid transitions and
->      verify invalid ones are rejected
+> 3. **Apply test-design techniques selectively** to high-value contracts not
+>    already covered. Use only the techniques justified by actual risk:
+>    - **Equivalence partitioning** — choose representative partitions where
+>      distinctions matter
+>    - **Boundary value analysis** — sample consequential range boundaries
+>    - **Decision table** — cover combinations with materially different outcomes
+>    - **State transition** — cover important valid transitions and invalid ones
+>      the contract promises to reject
 >    - **Error guessing (spec-driven)** — anything described as "should
 >      not", "must not", "invalid", "error", "reject"
 >
-> 4. **Adversarial coverage** — for each bound item, surface failure
->    expectations along these axes. If the item body or design doesn't
->    state the answer, the gap itself is a finding (`stage: drafting`,
->    `tags: [testing]`):
+> 4. **Risk review** — for each bound item, consider failure expectations along
+>    these axes only where the project's scope and consequences make them
+>    meaningful. Silence in the spec is not automatically a testing finding:
 >    1. Invalid input — when a caller passes invalid data, what should
 >       happen? (Reject? Fall back? Log and continue?)
 >    2. Missing config — when required configuration is absent, what's the
@@ -182,9 +190,8 @@ test-design techniques to find gaps, and returns structured findings.
 >    6. Interrupted operations — if a multi-step operation is interrupted,
 >       what's the expected end state?
 >
->    Where the spec is silent, produce either: (a) a `[testing]` story to
->    write the test once the spec is settled, or (b) a `[documentation]`
->    story to extend the spec with the missing assertion target.
+>    Where the spec is silent, emit a finding only when the missing contract is
+>    consequential for this project. Otherwise record that no test is warranted.
 >
 > 5. **Map e2e seams.** For items with `depends_on` chains, check whether
 >    the seam between them is tested:
@@ -197,16 +204,17 @@ test-design techniques to find gaps, and returns structured findings.
 >    feature's overall acceptance criteria are e2e-covered, not just
 >    per-story unit-covered.
 >
-> 6. **Classify gaps**:
+> 6. **Classify findings**:
 >    | Priority | Definition |
 >    |---|---|
->    | Critical | Acceptance criterion with no test |
->    | High | Boundary or error case from spec, no test |
->    | Medium | Valid partition or rule combination, no test |
->    | Low | Complementary coverage |
+>    | Critical | High-consequence public contract or known regression lacks protection |
+>    | High | Important interface, seam, or complex behavior lacks useful coverage |
+>    | Medium | Material confidence gain, but not release-critical |
+>    | Low | Ambient improvement or low-value test removal proposal |
 >
->    Also flag tautological tests found during step 2 — they need rework or
->    deletion.
+>    No finding is created merely because a line, branch, unit, edge, or
+>    acceptance statement lacks its own test. Also classify relevance as
+>    `Release-relevant` or `Ambient`, and flag low-value tests for deletion.
 >
 > **Output format** — return a single markdown document with:
 >
@@ -216,10 +224,12 @@ test-design techniques to find gaps, and returns structured findings.
 > ### Finding 1
 > - **Title**: <one-line: spec condition not covered>
 > - **Priority**: Critical | High | Medium | Low
-> - **Bound item**: `<item-id>`
-> - **Acceptance criterion**: <quote the criterion>
-> - **Gap type**: missing test for valid partition / boundary / error case /
->   adversarial-spec-silent / e2e-seam / tautological-rework
+> - **Bound item**: `<item-id>` | none
+> - **Relevance**: Release-relevant | Ambient
+> - **Value protected**: public interface | seam | complex unit | bug regression | test removal
+> - **Contract / risk / regression evidence**: <quote or concrete evidence>
+> - **Gap type**: important-interface / complex-unit / bug-regression /
+>   e2e-seam / low-value-test-removal
 > - **Suggested test**:
 >   ```<lang>
 >   // Sketch of the test — name, scenario, assertion target.
@@ -241,14 +251,14 @@ test-design techniques to find gaps, and returns structured findings.
 > ```
 >
 > **Rules**:
-> - Derive tests from specs, NOT from implementation code. If you find
->   yourself reading a function body to decide what to verify, stop — go
->   back to the spec.
-> - Test the public interface, not internal implementation.
-> - Cite spec references in every finding. A finding without a spec
->   reference is testing an assumption, not a contract.
-> - Prioritize invalid input, error cases, boundary conditions.
-> - Audit only the bundle's items, not the whole repo.
+> - Derive assertion targets from contracts, risk, and bug history—not
+>   implementation steps. Implementation may establish complexity or coupling.
+> - Prefer public interfaces and meaningful seams over internal implementation.
+> - Cite a contract, demonstrated risk, bug regression, or concrete maintenance
+>   cost for every finding. No evidence means no test work.
+> - Do not chase universal edge, branch, line, or surface coverage.
+> - Bound items are the focus, not a hard boundary. Follow concrete evidence and
+>   record why out-of-bundle test systems were inspected.
 > - Skip already-tracked.
 >
 > **Test integrity findings** (additional pass — flag and surface as
@@ -259,8 +269,9 @@ test-design techniques to find gaps, and returns structured findings.
 >   assertions.
 > - Tests that were silenced rather than diagnosed: broad `skip` /
 >   `xfail` / `it.todo` with no linked backlog id or written reason.
-> - Tests deleted in the bundle's commits with no replacement coverage
->   for the same acceptance criterion. (Check `git log` of the bundle.)
+> - Tests deleted in the bundle's commits when the removal leaves an important
+>   interface, complex behavior, or known regression without useful protection.
+>   (Check `git log` of the bundle.)
 > - Tests whose assertion was rewritten to match new-but-undocumented
 >   behavior — i.e. the test was made to follow the code instead of the
 >   code being made to follow the spec.
@@ -289,7 +300,7 @@ stage: implementing       # critical/high
 tags: [testing]
 parent: null
 depends_on: []
-release_binding: <version>
+release_binding: <version> | null  # null for ambient findings
 gate_origin: tests
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
@@ -300,9 +311,9 @@ updated: YYYY-MM-DD
 ## Priority
 Critical | High | Medium | Low
 
-## Spec reference
-Item: `<bound-item-id>`
-Acceptance criterion: <quote the criterion>
+## Value evidence
+Item: `<bound-item-id>` (or `none` for ambient findings)
+Contract / risk / regression / maintenance cost: <concrete evidence>
 
 ## Gap type
 <missing test for valid partition / boundary / error case / etc.>
@@ -316,6 +327,10 @@ Acceptance criterion: <quote the criterion>
 `<test-file-path>` (following project conventions)
 ```
 
+Release-relevant findings use the normal priority mapping and bind to the
+release. Ambient findings—including repository-wide low-value test systems
+merely discovered by the scan—go to the unbound backlog regardless of priority.
+
 Default priority -> placement mapping:
 - **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
 - **Medium** → `stage: drafting` in `.work/active/stories/`
@@ -327,8 +342,8 @@ Tautological tests get items too:
 # id: gate-tests-rework-<original-test-slug>
 # kind: story
 # tags: [testing, refactor]
-# Body describes which test is tautological and what spec behavior it should be
-# rewritten to verify (or marked for deletion).
+# Body describes why the test adds too little confidence for its upkeep and
+# whether it should be rewritten around a valuable contract or deleted.
 ```
 
 ### Phase 5: Commit
@@ -343,7 +358,8 @@ git commit -m "gate-tests: <N> coverage gaps for <version>"
 In conversation:
 - **Bundle**: `<version>` — `<N>` items audited
 - **Coverage gaps**: count by priority
-- **Tautological tests flagged**: count
+- **Low-value tests flagged for removal**: count
+- **Ambient findings**: count routed to unbound backlog
 - **Items created**: count, with new ids
 - **Already-tracked**: count of duplicates skipped
 
@@ -352,12 +368,11 @@ In conversation:
 - **The analysis happens in the scanner agent, not here.** Your job is bundle
   prep, dispatch, and item-writing. Don't replicate the scanner's contract
   extraction or coverage mapping.
-- The scanner brief enforces "specs not implementations". Don't substitute
-  your own judgment for findings.
-- Cite spec references in every item body. The scanner provides them.
-- Prioritize invalid input, error cases, boundary conditions — that's where
-  bugs hide and specs are most often undertested.
-- Audit only the bundle's items, not the whole repo.
+- The scanner brief enforces contract/risk/regression value over implementation
+  shape or coverage metrics. Don't substitute line-coverage pressure.
+- Cite the contract, risk, regression, or maintenance cost in every item body.
+- Release-bound items define focus, not a hard boundary. Follow concrete
+  evidence, but route ambient discoveries to the unbound backlog.
 - A failing test that exposes a real spec violation is the most valuable
   output. Don't sand it down — surface it as a Critical finding so the
   implementation gets fixed before shipping.

package/skills/implement/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: implement
 description: >
-  ALWAYS invoke this skill when the user explicitly asks to implement a substrate item inline OR the
-  delivery is tiny (about 50 LoC or less, two files or fewer, no coordination) OR the deliverable is no-code prose (a
-  [prose] item — any size, as long as it needs no coordination) — for any larger or default *code*
-  work prefer /agile-workflow:implement-orchestrator. Inline single-stride implementation of a
-  substrate item at stage:implementing. Reads the design embedded in the item body, writes code per
-  the spec, runs build+tests, advances stage implementing to review, and updates the item body with
-  implementation notes. Triggers on "implement this inline", "implement this item inline", "just do it
-  inline", or a very small explicit delivery.
+  ALWAYS invoke this skill when the user explicitly asks to implement a substrate item inline, when
+  the work is cohesive enough for one owner, or when the deliverable is no-code prose (a [prose]
+  item of any size that needs no coordination). Inline implementation of an item at
+  stage:implementing. Reads the design in the item body, implements and verifies it, records the
+  chosen execution capability, and continues through review to done unless the caller requests
+  stop-at-review. Prefer /agile-workflow:implement-orchestrator when ownership, sequencing, or
+  uncertainty makes delegated coordination useful. Triggers on "implement this inline", "implement
+  this item inline", "just do it inline", or a focused explicit delivery.
 ---
 
 # Implement
@@ -20,24 +20,21 @@ notes there as you work.
 
 ## Trigger
 
-`/agile-workflow:implement-orchestrator` is the default routing for implementing
-work, including lone stories. This skill is the **inline alternative** — same
-work, no sub-agent fan-out — and it's the right call when:
-
-- The delivery is small and focused (a tiny tweak, a single-file change, a
-  flag flip, landing code already in the working tree)
-- The deliverable is **no-code prose** (a `[prose]` feature — docs, a
-  convention / rule, research write-up, copy). The ≤50 LoC / ≤2 files cap is a
-  *code-coordination* proxy; it does not apply to prose, which qualifies on
-  **no-coordination** alone regardless of length. A 600-line convention rewrite
-  is one authoring stride, not an orchestrated fan-out.
-- The user explicitly asks to implement inline / "do it yourself"
-- You're already mid-flow on this item and a hand-off would lose context
-
-When the work is multi-unit *code*, spans several files, or has sibling stories
-that could run in parallel, prefer the orchestrator. When in doubt on code work
-and nothing strongly points either way, the orchestrator is the safer default.
-Prose work is never a reason to reach for the orchestrator.
+`/agile-workflow:implement-orchestrator` is the default routing for implementation
+that benefits from coordination. This skill is the **inline alternative** — the
+same lifecycle, owned by the current agent without implementation fan-out.
+Choose between them from cohesion, ownership, sequencing, and uncertainty:
+
+- Prefer inline when one owner can carry a cohesive change end to end, a handoff
+  would lose useful context, or the caller explicitly requests inline execution.
+- Prefer the orchestrator when work has independent ownership surfaces,
+  dependency-driven sequencing, useful parallelism, or enough uncertainty that
+  isolated workers improve delivery.
+- Tiny changes (roughly tens of lines or a couple of files) are a useful hint
+  toward inline execution, never a routing gate.
+- **No-code prose** (`[prose]`) qualifies for inline execution on
+  **no-coordination** grounds regardless of length. Prose is never routed to the
+  orchestrator merely because it is long.
 
 Common phrases:
 - "implement story X", "implement this feature"
@@ -87,7 +84,7 @@ Autopilot pre-filters via `work-view --ready` so this should rarely fire under
 autopilot. Interactive callers will see the note and can choose to fix the
 dep or remove it.
 
-### Phase 2.5: Choose delivery mode
+### Phase 2.5: Choose delivery mode and capability
 
 If the item carries `tags: [prose]`, use **prose mode** for the rest of this skill:
 
@@ -100,6 +97,13 @@ If the item carries `tags: [prose]`, use **prose mode** for the rest of this ski
 
 For non-prose items, continue in code mode.
 
+For either mode, select execution capability from the item's risk and scope
+unless the caller, a stable project convention, or an autopilot caller note
+overrides it. Do not ask a routine model-tier question. Also resolve the
+effective `review_weight`: explicit caller override, then project convention,
+otherwise `standard`. Record both choices in Phase 7; the principles and review
+skills own the weight matrix.
+
 ### Phase 3: Map integration points
 
 For `[prose]` items, map prose integration points instead:
@@ -165,7 +169,8 @@ In land mode:
    as-built reality (paths, interfaces, signatures).
 2. Validate — typecheck, lint, tests scoped to touched packages
    (`pnpm --filter`, `cargo -p`, `pytest <path>`).
-3. Fill test gaps for any meaningful behavior that lacks coverage.
+3. Fill high-value test gaps at stable interfaces, for complex logic, or for
+   demonstrated regressions; remove obsolete or low-value tests exposed by the work.
 4. Skip Phase 6 (no new code) and go straight to Phase 7 (notes — log
    "Land mode" explicitly), Phase 8 (verify), Phase 9 (commit + advance).
 
@@ -192,13 +197,19 @@ For code items:
 For each unit/file in the item's design:
 1. Write the code following the design's specifications — exact types, signatures,
    contracts
-2. Apply established patterns from the codebase
-3. Handle every error path the design specifies
-4. Write tests that verify behavior, not implementation
+2. Apply established patterns from the codebase without adding speculative layers
+3. Handle the error paths and guarantees the design actually requires
+4. Write tests only where they protect an important interface, complex unit, or
+   demonstrated regression; remove low-value tests the change makes obsolete
 5. Update module exports (index files) so new code integrates cleanly
+6. Run an elimination pass over the touched area: delete, inline, or consolidate
+   code, checks, abstractions, compatibility paths, and test machinery made
+   unnecessary by the implementation
 
-Take pride in the details: clean variable names, idiomatic control flow, meaningful
-error messages. Code that a future developer would read with appreciation.
+Safe behavior-preserving cleanup that is cohesive with the touched code is part
+of the task. Park larger or unrelated cleanup, and stop for a design decision
+before weakening behavior, guarantees, validation, compatibility, or safety.
+Prefer short, direct, readable code over a generalized framework.
 
 ### Phase 7: Update item body with implementation notes
 
@@ -206,8 +217,11 @@ Append (or update) an "Implementation notes" section in the item's body:
 
 ```markdown
 ## Implementation notes
+- Execution capability: <choice and brief risk/scope rationale>
+- Review weight: <effective value and source: caller, project, or default>
 - Files changed: <list>
-- Tests added: <list>
+- Tests added/removed: <list and the interface, complexity, or regression value>
+- Simplification: <code, checks, abstractions, or compatibility paths removed/consolidated>
 - Discrepancies from design: <list with one-line explanation each, or "none">
 - Adjacent issues parked: <list of backlog ids if any, or "none">
 ```
@@ -234,42 +248,47 @@ Don't claim done if tests don't pass. A known gap reported is better than a hidd
 
 #### Test integrity
 
-When tests fail during verification, classify each failure before reacting:
-
-- **Bad test** (stale fixture, drifted assertion, broken mock, outdated
-  snapshot) → fix in-session. Repairing the suite is part of the stride.
-- **Real production bug** surfaced by the test → park it via
-  `/agile-workflow:park` with a short repro. Do NOT silently fix mid-pass.
-  Once the suite is green, if the parked bug is small enough for a single
-  stride, pick it up immediately with `/agile-workflow:scope` → design →
-  implement. Larger bugs stay in backlog for prioritization.
-- **Pre-existing flake or unrelated regression** → park it. Don't bundle.
-
-NEVER game a test to make it pass. A failing test that documents *why* it
-fails (inline comment, `skip` linked to a backlog id, `xfail` with reason)
-is more honest than a green test that lies. No `expect(true).toBe(true)`,
-no asserting on whatever the code happens to return, no deleting a test
-as "flaky" without root-causing first.
+Follow the project's test-integrity rules and the worker posture in
+`../principles/references/subagents.md`: fix bad tests in-session, park real
+production bugs, and never game a test to make it pass.
 
-### Phase 9: Advance stage and commit
+### Phase 9: Commit and complete the lifecycle
 
 1. Edit the item's frontmatter: `stage: implementing → review`. PostToolUse hook
    bumps `updated:`.
-2. Commit:
+2. Commit the implementation:
    ```bash
    git add <changed-files> <test-files> .work/active/<kind>s/<id>.md
    git commit -m "implement: <id>"
    ```
+3. Unless the caller explicitly requested `stop-at-review` (including "stop at
+   review", "leave at review", or "hand off for review") or a project convention
+   sets that boundary, invoke `/agile-workflow:review <id>` in the same invocation
+   and forward the effective `review_weight`. The review lane owns its required
+   context and verdict:
+   - approve: advance and commit `review → done`
+   - bounce: record `## Review findings`, return the item to `implementing`, and
+     report the bounce
+   - blocker: record `## Blocker` and report it without claiming completion
+
+A weight of `none` skips independent review, but the review lane still requires
+the same green verification and acceptance evidence before administrative
+closure. Reaching `review` remains a real lifecycle transition; continuing
+through it never means silently self-approving. With `stop-at-review`, finish
+Phase 9 after the implementation commit and report that explicit boundary.
 
 ## Output
 
 In conversation:
-- **Implemented**: `<id>` advanced to `stage: review`
+- **Implemented**: `<id>` advanced to `stage: done`, `stage: review` by explicit
+  override, or `stage: implementing` after a documented bounce
+- **Review**: lane verdict, limitation, or blocker
 - **Files changed**: list
 - **Tests added**: list
+- **Execution capability**: choice and rationale
+- **Review weight**: effective value and source
 - **Discrepancies from design**: list (or "none")
 - **Adjacent issues parked**: backlog ids (or "none")
-- **Next**: `/agile-workflow:review <id>` to evaluate the change
 
 ## Guardrails
 
@@ -279,10 +298,12 @@ In conversation:
   When they disagree, adapt the implementation, document the why.
 - Implement fully or report a blocker. NEVER leave TODO comments or `unimplemented!`.
 - Don't add unrequested features. Adapt to repo reality freely; expand scope never.
-- Don't advance past `review` — that's `/agile-workflow:review`'s job.
+- Do not self-approve at `review`; invoke the review lane and honor its verdict.
 - If you discover a genuine design flaw, don't muscle through. Append a
   `## Implementation discovery` section, set stage back to `drafting`, and
   return. The design family will pick it up on the next pass.
-- Adjacent issues you notice get parked via `/agile-workflow:park`, not bundled.
-- Test integrity is non-negotiable. Fix bad tests in-session; park real
-  production bugs; never make a test pass just to make it pass.
+- Safe, cohesive simplification in the touched area belongs in the task. Park
+  larger, unrelated, or behavior-changing opportunities instead of silently
+  expanding scope.
+- Test integrity is non-negotiable: follow the project rules and worker posture;
+  fix bad tests, park real production bugs, and never game tests.