@nklisch/pi-agile-workflow 0.15.3

package/skills/gate-tests/SKILL.md

@@ -0,0 +1,367 @@
+---
+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
+  .work/active/. Auto-triggers during /agile-workflow:release-deploy.
+---
+
+# Gate-Tests
+
+You orchestrate a test-quality gate over the items bound to a release. The
+actual analysis runs inside a **deep test 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 gaps it returns into
+items in the substrate.
+
+Scanner strength is explicit: spawn exactly one source-read-only deep test
+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
+only for broad cross-feature releases, complex state machines,
+concurrency-heavy behavior, or repeated test-quality misses. If the host has no
+scanner path, run the analysis inline and record the reduced isolation
+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.
+
+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.
+
+## Trigger
+
+- `/agile-workflow:release-deploy` invokes during `quality-gate` stage
+- User can invoke manually: `/agile-workflow:gate-tests <release-version>`
+
+## Workflow
+
+### Phase 1: Identify the bundle
+
+```bash
+# Bound non-release items. `--release` auto-widens to ALL tiers (active + archive + releases).
+# Include late-bound archived stubs; their bodies may be pruned, but their item id is still
+# present and can recover the bundle commits/files. Ignore only the release orchestration item.
+.work/bin/work-view --release <version> --paths | while IFS= read -r item; do
+  kind=$(grep -m1 '^kind:' "$item" | awk '{print $2}')
+  [ "$kind" = "release" ] && continue
+  echo "$item"
+done > /tmp/bundle-items-<version>.txt
+```
+
+If the bundle-items file is empty, halt: "No items bound to release `<version>`."
+
+Build the union of files changed by the bundle. For archived stubs, the body is pruned on disk by
+design; use the item id to find implementation commits instead of treating the missing body as a
+skip reason:
+
+```bash
+while IFS= read -r item; do
+  id=$(grep -m1 '^id:' "$item" | awk '{print $2}')
+  git log --grep "$id" --format='%H' | xargs -I{} git diff-tree --no-commit-id --name-only -r {}
+done < /tmp/bundle-items-<version>.txt | sort -u > /tmp/bundle-files-<version>.txt
+```
+
+### Phase 2: Read existing gate items (idempotency prep)
+
+```bash
+.work/bin/work-view --release <version> --gate tests --paths
+```
+
+Capture already-tracked findings to feed into the scanner brief.
+
+### Phase 3: Dispatch the test-coverage scanner
+
+Spawn ONE source-read-only deep scanner agent with the full analysis brief. Use
+a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md` and the strongest
+inspection/reviewer setting the host exposes, escalating for broad cross-feature
+releases, complex state machines, concurrency-heavy behavior, or repeated
+test-quality misses. If scanner agents are unavailable, run the analysis
+inline and record the reduced isolation in the release body. The scanner
+extracts behavioral contracts from item bodies, maps existing tests, applies
+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.
+>
+> Use read/search/shell tools as needed. Do not spawn nested sub-agents or implement
+> fixes.
+>
+> **Bundle scope** (files changed by the bundle):
+> ```
+> <bundle-files>
+> ```
+>
+> **Bound items** (read each item's body for the spec; an archived stub's
+> body is pruned on disk — hydrate it from the stub's `git_ref` frontmatter
+> via `git show <git_ref>:<path>`, trying the item's former `.work/active/`
+> path at that ref):
+> `<bound-item-ids>`
+>
+> **Already-tracked findings to skip**:
+> ```
+> <already-tracked>
+> ```
+>
+> **Methodology**:
+>
+> 1. **Extract the behavioral contract per item.** For each bound item, read
+>    its body and decompose along four axes:
+>
+>    **Input space:**
+>    - All parameters, types, valid ranges and partitions
+>    - Invalid inputs the spec says should be rejected or handled
+>    - Optional vs required
+>    - Edge values: empty, zero, null, max, min
+>
+>    **Output space:**
+>    - All return types and variants
+>    - Error/exception conditions the spec defines
+>    - Side effects the spec promises (or prohibits)
+>
+>    **State space (where applicable):**
+>    - All valid states
+>    - All valid transitions
+>    - Invalid transitions the spec rejects
+>
+>    **Business rules:**
+>    - Conditions and combinations producing different outcomes
+>    - Priority rules when multiple conditions apply
+>
+>    Then extract:
+>    - Acceptance criteria (look for `## Acceptance Criteria`,
+>      `## Acceptance`, or `- [ ]` checklist items)
+>    - Implementation units / unit names
+>    - Public interface surface (functions, types, endpoints exposed)
+>
+>    These four axes plus the explicit acceptance criteria form the spec.
+>
+> 2. **Map existing test 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.
+>
+> 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
+>    - **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]`):
+>    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
+>       expected behavior?
+>    3. Unavailable dependency — when a downstream dep (DB, API, queue) is
+>       unreachable, what's expected? (Retry? Fail fast? Degraded mode?)
+>    4. Boundary values — at the limits of input ranges, what's the
+>       contract?
+>    5. Concurrent / race conditions — for items with shared state, what's
+>       the contract under concurrency?
+>    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.
+>
+> 5. **Map e2e seams.** For items with `depends_on` chains, check whether
+>    the seam between them is tested:
+>    - Does an integration or e2e test exercise the path from item A's
+>      output through item B's input?
+>    - Are real conditions used (real DB instance, real HTTP, real
+>      filesystem in temp) rather than mocks of mocks?
+>
+>    For features with multiple child stories, check that the parent
+>    feature's overall acceptance criteria are e2e-covered, not just
+>    per-story unit-covered.
+>
+> 6. **Classify gaps**:
+>    | 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 |
+>
+>    Also flag tautological tests found during step 2 — they need rework or
+>    deletion.
+>
+> **Output format** — return a single markdown document with:
+>
+> ```
+> ## 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
+> - **Suggested test**:
+>   ```<lang>
+>   // Sketch of the test — name, scenario, assertion target.
+>   ```
+> - **Test location (suggested)**: `<test-file-path>`
+>
+> ### Finding 2
+> ...
+> ```
+>
+> Followed by:
+>
+> ```
+> ## Audit summary
+> - Items with extracted contracts: <count>
+> - Existing tests mapped: <count>
+> - Tautological tests flagged: <count>
+> - Findings by priority: Critical=<n>, High=<n>, Medium=<n>, Low=<n>
+> ```
+>
+> **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.
+> - Skip already-tracked.
+>
+> **Test integrity findings** (additional pass — flag and surface as
+> Critical findings):
+> - Tests that make themselves pass without verifying behavior:
+>   `expect(true).toBe(true)`, asserting on the literal return of the
+>   function under test, `assert 1 == 1`, tautological mock-on-mock
+>   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 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.
+>
+> When you flag a test-integrity finding, also identify whether a real
+> production bug was being silenced. If so, surface BOTH the integrity
+> finding and the underlying-bug finding.
+
+### Phase 4: Convert findings to items
+
+For each finding the scanner returned:
+
+Read `gate_finding_routing` from `.work/CONVENTIONS.md` before writing items.
+If absent, use the default routing below. Normalize test priority to routing
+keys as: `Critical -> critical`, `High -> high`, `Medium -> medium`, and
+`Low -> low`. If a normalized key maps to `skip`, do not emit an item for that
+finding; include the skipped count in the gate output. If it maps to `backlog`,
+write a `.work/backlog/` item instead of an active story.
+
+```yaml
+---
+id: gate-tests-<short-slug>
+kind: story
+stage: implementing       # critical/high
+                          # OR drafting for medium
+tags: [testing]
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: tests
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <one-line description: spec condition not covered>
+
+## Priority
+Critical | High | Medium | Low
+
+## Spec reference
+Item: `<bound-item-id>`
+Acceptance criterion: <quote the criterion>
+
+## Gap type
+<missing test for valid partition / boundary / error case / etc.>
+
+## Suggested test
+\`\`\`<lang>
+// Sketch of the test — name, scenario, assertion target.
+\`\`\`
+
+## Test location (suggested)
+`<test-file-path>` (following project conventions)
+```
+
+Default priority -> placement mapping:
+- **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
+- **Medium** → `stage: drafting` in `.work/active/stories/`
+- **Low** → backlog file in `.work/backlog/` (not stage-managed)
+
+Tautological tests get items too:
+
+```yaml
+# 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).
+```
+
+### Phase 5: Commit
+
+```bash
+git add .work/active/stories/ .work/backlog/
+git commit -m "gate-tests: <N> coverage gaps for <version>"
+```
+
+## Output
+
+In conversation:
+- **Bundle**: `<version>` — `<N>` items audited
+- **Coverage gaps**: count by priority
+- **Tautological tests flagged**: count
+- **Items created**: count, with new ids
+- **Already-tracked**: count of duplicates skipped
+
+## Guardrails
+
+- **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.
+- 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.
+- **Test-integrity is a first-class concern of this gate.** A test that
+  was made to pass instead of made to fail honestly is worse than a
+  missing test — it lies to every future reviewer. Surface those as
+  Critical findings even when nominal coverage looks complete.

