@nklisch/pi-agile-workflow 0.15.3

package/skills/deep-code-scan/references/lane-catalog.md

@@ -0,0 +1,129 @@
+# Lane Catalog — what each lane reuses
+
+A **lane** is a scan domain the user selected at kickoff; it becomes a feature. Each lane points at
+**existing reference knowledge** the scanners load (so this skill never re-derives pattern catalogs)
+and at the **standalone alternative** — the specialist skill to run *instead of* a campaign when the
+user only needs that one domain. **In-campaign, lanes are references-only**; do not invoke the
+specialist skills mid-campaign (most mint/commit their own items and would bypass the gauntlet).
+Paths are relative to the repo's plugin root (`plugins/`).
+
+## The lanes
+
+### correctness
+- **References (scanner load):** `agile-workflow/skills/bug-scan/references/` — the 8 domains:
+  `concurrency-races.md`, `async-promises.md`, `state-closures.md`, `resource-leaks.md`,
+  `time-numbers.md`, `error-handling.md`, `data-layer.md`, `language-footguns.md`.
+- **Per-altitude fan-out:** split scanners by `bug-domain × component`. Use bug-scan's own relevance
+  test (Phase 2) to skip domains a component can't have (no async → no async scanner).
+- **Standalone alternative:** `/agile-workflow:bug-scan <path>`.
+
+### tests
+- **References (scanner method):** `agile-workflow/skills/gate-tests` — derive *expected* coverage
+  from behavior / acceptance criteria / public contracts (NOT from the implementation), map existing
+  test coverage, and find the deltas. Reuse its priority rubric (Critical = acceptance criterion with
+  no test; High = boundary/error case with no test; Medium = valid partition/rule combo with no test;
+  Low = complementary coverage).
+- **What this lane hunts (broader than the release gate):** *test gaps* (uncovered behavior, edges,
+  error paths), *bad tests* (asserting on implementation not behavior, weak/empty assertions,
+  over-mocking, tautological `expect(true)`), *test issues* (stale fixtures, broken/leaky mocks,
+  flaky/timing-dependent tests, order-dependence), and *test improvements* (missing harness, property
+  or fuzz opportunities, e2e coverage). For e2e program work specifically, hand off to
+  `/agile-workflow:e2e-test-design`.
+- **Altitude:** `module → subsystem → system`. Tests are assessed against a component's behavior, so
+  there is rarely a leaf-level test-scan story worth minting.
+- **Spec-source hierarchy + finding shape.** Unlike `gate-tests` (which reads a bound item's
+  acceptance criteria), a campaign tests-scanner often has no bound spec. Derive *expected* behavior
+  in this order: acceptance criteria of a related item → public contract / signatures / docstrings →
+  observable behavior inferred from the code. **If no spec source exists at all, emit a
+  documentation/spec gap, NOT an implementation-derived "test gap"** (a test asserting whatever the
+  code happens to do is the bad-test failure mode this lane hunts). The tests-lane finding records the
+  *missing/weak test and the expected behavior + its source*, not "offending code" — the generic
+  scanner evidence field doesn't fit "no test exists", so describe the uncovered contract instead.
+- **Intent-lens note:** respect the project's test-integrity rules (a `skip`/`xfail` linked to a
+  backlog id documenting a real bug is *honest*, not a gap — do not "fix" it into a green lie).
+- **Standalone alternative:** `/agile-workflow:gate-tests`.
+
+### performance
+- **References:** `agile-workflow/skills/perf-scout/references/` — the 11 lenses (algorithmic,
+  memory/data-locality, parallelism/vectorization, gpu, caching, io/batching, distributed,
+  game-engine/realtime, database-internals, compiler/runtime, approximation) plus `idea-ranking.md`
+  and `peer-review-pass.md`.
+- **Note:** perf findings are *speculative ideas*, ranked, not severities-as-bugs. Carry perf-scout's
+  ranking tiers into the finding severity and lean on its peer-review-pass — it dovetails with the
+  review gauntlet.
+- **Standalone alternative:** `/agile-workflow:perf-scout <path>`.
+
+### quality / holistic
+- **References:** `code-audit/skills/repo-eval/references/` — the 9 dimensions + scoring rubric +
+  verification-checks.
+- **Note:** this lane *scores*, it doesn't only list findings. Best at the `subsystem`/`system`
+  bands where holistic judgment applies; weak at `leaf`. Often run as one or two high-altitude
+  stories rather than a full leaf→system spine.
+- **Standalone alternative:** `/code-audit:repo-eval <path>`.
+
+### structure / refactor
+- **References:** `agile-workflow/skills/refactor-design` discovery heuristics + any project
+  `.agents/skills/refactor-conventions/`.
+- **Hard intent guard:** the **black-box test** applies — a finding here must be behavior-preserving.
+  And documented deliberate patterns (`.agents/skills/patterns/`) are *not* refactor findings. This
+  lane is the most prone to goal-fighting fixes; the gauntlet's Intent lens is non-optional for it.
+- **Standalone alternative:** `/agile-workflow:refactor-design <path>`.
+
+### architecture / bold-refactor
+- **References (scanner load):** `agile-workflow/skills/bold-refactor` — the conceptual lenses
+  (elimination, unification, inversion, algebraic, declarative, domain crystallization) plus its
+  "Beneath you: generic LLM refactoring" anti-pattern list. This lane finds **bold reconceptions**
+  ("what single idea would make half this code unnecessary?"), not cleanups.
+- **Altitude:** `subsystem` and `system` ONLY — a reconception needs a whole subsystem in view;
+  there is no leaf-level bold refactor. Usually one or two high-altitude stories.
+- **Highest goal-fighting risk of any lane.** Bold reconceptions are by nature "you've been doing
+  this wrong" proposals — exactly the findings most likely to fight a deliberate design philosophy.
+  The gauntlet's **Intent lens is mandatory and strict here**: a reconception that contradicts a
+  documented pattern (`.agents/skills/patterns/`) or stated architecture is a *contested* finding for
+  a human, never an auto-emitted fix. Use bold-refactor's anti-pattern list in reverse too — reject
+  timid extractions masquerading as bold findings.
+- **Do NOT invoke `bold-refactor` in-campaign.** It materializes and commits its own `[refactor]`
+  epic — which would bypass this campaign's gauntlet (the very gate this highest-risk lane needs most)
+  and create an epic competing with `fix-<goal>`. In-campaign, load its lenses + anti-pattern list as
+  scanner knowledge only; every architecture finding flows through Gate 1/Gate 2 and emits solely via
+  `fix-<goal>`. `/agile-workflow:bold-refactor` is the **standalone alternative** — run it *instead of*
+  a campaign when the user wants a pure architectural pass and is fine with its own epic + flow.
+
+### security
+- **References:** the security domains `gate-security` selects (auth, injection, secrets, deps, API,
+  infra, crypto, data-protection, error-handling). Reuse its audit method.
+- **Standalone alternative:** `/agile-workflow:gate-security` (gate-scoped) or a scoped
+  security scanner brief.
+
+### custom (free-form goal)
+- **References:** none prebuilt. Build a bespoke scanner brief from the user's goal — name the
+  concrete signal to hunt ("every site that spawns a task without awaiting/cancelling it"), give
+  detection heuristics, and require in-context confirmation like every other lane.
+- **Specialist:** none — this is the case the campaign uniquely serves.
+
+## Choosing a lane's story spine
+
+Not every lane wants the full `leaf → module → subsystem → system` spine:
+
+- **correctness / security** — full spine; bugs and vulns live at every altitude.
+- **tests** — `module → subsystem → system`; coverage is judged against component behavior.
+- **performance** — usually `module → subsystem → system`; single-line leaf micro-opts rarely earn a
+  story (let perf-scout handle those directly).
+- **quality / holistic** — `subsystem → system` only; holistic scoring needs altitude.
+- **structure / refactor** — `leaf → module` mostly; cross-cutting refactors are rare and risky.
+- **architecture / bold** — `subsystem → system` only; reconceptions need altitude, and the lane is
+  the highest-risk for goal-fighting fixes.
+
+Confirm the per-lane spine at the Phase 3 checkpoint — it's part of the plan the user approves.
+
+## In-campaign: always fan out (never invoke the specialist)
+
+In a campaign, scanning is **always** the scoped sub-agent fan-out that loads the lane's references.
+Do **not** call the specialist skill mid-campaign, even when one component feels like "just run
+repo-eval here." The specialists mint/commit their own `.work/` items and run their own (non-gauntlet)
+flows — invoking them would create items outside `fix-<goal>` and skip the Reality/Context/Intent
+gauntlet that every campaign finding must clear. The specialist column is the **standalone
+alternative**: what the user runs *instead of* a campaign when one domain is all they need.
+
+Never paste a specialist's pattern catalog into this skill or a scanner brief inline — point at the
+reference file. The catalogs are maintained in their home skills; reuse keeps them single-sourced.