package/skills/groom/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: groom
+description: >
+  Backlog hygiene sweep for the agile-workflow substrate. Use when the user asks to groom the
+  backlog, audit backlog hygiene, find stale/dead/duplicate/superseded backlog items, or clean up
+  .work/backlog/. Triggers on "groom the backlog", "backlog hygiene", "find stale items", "what's
+  dead in the backlog", "any duplicates in the backlog". Reads .work/backlog/, classifies items
+  (DONE / SUPERSEDED / DUPLICATE / STALE / MERGEABLE / VALID) from date/metadata signals plus a
+  grounded semantic pass, and writes a triage REPORT of proposals. Propose-not-prune: it never
+  auto-archives, merges, or deletes — every disposition is operator-confirmed per finding, and dead
+  items route through the project's terminal-tier retention convention. Opt-in and inert when not
+  invoked; the staleness face is additionally inert unless backlog_staleness_days is configured.
+---
+
+# Groom
+
+You audit the project's `.work/backlog/` tier for hygiene problems and produce a **triage report
+of proposals** — never silent mutation. Backlogs accrete entropy: items finish elsewhere, later
+work supersedes them, duplicates pile up, and parked ideas go stale. Grooming surfaces that for a
+human; it does not prune on its own.
+
+This is a **user-invocable sweep, not a release gate.** The backlog has no release binding, so
+grooming is not part of `gates_for_release` / `release-deploy`. It borrows the gates'
+item-producer discipline (produce findings, never mutate silently) and is structured like `park` /
+`scope` (operates on `.work/`, verifies substrate first).
+
+## When to invoke
+
+Auto-trigger on hygiene phrases: "groom the backlog", "backlog hygiene", "audit the backlog",
+"find stale / dead / duplicate / superseded items", "what's dead in the backlog", "clean up the
+backlog". If the user wants to *add* an idea, that is `park`; if they want to *promote* one, that
+is `scope`. Groom is for auditing what is already parked.
+
+## Core discipline (load-bearing)
+
+- **Propose-not-prune.** Every non-VALID classification is a *proposal*. You write a report; you
+  apply a disposition only after explicit per-finding operator confirmation. Archive / merge /
+  delete are never automatic.
+- **Ground every claim.** Mechanical findings name the signal that fired (age, missing field, a
+  cited id that is now `done`). Semantic findings (DUPLICATE / SUPERSEDED / MERGEABLE) must quote
+  the overlapping text from both items — no classification without a citation. Uncertain → propose
+  as a question, never assert. This is the anti-fabrication floor: do not claim "superseded"
+  without the grounding a reader could check.
+- **Inherit disposition; don't re-decide it.** Confirmed DONE / SUPERSEDED items are disposed
+  through the project's **terminal-tier retention** convention (read it from
+  `.work/CONVENTIONS.md`), not a policy this skill invents.
+- **No imposed cadence.** Groom runs when invoked. A deployment may schedule a recurring sweep,
+  but the skill neither assumes nor requires continuous operation.
+
+## Workflow
+
+### Phase 1: Verify substrate
+
+Confirm `.work/CONVENTIONS.md` exists in the project (walk up from CWD). If not, halt:
+> "No agile-workflow substrate found. Run `/agile-workflow:convert` to bootstrap, then retry."
+
+Read from `.work/CONVENTIONS.md`: the **Terminal-tier retention** value (`delete-refs` default /
+`retain-bodies`) and whether `backlog_staleness_days` is set.
+
+### Phase 2: Mechanical pass (cheap, deterministic)
+
+These signals need no judgment. For each, record the item id + the signal that fired.
+
+1. **STALE (age).** Run `.work/bin/work-view --stale`. This lists backlog items whose last-touched
+   date — `updated` if present, else `created` — exceeds `backlog_staleness_days`. If the key is
+   absent, `--stale` reports itself inert; note "staleness face inert (no `backlog_staleness_days`
+   configured)" in the report and continue with the other checks. Do not invent a threshold.
+2. **Missing-field.** Flag backlog items missing a required field (`id`, `created`, `tags`) — a
+   malformed capture worth a human look.
+3. **Cites-done-work.** Scan each backlog item body for references to a feature/release/story id;
+   cross-check with `work-view` whether that id is now `stage: done` (or shipped). **The check must
+   span the terminal tiers** (`archive/`, `releases/`) where completed work usually lives — miss
+   them and this check misses exactly the shipped/archived work it exists to catch. On the Rust
+   `work-view` binary the active+backlog default hides those tiers, so widen with `--scope all`
+   (e.g. `work-view --scope all --stage done`); the bash fallback (`work-view.sh`) does not accept
+   `--scope` and already queries all tiers by default, so run it without the flag. An item whose
+   premise cites already-completed work is a **DONE candidate** — flag it with the cited id.
+
+Mechanical findings are higher-confidence; still proposals, never auto-applied.
+
+### Phase 3: Semantic pass (grounded; default on, skippable)
+
+Dispatch **one read-only deep sub-agent** over the backlog item bodies to propose:
+
+- **DUPLICATE** — two items expressing the same intent.
+- **SUPERSEDED** — a later item (or landed work) obsoletes an earlier one.
+- **MERGEABLE / CLUSTER** — N items that are really one epic/feature.
+
+The sub-agent prompt MUST use the host's generic/general-purpose subagent path
+and carry the grounding requirement verbatim: *every proposed classification
+quotes the overlapping text from each item involved; no classification without a
+citation; uncertain pairings are surfaced as questions, not assertions.* If no
+generic subagent adapter is available, run the pass inline and record the
+reduced isolation in the report.
+
+The user may skip this pass ("groom, mechanical only") — then report STALE / missing-field /
+cites-done only.
+
+### Phase 4: Write the triage report
+
+Write `groom-report-<date>.md` to the project's scratchpad tier — a transient location, NEVER
+`.work/backlog/` (that would add items to the backlog this sweep exists to shrink). Resolve the
+destination in this order: use `.work/scratch/` if it exists, else `.memory/scratchpad/` if it
+exists, else emit the report inline in conversation and write no file. For each finding:
+
+```
+<CLASSIFICATION>  <item-id>   — <signal / grounding>
+  e.g. STALE       idea-foo    — 180d since last-touched (threshold 90)
+       DONE?       idea-bar    — cites feature-baz, now stage:done
+       DUPLICATE   idea-x ~ idea-y — both describe <quoted overlap from each>
+       SUPERSEDED  idea-old    — by idea-new: "<quote>" vs "<quote>"
+       MERGEABLE   idea-a,b,c  — one epic: <shared theme + quotes>
+```
+
+VALID items are not listed individually (a count suffices) — the report is the exception set.
+
+### Phase 5: Per-finding confirmation and disposition
+
+For each non-VALID finding, ask the operator before acting. Nothing moves without confirmation.
+
+- **DONE / SUPERSEDED (confirmed)** → dispose through **terminal-tier retention**: under
+  `delete-refs`, archive as a bodyless stub; under `retain-bodies`, archive with body kept. (This
+  is the same terminal disposition the review skill uses — honor the project's value, do not
+  re-decide close-vs-archive.) For SUPERSEDED, first fold any unique detail into the superseding
+  item.
+- **DUPLICATE (confirmed)** → fold unique detail into the kept item, then dispose the absorbed one
+  per the same convention.
+- **MERGEABLE (confirmed)** → this is a `scope` act: hand off to `/agile-workflow:scope` to cluster
+  the items into one epic/feature, rather than mutating inline.
+- **STALE (confirmed dead)** → treat as DONE/SUPERSEDED disposition; **STALE but still wanted** →
+  leave in place (touching it bumps `updated`, resetting the staleness clock — which is correct: a
+  human reaffirmed it).
+- **Declined** → leave the item untouched; optionally note the reaffirmation.
+
+Commit only the dispositions the operator confirmed:
+
+```bash
+git add .work/  # the archived stubs / merged items actually changed
+git commit -m "groom: <N> items disposed (<counts by class>)"
+```
+
+## Output
+
+In conversation:
+- **Report**: path (or inline) + counts by classification.
+- **Confirmed**: items disposed and how (archived / merged / handed to scope).
+- **Left**: stale-but-reaffirmed and declined counts.
+- **Next**: `/agile-workflow:scope` for any MERGEABLE clusters the operator wants promoted.
+
+## Guardrails
+
+- **Never auto-prune.** No archive / merge / delete without per-finding confirmation. A report with
+  zero confirmed dispositions is a valid, complete run.
+- **Never fabricate a supersession or duplicate claim.** Semantic findings without quoted grounding
+  do not get written. "I'm not sure these are duplicates — confirm?" is correct; asserting it is not.
+- **Don't add items to the backlog.** The report is transient; it never becomes a `.work/backlog/`
+  file. Grooming reduces entropy, it does not produce more items to triage.
+- **Don't re-decide terminal disposition.** Inherit `Terminal-tier retention`; an unrecognized
+  value defaults to keeping the body (safe) with a warning, exactly as the release/review paths do.
+- **Don't impose a cadence.** Invocation-driven; schedulability is a deployment choice.
+- **Inert without opt-in.** The staleness face requires `backlog_staleness_days`; absent, it
+  reports inert and the other faces still run. The skill as a whole is a no-op unless invoked.

package/skills/groom/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Groom"
+  short_description: "Audit backlog hygiene — find stale, dead, duplicate, superseded items"
+  default_prompt: "Use $groom to audit the backlog for stale, dead, duplicate, and superseded items."
+policy:
+  allow_implicit_invocation: true