package/skills/deep-code-scan/references/review-gauntlet.md

@@ -0,0 +1,108 @@
+# The Review Gauntlet — multi-round adversarial culling before any fix ships
+
+Auto-generated scan findings have three characteristic failure modes, and **all three produce
+"fixes" that are worse than leaving the code alone**:
+
+1. **False positives** — the finding isn't real. A misread, a theoretical case that can't occur, or
+   something already handled elsewhere.
+2. **Context-ignorant fixes** — the finding is locally real but the proposed remediation ignores the
+   broader system: it breaks an invariant a caller relies on, duplicates an existing abstraction, or
+   "fixes" a symptom whose cause lives elsewhere.
+3. **Goal-fighting fixes** — the worst kind. The "fix" undoes a *deliberate* design choice. It
+   swaps the repo's hand-rolled, dependency-free parser for a library the project intentionally
+   avoids; it adds `thiserror` to a codebase whose convention is hand-written `Display`; it
+   "hardens" a fail-open probe that is fail-open *on purpose*. These regress the project while
+   looking like diligence.
+
+The gauntlet exists to kill all three **before findings become fix items, and again on the drafted
+fix epic**. It is iterative on purpose — one pass rationalizes; several passes in fresh context
+converge on what's actually true.
+
+## The three lenses (every round applies all of them at `rigor ≥ standard`)
+
+- **Reality** — *Is this a real problem that can actually occur here?* Re-read the cited code in
+  context. Reject theoretical-only, defensive-only-with-no-trigger, and already-mitigated findings.
+- **Context** — *Does the fix respect the broader system?* Check the finding's `fix locality`
+  against callers, invariants, and existing abstractions. A `local` fix that violates a `module`- or
+  `cross-cutting`-level contract is rejected or escalated to the right altitude.
+- **Intent** — *Does the finding or its fix fight the repo's actual goals?* Cross-check against the
+  project's stated intent and deliberate choices:
+  - `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md` (or the project's foundation docs)
+  - `.work/CONVENTIONS.md` (tag taxonomy, design conventions)
+  - `.agents/skills/patterns/` and `.agents/rules/` — **documented deliberate patterns are not
+    findings**; a finding that contradicts a catalogued pattern is rejected unless it shows the
+    pattern itself is being misapplied.
+  - In-code comments that explain *why* (an explicit "intentionally fail-open" / "no deps by
+    design" comment is binding intent, not an oversight).
+
+  A finding that survives Reality and Context but fails Intent is **dropped with a note**, not
+  emitted — and the note feeds back so future scanners learn the boundary.
+
+## The loop
+
+Run rounds until convergence or the rigor cap. **Independence is everything** — each round must be
+genuinely fresh, or it just agrees with itself.
+
+1. **Round 1 — cross-model cull.** Hand the full finding set (with evidence + the project intent
+   sources above) to an independent reviewer, per agile-workflow's **advisory-review policy**: when a
+   *different* model class is available, use `peeragent` (pre-approved for cross-review); otherwise
+   fall back to a fresh-context same-harness sub-agent. The cross-model path is preferred but
+   **optional** — the gauntlet degrades to fresh-context review, never skips. For a deep or complex
+   campaign where two model classes are available, use **two distinct classes** — the first pass in
+   the advisory/completeness posture (is the finding set complete, anything missed?), the next in the
+   adversarial posture (which findings don't hold up?). Class selection and peer flags live in
+   [../../principles/references/models.md](../../principles/references/models.md). Either way the
+   reviewer scores every finding `keep | revise | drop` on all three lenses, with a one-line reason
+   each, and the ledger (below) is written regardless of which path ran.
+2. **Apply.** Drop the rejects. Revise the salvageable (often: re-scope the fix to the right
+   altitude, or soften "replace X" to "the real issue is Y"). Record every drop + reason in the
+   campaign ledger — dropped findings are evidence the gauntlet worked, not waste.
+3. **Round 2 — fresh-context re-review of survivors.** A *new* reviewer (different model again where
+   possible, no memory of round 1) reviews only the survivors. Does it still agree? New objections?
+   New drops/revisions restart the convergence check.
+4. **Repeat** until a round produces **no new drops or revisions** (converged) or the cap is hit:
+   - `rigor: floor` → 1 combined pass (Reality lens minimum).
+   - `rigor: standard` → ≥ 2 rounds, all three lenses, cross-model.
+   - `rigor: full` → rounds until convergence, cap 4, all three lenses, cross-model, fresh context
+     each round.
+5. **Persistent dissent → advisory, not forced.** A finding that keeps drawing objections across
+   rounds without resolving does **not** get forced into the fix epic. Demote it to an advisory note
+   on the scan epic ("flagged but contested — needs human judgment") so a person decides, rather
+   than shipping a fix the reviewers couldn't agree was correct.
+
+## Two gates, same gauntlet
+
+- **Gate 1 — pre-consolidation** (end of Phase 4 / start of Phase 5): the raw finding set runs the
+  gauntlet so consolidation clusters only survivors.
+- **Gate 2 — the drafted fix epic** (end of Phase 5, before emission): the *clustered plan* runs one
+  more gauntlet pass. Reviewers need a concrete artifact, so consolidation first persists a
+  **fix-epic draft packet** at `.work/scan-artifacts/scan-<goal>/fix-draft.md` — hand that path to
+  the reviewer. Clustering can introduce new context/intent problems (a feature that bundles three
+  findings may, as written, fight a goal none of the three did alone). The fix epic is materialized
+  into real `.work/` items **only after the packet passes**. After the durable `.work/` items and
+  campaign record are written, the artifact root is deleted.
+
+### Gate 2 verdict schema (per cluster)
+
+Gate 2 reviews *clusters*, not raw findings, so it gets a verdict vocabulary to match. For each
+proposed fix feature the reviewer returns one of:
+
+- **keep** — cluster and its sequencing are sound.
+- **revise** — keep the cluster, but the body/scope/Intent-constraints need the listed edits.
+- **split** — the cluster bundles findings that don't share a remedy; break it into the named
+  sub-clusters.
+- **drop** — the cluster shouldn't be fix work at all (its findings failed re-review on Reality/Intent
+  at the plan level; demote to advisory).
+
+Each verdict carries its lens reason(s) and, for `revise`/`split`, the **required edits**.
+**Convergence = a pass where no cluster needs `revise`/`split`/`drop`** (all `keep`), or the rigor
+cap. Apply the edits to the packet between rounds; the packet — not your memory — is the artifact
+that converges.
+
+## What lands in the ledger
+
+For auditability, the scan epic body records, per round: how many findings entered, how many were
+dropped and why (by lens), how many revised, and the convergence outcome. The point of the gauntlet
+is partly the surviving fixes and partly the **documented reasons** the rejected ones didn't make
+it — that record is what keeps the next campaign (and the human reading it) from re-litigating the
+same non-issues.

package/skills/deep-code-scan/references/scanner-brief.md

@@ -0,0 +1,152 @@
+# Scanner Dispatch — brief template, model diversity, finding schema
+
+Scanners are the workers of an altitude story. Use a generic sub-agent prompted with the scanner posture from `../../principles/references/subagents.md`. They are **source-read-only**, **scoped to one component**, and **armed with the lane's
+references**. Their only writes are their assigned artifact files. The orchestrator never re-does
+their work.
+
+## Model diversity (the "different models in parallel" rule)
+
+The lane's **scanner tier is locked at plan time** (the kickoff dial, recorded in the lane feature
+body). Read it and honor it; the guidance below is what each tier means, with `mixed` as the
+default. Whatever the scanner tier, the cross-model **gauntlet** (Verification) still runs on a
+*different* class — independence there is non-negotiable.
+
+Single-model fan-out gives single-model blind spots, so the default `mixed`
+tier spreads the wave across the host's available model classes or reasoning
+settings. Use stronger reviewer reasoning on dense, subtle, high-altitude, or
+high-risk components; use the capable default for smaller leaf components and
+high-volume waves. The `codex-high` and `codex-xhigh` tiers map directly to
+Codex high and extra-high reasoning; other hosts should map those tiers to
+their closest source-read-only reviewer/scanner settings.
+
+The cross-model **adversarial** pass (Verification, `rigor ≥ standard`) should run on a *different*
+model class than the bulk of the scanners — that is where `peeragent` fits, and it is pre-approved
+for cross-review.
+
+## Dispatch rules
+
+- All component-scanners for one altitude band go out in **one message** (parallel).
+- Each scanner is scoped to **its component's file list only**, plus the **inherited findings** from
+  the band below (so wider scans reason about interactions, not re-find leaf bugs).
+- If a scanner errors, record it as a coverage gap in the story body — do not blind-retry.
+- If a scanner returns >25 findings, ask it to keep the top 25 by severity; a flood
+  usually means pattern over-matching.
+- Scanners may write only their assigned artifact files under `.work/scan-artifacts/scan-<goal>/`.
+  They must not edit source files, `.work/active/` items, shared manifests, or another scanner's
+  paths.
+
+## Scanner brief template
+
+> You are a **source-read-only scanner agent** for the **<lane>** lane at the **<band>** altitude.
+> Follow the agile-workflow scanner contract: scoped inspection, caller-authorized artifacts only,
+> no fixes, and no recursive sub-agents.
+>
+> **Scan goal (the campaign north star):** <goal — verbatim from the user>
+> Everything you report must serve this goal. A finding outside the goal is noise.
+>
+> **Reference(s) — load FIRST and apply their named patterns:**
+> <absolute paths from the lane catalog, e.g. bug-scan/references/concurrency-races.md>
+>
+> **Scope — scan ONLY these files:**
+> ```
+> <component file list>
+> ```
+>
+> **Artifact paths — write ONLY these files:**
+> - raw packet: `.work/scan-artifacts/scan-<goal>/raw/<lane>/<band>/<component>.md`
+> - candidate findings: `.work/scan-artifacts/scan-<goal>/candidates/<lane>/<band>/<component>.jsonl`
+> - status: `.work/scan-artifacts/scan-<goal>/status/<lane>/<band>/<component>.json`
+>
+> **Inherited findings from the band below (reason about interactions; don't re-report these):**
+> ```
+> <file:line + one-line summary pairs, or "none — this is the leaf band">
+> ```
+>
+> **Stack profile:** <languages, frameworks, relevant primitives>
+>
+> **Method:**
+> 1. Load the reference(s); note the patterns and detection signals relevant to the goal.
+> 2. (If the lane calls for it) web-search 1–3 times for current pitfalls for this stack/version.
+> 3. Apply the detection signals to the scope. Read every flagged site — **confirm in context**.
+>    Grep hits alone are not findings.
+> 4. Consider how your component interacts with the inherited findings (a leaf bug may compose into
+>    a module-level hazard worth its own, higher-severity finding).
+>
+> **For each confirmed finding, return:**
+> - **Title** (one line)
+> - **Lane / Band**: <lane> / <band>
+> - **Pattern**: named pattern from the reference, or "new"
+> - **Severity**: Critical | High | Medium | Low (rubric below)
+> - **Location**: `file:line`
+> - **Evidence**: 1–5 lines of the offending code, fenced
+> - **Why it matters** (1–2 sentences — the specific failure mode, tied to the goal)
+> - **Remediation direction** (a direction, not a finished fix)
+> - **Fix locality**: `local` (single site) | `module` (one component) | `cross-cutting` (spans
+>   components) — this feeds consolidation clustering.
+>
+> **Rules:** cite `file:line` for every finding; confirm in context; don't fabricate (empty is
+> valid and honest); don't implement fixes; stay in scope; skip anything in the inherited list.
+>
+> **Write artifacts, then return only status:**
+> 1. Write the raw packet markdown to the assigned raw packet path. The packet starts with
+>    `## <lane>/<band> — <component>`, then the findings, then a `## Summary` line.
+> 2. Write candidate findings as JSONL to the assigned candidate path. Use one JSON object per
+>    confirmed finding; write an empty file if there are no findings.
+> 3. Write the status JSON to the assigned status path, including counts and `status: "ok"` or
+>    `status: "error"`.
+> 4. Return one terse line in chat: `wrote <raw> <candidates> <status>`.
+
+**Lane-specific schemas override the generic fields above.** The `tests` lane is the notable case:
+"Evidence" as *offending code* doesn't fit a *missing* test. A tests-lane finding instead records:
+- **Title** · **Lane/Band** · **Severity** (gate-tests rubric) · **Location** (the under-tested
+  `file:line` / public symbol) · **Expected behavior + its source** (acceptance criterion / contract
+  / docstring — or "no spec source → this is a documentation/spec gap, not a test gap") ·
+  **What's missing or wrong** (no test / weak assertion / over-mock / stale fixture / flake) ·
+  **Suggested test** (direction) · **Fix locality**. See `lane-catalog.md` → tests.
+
+## Severity rubric (shared across lanes)
+
+| Severity | Meaning |
+|---|---|
+| Critical | Will cause data loss/corruption/hang/wrong outcome (or, for non-correctness lanes, the lane's equivalent severe failure) under realistic conditions. Must fix. |
+| High | Incorrect behavior, crash, or serious degradation under uncommon-but-real conditions. Must fix. |
+| Medium | Real issue, hard to trigger or limited blast radius. Should fix; deferrable with acknowledgement. |
+| Low | Edge case, latent, defensive-only. Backlog-grade. |
+| Info | Not a finding. Do not return Info entries. |
+
+Non-correctness lanes reuse the same five tiers with the lane's meaning of "severe" (a perf
+finding's Critical is a dominant hot path; a security finding's Critical is actively exploitable —
+defer to the specialist reference's own rubric where it has one).
+
+## Recording findings durably
+
+Per band, do a **spot-check only** — you (the orchestrator), with full context, re-read the cited
+code for each finding, drop grep-only or fabricated ones, and dedupe within the band. **Do not run
+the multi-round cross-model gauntlet per band** — that fires once at Gate 1, after every lane/band
+has scanned (see Verification in SKILL.md). Running it per band would multiply cost and converge on
+local context the wider bands haven't seen yet.
+
+Use the artifact ledger in `artifact-ledger.md`:
+
+1. Preallocate unique raw, candidate, and status paths for each scanner before dispatch.
+2. After the wave, verify every expected status file exists.
+3. Build or refresh the manifest from the per-scanner status files.
+4. Spot-check from the saved raw packet and candidate JSONL.
+5. Write accepted findings to `accepted/<lane>/<band>.jsonl`.
+6. Write the compact inheritance input to `rollups/<lane>/<band>.md`.
+7. Write the summary into the altitude story body under `## Findings`, grouped by severity, with
+   links to the raw packet(s) and rollup.
+
+Low findings stay under their own advisory heading — not minted as backlog stubs. Advance the story
+`implementing → review → done` once its band is scanned, spot-checked, and its artifact rollup is
+written.
+
+### Rolling findings up to the next band
+
+The orchestrator reads `rollups/<lane>/<band-below>.md` between bands (scanner agents are stateless) and
+injects only the relevant subset into each next-band scanner's brief. The roll-up is
+**deterministic by explicit component membership** (defined in the component map — file sets +
+parent edges, see `decomposition.md`), not naive path prefix: a band-N component's inherited set =
+every confirmed band-(N-1) finding whose `file` is in a child component's file set. A finding in a
+file shared by two parents rolls up to **both**; a finding owned by no single higher component goes
+to the **cross-cutting bucket** the `system` band always inherits — so nothing is silently dropped.