@nklisch/pi-agile-workflow 0.15.3

package/skills/deep-code-scan/references/artifact-ledger.md

@@ -0,0 +1,148 @@
+# Artifact Ledger — temporary durable scanner output and rollups
+
+The artifact ledger prevents context loss during large scan campaigns. Scanner output can exceed the
+orchestrator's context budget; the filesystem is the source of truth while the campaign is running.
+It is **not** a permanent deliverable. After the final scan summary, fix epic, resolved finding
+index, and gauntlet ledgers are collated, remove the artifact root.
+
+## Root And Lifecycle
+
+Create the root before Phase 4:
+
+```text
+.work/scan-artifacts/scan-<goal>/
+  manifest.jsonl
+  raw/<lane>/<band>/<component-slug>.md
+  candidates/<lane>/<band>/<component-slug>.jsonl
+  status/<lane>/<band>/<component-slug>.json
+  accepted/<lane>/<band>.jsonl
+  rollups/<lane>/<band>.md
+  gate1-input.md
+  gate1-ledger.md
+  fix-draft.md
+  gate2-ledger.md
+```
+
+Use stable lowercase slugs for components. If two components slug the same, prefix with the story's
+component index: `003-parser.md`.
+
+The repo should ignore `.work/scan-artifacts/`. Do not force-add it. These files are local recovery
+state, not release artifacts.
+
+Lifecycle:
+
+1. Create the root before scanner fan-out.
+2. Let scanners write their assigned raw/candidate/status files.
+3. Collate accepted findings, rollups, Gate 1/Gate 2 inputs, and ledgers from those files.
+4. Copy the durable summary into `.work/` scan/fix item bodies:
+   - scan epic campaign record
+   - altitude story findings and coverage gaps
+   - fix epic audit summary
+   - fix epic resolved finding index
+   - fix feature/story finding citations and gauntlet constraints
+5. Delete `.work/scan-artifacts/scan-<goal>/`.
+6. Commit only the collated `.work` item updates. The final git tree should not keep raw scanner
+   packets.
+
+## Write Order
+
+1. Before dispatch, the orchestrator creates the directories and assigns each scanner unique
+   `raw`, `candidates`, and `status` paths.
+2. Each scanner writes only those assigned files and returns one terse chat line naming them.
+3. No scanner writes `manifest.jsonl`, story bodies, rollups, gate packets, source files, or another
+   scanner's paths.
+4. At the band checkpoint, the orchestrator verifies every expected `status` file exists.
+5. The orchestrator rebuilds or appends `manifest.jsonl` from status files; no concurrent appends.
+6. The orchestrator spot-checks candidate findings from disk, not from chat.
+7. Accepted findings go to `accepted/<lane>/<band>.jsonl`; inheritance summaries go to
+   `rollups/<lane>/<band>.md`.
+8. Link raw packet directories, accepted findings, and rollups from the altitude story body.
+9. For long-running campaigns, commit after each completed altitude story or approved checkpoint,
+   but commit only collated `.work` item updates. Do not force-add `.work/scan-artifacts/`.
+
+If context compacts, resume by reading `manifest.jsonl`, the current altitude story body, and the
+needed `rollups/` files. Do not ask scanners to regenerate packets that already exist.
+
+## Status And Manifest Schema
+
+Each scanner writes one status file:
+
+```json
+{"scan":"scan-goal","lane":"correctness","band":"leaf","component":"parser","story":"scan-goal-correctness-leaf","status":"ok","raw_packet":".work/scan-artifacts/scan-goal/raw/correctness/leaf/parser.md","candidates":".work/scan-artifacts/scan-goal/candidates/correctness/leaf/parser.jsonl","counts":{"critical":0,"high":2,"medium":1,"low":0},"coverage_gap":false}
+```
+
+Use `status: "error"` and `coverage_gap: true` for scanner failures; include a short `error` string
+and still write the status file. The orchestrator writes `manifest.jsonl` from these status files at
+the checkpoint. Missing status files are coverage gaps too; record them in the story body and
+manifest with `status: "missing"`.
+
+## Raw Packets
+
+Raw packets are scanner-authored markdown with a short metadata header:
+
+```markdown
+---
+scan: scan-<goal>
+lane: <lane>
+band: <band>
+component: <component-slug>
+story: scan-<goal>-<lane>-<band>
+status: ok
+---
+
+# Raw scanner packet: <lane>/<band>/<component>
+
+<scanner output verbatim>
+```
+
+Do not edit scanner prose after writing it. Corrections belong in accepted findings and gauntlet
+ledgers so the raw record remains auditable.
+
+## Candidate And Accepted Findings
+
+Each scanner writes candidate findings to its assigned `candidates/.../<component>.jsonl`. One JSON
+object per finding; write an empty file for no findings:
+
+```json
+{"fingerprint":"src/parser.rs:42|correctness|null-handling","severity":"High","lane":"correctness","band":"leaf","component":"parser","location":"src/parser.rs:42","title":"Parser accepts empty owner","fix_locality":"local","raw_packet":"raw/correctness/leaf/parser.md","rationale":"Confirmed by reading the branch that bypasses owner validation."}
+```
+
+The fingerprint is the idempotency key for in-campaign dedupe. The orchestrator writes
+spot-checked survivors to `accepted/<lane>/<band>.jsonl`, preserving `raw_packet` and adding
+`accepted_by: "orchestrator-spot-check"` plus any drop reason for rejected candidates in the gate or
+campaign ledger.
+
+## Rollups
+
+`rollups/<lane>/<band>.md` is the compact input for the next altitude band:
+
+- counts by severity
+- accepted finding fingerprints
+- `file:line` + title + one-line rationale
+- inherited parent/cross-cutting bucket assignment
+- coverage gaps
+
+The next band receives the relevant rollup excerpt, not every raw packet.
+
+## Gate Packets
+
+Before Gate 1, concatenate accepted findings into `gate1-input.md` with links to raw packets and
+rollups. Reviewers get that path. After each round, write `gate1-ledger.md`.
+
+Before Gate 2, write the proposed fix epic and child item bodies to `fix-draft.md`. Reviewers get
+that path. After each round, write `gate2-ledger.md`.
+
+## Cleanup Gate
+
+Do not delete the artifact root until all of these are true:
+
+- `fix-<goal>` exists or the user explicitly declined fix emission.
+- The scan epic's `## Campaign record` includes counts by lane/severity, coverage gaps, contested
+  findings, gauntlet outcomes, and whether a fix epic was emitted.
+- The fix epic's `## Audit summary` and `## Resolved finding index` contain the survivors that drove
+  the remediation plan.
+- Each emitted fix feature/story cites the findings it resolves and the relevant gauntlet
+  constraints.
+
+Then delete `.work/scan-artifacts/scan-<goal>/`. If the campaign is abandoned before collation,
+either resume and collate first or ask the user before deleting the only raw evidence.

package/skills/deep-code-scan/references/consolidation.md

@@ -0,0 +1,91 @@
+# Consolidation — turning findings into one intelligent fix epic
+
+The deliverable is **one coherent remediation plan**, not a backlog flooded with one stub per
+finding. A whole-codebase campaign can surface hundreds of findings; emitted raw, they're
+unusable — duplicative, unsequenced, and impossible to prioritize. Consolidation is the step that
+makes the campaign worth running.
+
+This runs **after the pre-consolidation review gauntlet** (see
+[review-gauntlet.md](review-gauntlet.md)) — you cluster only survivors, and the drafted fix epic
+gets one more gauntlet pass before emission.
+
+## Step 1 — collect and dedupe
+
+Gather every surviving finding from the artifact ledger's accepted findings and Gate 1 ledger, using
+the altitude story bodies as the human-readable index. Dedupe by `file:line`:
+- Same location flagged by two lanes → keep the higher severity, note "also flagged by: <lane>".
+- A leaf finding subsumed by a module finding (the wider one's fix resolves the narrow one) → keep
+  the wider, reference the narrower.
+
+## Step 2 — cluster (the intelligence)
+
+Group findings into **fix units** along whichever axis yields the most coherent, lowest-churn work.
+Pick per cluster, don't force one axis on everything:
+
+- **By fix locality** — `cross-cutting` findings that share a root cause become *one* feature (e.g.
+  "introduce a cancellation-aware task helper and adopt it" resolves 14 scattered findings). This is
+  the highest-value clustering: many findings, one well-designed change.
+- **By component** — several findings in one module become one "harden `<module>`" feature, so the
+  fixer holds the module's context once instead of context-switching 6 times.
+- **By theme / pattern** — all instances of one named anti-pattern become one feature with a
+  consistent remedy, so the fix is applied uniformly (and could seed a new `patterns/` entry).
+- **Standalone** — a genuinely isolated Critical stays its own story; don't bundle it just to bundle.
+
+A file or root cause with 5+ findings is almost always *one* "rework this" unit, not five stories —
+mirror bug-scan's clustering instinct, scaled to the campaign.
+
+## Step 3 — shape the fix epic
+
+```
+EPIC  fix-<goal>            kind: epic, scan_origin: scan-<goal>, release_binding: null
+ ├─ FEATURE <cluster-1>     one fix unit; tag carries the lane(s) it resolves
+ │   ├─ STORY ...           concrete, single-stride fixes
+ │   └─ STORY ...
+ └─ FEATURE <cluster-2>
+```
+
+- **Sequence with `depends_on`:** a shared-abstraction feature (the helper everything adopts) lands
+  *before* the adopt-it features that depend on it. Foundational clusters first.
+- **Severity drives stage, not the gauntlet:** Critical/High/Medium clusters → features at
+  `stage: drafting`, ready to design. (Findings already passed the gauntlet; staging is about
+  urgency, not confidence.) **Low findings do NOT become fix items at all** — they stay as advisory
+  notes in the scan epic / story bodies. Minting a backlog stub per Low finding is exactly the flood
+  this skill exists to avoid; if the user wants to action one later, they elevate it via
+  `/agile-workflow:scope`.
+- **Every fix item carries `scan_origin: scan-<goal>`** so the remediation traces back to the audit,
+  and `tags:` reflect the lane(s) + the project taxonomy (route a behavior-preserving cluster
+  `[refactor]`, a perf cluster `[perf]`, etc., so downstream design routing is correct).
+- **Each feature body cites its findings:** the `file:line` list it resolves, the cluster rationale,
+  and the gauntlet verdict. This is the grounding that lets `feature-design` design the fix without
+  re-discovering the problem.
+
+## Step 4 — gauntlet the plan, then emit (operator-confirmed)
+
+Gate 2 needs a **concrete artifact** to review, not an idea in your head. Persist the proposed plan
+as a **fix-epic draft packet** before reviewing it: write the would-be epic + every cluster
+feature/story (frontmatter + bodies + the `file:line` lists each resolves) to
+`.work/scan-artifacts/scan-<goal>/fix-draft.md`. Hand *that path* to the Gate 2 gauntlet reviewers so
+a fresh-context, cross-model pass can judge the clustered plan (does it, as written, still pass
+Reality / Context / Intent? did clustering bundle a finding into a feature that now fights a goal?).
+See [review-gauntlet.md](review-gauntlet.md).
+
+Once the packet clears Gate 2, **present it and ask before writing the real items** — like
+`research-handoff`, never an auto-flood:
+
+> "<N> findings survived review → <M> fix features (<k> foundational, sequenced). Top clusters:
+> … . Emit `fix-<goal>` now?"
+
+On confirmation, materialize the packet into real `.work/` items (epic + features/stories, each with
+`scan_origin: scan-<goal>`) and commit:
+`deep-code-scan: emit fix epic for <goal> (<N> findings -> <M> features)`.
+
+After emission and the scan epic campaign record are updated, delete
+`.work/scan-artifacts/scan-<goal>/`. The emitted `.work/` items are the durable record; the artifact
+root is in-flight scratch space.
+
+## What the user gets back
+
+A single epic they can hand straight to `/agile-workflow:autopilot --scope fix-<goal>` or reprioritize
+via `/agile-workflow:scope` — sequenced, deduped, gauntlet-hardened, and traceable to the audit.
+That is the whole point of the campaign: not "here are 300 things", but "here is the organized,
+vetted work, in the order it should happen."

package/skills/deep-code-scan/references/decomposition.md

@@ -0,0 +1,127 @@
+# Codebase Decomposition — building the altitude component map
+
+The map is the campaign's spine: `band → [components]`, where every component is a concrete,
+scannable scope. Get this right and every scanner downstream is tight and non-overlapping; get it
+wrong and you either drown leaf scanners in the whole repo or miss whole regions.
+
+## The default altitude bands
+
+| Band | Grain | What a component is | Typical count |
+|---|---|---|---|
+| `leaf` | functions / single files | one source file or a tight cluster of hot functions | tens–hundreds |
+| `module` | directories / packages | a cohesive dir, package, or namespace | tens |
+| `subsystem` | bounded contexts | a feature area / service / layer that spans dirs | a handful |
+| `system` | cross-cutting / whole repo | the repo as one unit; cross-component concerns | 1 |
+
+Trim or rename to fit. A single-file library is just `file → repo`. A monorepo may add a
+`package` band between `module` and `subsystem`. Confirm the bands at kickoff (Phase 1).
+
+## Why small→large, and how findings flow up
+
+Leaf scans are cheap, parallel, and precise — run them first. Each wider band then **inherits the
+findings recorded by the band below it**, so a module scanner already knows "these three files have
+stale-closure issues" and can reason about *interactions* between them rather than re-finding the
+leaf bugs. System-level scanners focus purely on cross-cutting concerns (global invariants,
+end-to-end data flow, architectural seams) because the local issues are already logged below.
+
+This is why the altitude stories are `depends_on`-chained leaf→system: it is not just ordering, it
+is information flow.
+
+**The roll-up is deterministic by explicit component membership** (sub-agents are stateless, so the
+orchestrator carries findings between bands). Naive path-prefix ownership breaks on real codebases —
+a "CLI pipeline" subsystem spans several directories; a shared util belongs to two parents. So the
+component map must carry, per component, an **explicit file set** and **parent-component edges** (not
+just a directory glob). Then:
+
+- a band-N component inherits every confirmed band-(N-1) finding whose `file` is in its file set;
+- a finding may roll up to **multiple** parents (shared files), deterministically ordered by the
+  component map's declared order;
+- a finding owned by no single higher component lands in an explicit **cross-cutting bucket** that the
+  `system` band always inherits, so nothing is silently dropped.
+
+(Same rule referenced in `scanner-brief.md`.)
+
+## Detecting component boundaries
+
+Use cheap structural signals before reading code. Prefer `ast-grep` for structure and `rg`/`git`
+for breadth.
+
+1. **Repo skeleton** — `git ls-files | sed 's#/[^/]*$##' | sort -u` for the directory set;
+   `tokei`/`cloc` or `git ls-files | xargs wc -l` for size, to find the dense regions worth their
+   own component.
+2. **Declared modules** — manifests and module systems: workspace members (`Cargo.toml`
+   `[workspace]`, `package.json` workspaces, `go.mod`), package boundaries (`__init__.py`,
+   `mod.rs`, `index.ts`, Go packages), namespaces.
+3. **Entry points** (seed the subsystem band) — route registrations, CLI mains, workers, cron,
+   webhook handlers, exported public API. Each entry point usually anchors a subsystem.
+4. **Dependency cues** — import/`use`/`require` density. Files that import each other heavily are
+   one component; a dir nothing imports is a leaf island. `ast-grep` import patterns or a quick
+   `rg '^(import|use|from|require)'` histogram surfaces the clusters.
+5. **Co-change cues** (optional, powerful) — `git log --format= --name-only | sort | uniq -c | sort -rn`
+   and pairwise co-change reveal de-facto modules that the directory tree hides.
+
+## Keeping the leaf set tractable
+
+The leaf band can explode. Bound it:
+
+- **Cap per parallel wave.** Group leaf components so each scanner gets a *batch* of related files,
+  not one file each — aim for a handful of scanners per module's worth of leaves, not one per file.
+- **Goal-filter early.** The scan `goal`/lane prunes irrelevant leaves: a correctness campaign skips
+  pure-config and generated files; a perf campaign skips cold setup code. Record what you skipped
+  and why — skipped scope is a reportable decision, not a silent gap.
+- **Respect the lane's relevance test.** Reuse the specialist's own Phase-1 logic (e.g. bug-scan's
+  domain relevance) to decide whether a leaf even warrants a given lane's scanner.
+
+## Agent budget (compute it, surface it, get it approved)
+
+The fan-out is roughly `components × (domains/lenses per lane)` summed over lanes and bands — and it
+**will** explode if left unbounded (eight bug domains over 300 leaf files = 2,400 scanner calls). The
+gauntlet adds more on top. The map is where you bound it. Before the Phase 3 checkpoint, compute and
+write into the epic body (this is the same "agent budget" contract stated in SKILL.md):
+
+- **max scanners per wave** (the parallel width of one band's fan-out),
+- **leaf batch size** (files per scanner — the main lever for collapsing the leaf count),
+- **estimated scanner calls**, **plus estimated verification/review calls** (Gate 1 + Gate 2 rounds,
+  and the `full`-rigor campaign evaluate — the gauntlet is not free),
+- **estimated total agent calls** (scanners + verification).
+
+If the total exceeds a sane threshold (rule of thumb: **>150 total agent calls or >20 scanners per
+wave**), surface it at the checkpoint so the user can narrow lanes, coarsen bands, raise the batch
+size, drop rigor, or accept the cost knowingly. The budget is part of what gets approved — a campaign
+that quietly spawns thousands of agents is a footgun, not a feature.
+
+## Large-repo dispatch
+
+For a big or polyglot repo, spawn **1–3 parallel exploratory sub-agents** to build the
+map, each owning a slice of the tree, each returning `band → [components]` with a one-line role per
+component and an approximate size. Merge their maps, dedupe overlaps at boundaries, and resolve any
+component claimed by two slices to the lower (more specific) band. For a small repo, build the map
+inline — don't pay for agents you don't need.
+
+## Output shape (what Phase 3 consumes)
+
+A single structured map. Each component carries an **explicit file set** (or globs that resolve to
+one) and its **parent edges**, so the roll-up is unambiguous — not just a label:
+
+```
+goal: correctness   lanes: [correctness, tests]   bands: [leaf, module, subsystem, system]
+
+leaf:
+  - args            files: [work-view/src/cli/args.rs]            parents: [substrate-layer, cli]
+  - query           files: [work-view/src/substrate/query.rs]     parents: [substrate-layer]
+  - board-view      files: [board/views/board.js]                 parents: [board-app]
+module:
+  - substrate-layer files: [work-view/src/substrate/**]           parents: [cli]
+  - board-app       files: [board/**]                             parents: []
+subsystem:
+  - cli             files: [work-view/src/**] (entry: main.rs)    parents: []   # spans dirs
+  - board-app       files: [board/**]                             parents: []
+system:
+  - repo            files: [**]   role: cross-cutting — error model, IO/time/rand seams + the
+                                   cross-cutting bucket (findings owned by no single component)
+```
+
+Note `args` rolls up to **two** parents (it's shared by the CLI and substrate layers) — that's why
+membership is explicit, not path-prefix. Write each band's component list (with file sets) into the
+matching altitude story body as that story's scan scope. The map — file sets, parent edges, and the
+scanner budget — is the artifact you present at the Phase 3 checkpoint; it is what the user approves.

package/skills/deep-code-scan/references/item-templates.md

@@ -0,0 +1,263 @@
+# Item Templates — scan scaffold + fix epic
+
+All items follow the agile-workflow active-tier schema (see `docs/SPEC.md`). Two kinds of structure:
+
+- **Scan scaffold** (`scan-<goal>` epic + lane features + altitude stories) — **engagement-owned
+  working state**. `deep-code-scan` creates it, drives it, and advances it to `done` *within the same
+  run*. It is not a queue for `autopilot` to drain (see the routing guardrail in SKILL.md).
+- **Artifact ledger** (`.work/scan-artifacts/scan-<goal>/`) — temporary scanner-written raw packets,
+  candidate findings, per-scanner status files, orchestrator-accepted rollups, and gauntlet inputs.
+  The scan scaffold links to it while the campaign is running; Phase 6 deletes it after the scan/fix
+  item bodies contain the collated durable record.
+- **Fix epic** (`fix-<goal>`) — the **durable deliverable**. Ordinary remediation work that plugs
+  straight into the normal design → implement → release machinery.
+
+## The `scan_origin` linkage field
+
+`scan_origin: <campaign-slug>` is a **first-class linkage field**, mirroring `research_origin` —
+queryable via `work-view --scan-origin <slug>`, inert (`null`/absent) when not set, no validation
+warning when omitted. It records the scan campaign that produced an item:
+
+- **Fix items** carry `scan_origin: scan-<goal>` so the remediation traces back to its audit, and
+  re-runs can dedupe against prior campaigns.
+- **Scan items** also carry it (`scan_origin: scan-<goal>`) for symmetry and single-query recall of
+  the whole scaffold; their `parent` chain already nests them under the epic.
+
+> **Paired scan-aware substrate (one rollout, modeled on `research_origin`).** This skill assumes a
+> substrate patch that ships alongside it:
+> 1. `scan_origin` in `docs/SPEC.md` + the `work-view` parser/model/filter + a `--scan-origin` flag + tests;
+> 2. `scan` / lane / band tags registered in `.work/CONVENTIONS.md`;
+> 3. **autopilot excludes `[scan]`-tagged items from its ready queue** — the structural guarantee the
+>    engagement-owned scaffold can't be misrouted to `implement-orchestrator`.
+>
+> Until that lands in a given install, `scan_origin` is inert (the parser ignores unknown frontmatter),
+> `grep -rl 'scan-<goal>' .work/` is the fallback query, and scan items are autopilot-grabbable — so
+> the Phase 0 preflight warns before creating them.
+
+## Canonical tags (slug-safe)
+
+Tags must be single kebab tokens — never display names with slashes/spaces ("quality / holistic").
+Scan items use the **scan-domain** tags below; fix items use the **project's** routing taxonomy
+(`.work/CONVENTIONS.md`) so design routing works.
+
+| Lane (display) | scan tag |
+|---|---|
+| correctness | `correctness` |
+| tests | `tests` |
+| performance | `performance` |
+| security | `security` |
+| quality / holistic | `quality` |
+| structure / refactor | `structure` |
+| architecture / bold | `architecture` |
+| custom | `custom` |
+
+Every scan item also carries the umbrella `scan` tag (the `[scan]` tag is the discriminator
+`autopilot` uses to skip the engagement-owned scaffold); stories add a band tag (`leaf` / `module` /
+`subsystem` / `system`). **Registering `scan` + the lane/band tags in `.work/CONVENTIONS.md` is a
+rollout prerequisite**, shipped with the paired substrate change — not an optional aside.
+
+**Fix items never carry `[scan]`.** They use the project's routing taxonomy so design routing works
+*and* so `autopilot` drains them normally — a fix item tagged `[scan]` would be skipped.
+
+---
+
+## Scan scaffold
+
+### Scan campaign epic — `.work/active/epics/scan-<goal>.md`
+
+```yaml
+---
+id: scan-<goal>
+kind: epic
+stage: drafting        # drafting at creation; -> implementing once the Phase 3 plan is approved;
+                       # -> done at end of the run (audit complete). NOT release-bound.
+tags: [scan, <lane-tags...>]
+parent: null
+depends_on: []
+release_binding: null  # a scan is an input/audit, never a release-bundle member
+gate_origin: null
+scan_origin: scan-<goal>   # self-anchor: the campaign id
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Scan campaign: <goal>
+
+## Goal
+<verbatim user goal — the north star every scanner serves>
+
+## Dials
+- lanes: [<lane>, ...]
+- rigor: floor | standard | full
+- altitude bands: [leaf, module, subsystem, system]
+
+## Agent budget   <!-- approved at the Phase 3 checkpoint -->
+- max scanners per wave: <n> · leaf batch size: <n files/scanner>
+- est. scanner calls: <n> · est. verification/review calls (Gate 1 + Gate 2 rounds, evaluate): <n>
+- **est. total agent calls: <n>**
+
+## Component map
+<the band -> [components] map from decomposition; this is what was approved at the checkpoint>
+
+## Artifact ledger
+- root: `.work/scan-artifacts/scan-<goal>/`
+- manifest: `.work/scan-artifacts/scan-<goal>/manifest.jsonl`
+- raw packets: `.work/scan-artifacts/scan-<goal>/raw/`
+- scanner candidates: `.work/scan-artifacts/scan-<goal>/candidates/`
+- scanner statuses: `.work/scan-artifacts/scan-<goal>/status/`
+- accepted findings: `.work/scan-artifacts/scan-<goal>/accepted/`
+- rollups: `.work/scan-artifacts/scan-<goal>/rollups/`
+- lifecycle: temporary; removed after final collation
+
+## Campaign record   <!-- filled at Phase 6; a done+unbound epic body is git-historical and may later
+                          be pruned to a stub, so the DURABLE summary also rides fix-<goal> -->
+- lanes run / components scanned / findings by severity
+- review gauntlet: rounds, dropped (by lens) + why, contested/advisory items (Low findings live here)
+- fix epic emitted: `fix-<goal>` (<M> features)
+- artifact cleanup: `.work/scan-artifacts/scan-<goal>/` removed after collation
+```
+
+### Lane feature — `.work/active/features/scan-<goal>-<lane>.md`
+
+```yaml
+---
+id: scan-<goal>-<lane>
+kind: feature
+stage: drafting        # -> implementing as its bands run; -> done when the lane is scanned
+tags: [scan, <lane>]
+parent: scan-<goal>
+depends_on: []         # lanes independent unless one informs another
+release_binding: null
+gate_origin: null
+scan_origin: scan-<goal>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Lane: <lane>
+
+## Scanner tier   <!-- LOCKED at plan time from the kickoff dial; binds this lane's fan-out -->
+opus | mixed | sonnet | codex-high | codex-xhigh
+
+## Reference knowledge
+<paths from lane-catalog.md this lane's scanners load>
+
+## Altitude spine
+<the bands this lane uses — may be a subset; see lane-catalog "story spine">
+```
+
+### Altitude story — `.work/active/stories/scan-<goal>-<lane>-<band>.md`
+
+```yaml
+---
+id: scan-<goal>-<lane>-<band>
+kind: story
+stage: implementing    # -> review -> done as the band is scanned + spot-checked
+tags: [scan, <lane>, <band>]
+parent: scan-<goal>-<lane>
+depends_on: [scan-<goal>-<lane>-<band-below>]   # leaf: [] ; module deps on leaf ; etc.
+release_binding: null
+gate_origin: null
+scan_origin: scan-<goal>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <lane> / <band>
+
+## Scope (components)
+<this band's component list from the map>
+
+## Inherited findings
+<file:line summaries rolled up from the band below by path ownership — or "leaf band, none">
+
+## Findings   <!-- written after the fan-out + per-band spot-check -->
+### Critical / High / Medium
+- `file:line` — <title> — fix locality: local|module|cross-cutting — <one line>
+### Low (advisory — stays here, NOT minted as backlog stubs)
+- `file:line` — <title> — <one line>
+
+## Artifact links
+- raw packets: `.work/scan-artifacts/scan-<goal>/raw/<lane>/<band>/`
+- scanner candidates: `.work/scan-artifacts/scan-<goal>/candidates/<lane>/<band>/`
+- scanner statuses: `.work/scan-artifacts/scan-<goal>/status/<lane>/<band>/`
+- accepted findings: `.work/scan-artifacts/scan-<goal>/accepted/<lane>/<band>.jsonl`
+- rollup: `.work/scan-artifacts/scan-<goal>/rollups/<lane>/<band>.md`
+
+## Coverage gaps
+<components/domains skipped + why, scanner errors>
+```
+
+---
+
+## Fix epic (the deliverable) — `.work/active/epics/fix-<goal>.md`
+
+Emitted operator-confirmed at Phase 5, after the draft packet clears gauntlet Gate 2.
+
+```yaml
+---
+id: fix-<goal>
+kind: epic
+stage: drafting        # ready for epic/feature design + autopilot — ordinary work from here
+tags: [<project taxonomy tags reflecting the clusters>]
+parent: null
+depends_on: []
+release_binding: null  # binds to a release later, via release-deploy, like any work
+gate_origin: null
+scan_origin: scan-<goal>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Remediation: <goal>
+
+**Source:** scan campaign `scan-<goal>` — <N> findings survived the review gauntlet.
+
+## Clusters
+<one line per fix feature: what it resolves, how many findings, why grouped>
+
+## Audit summary (durable)
+<finding counts by severity + lane; the persistent record, since the scan epic may be pruned>
+
+## Resolved finding index (durable — idempotency anchor)
+<every finding this campaign actioned, as `file:line — <slug>` fingerprints, one per line. Lives on
+the fix EPIC (not just child features) so re-runs match against one durable list even after the scan
+scaffold and fix children are archived/pruned.>
+```
+
+### Fix feature / fix story
+
+`.work/active/features/fix-<goal>-<cluster>.md` and `.work/active/stories/fix-<goal>-<cluster>-<n>.md`
+
+```yaml
+---
+id: fix-<goal>-<cluster>
+kind: feature                       # or story for a single-stride isolated fix
+stage: drafting
+tags: [<project routing tag: refactor / perf / bug / security / ...>]
+parent: fix-<goal>
+depends_on: [fix-<goal>-<foundational-cluster>]   # foundational clusters land first
+release_binding: null
+gate_origin: null
+scan_origin: scan-<goal>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# Fix: <cluster name>
+
+## Findings resolved
+- `file:line` — <title> (severity)
+
+## Cluster rationale
+<why these are one unit; the shared root cause or shared remedy>
+
+## Review gauntlet verdict
+<survived rounds; context/intent constraints the fix MUST respect — e.g.
+"keep the parser dependency-free per patterns/hand-rolled-peekable-flag-parser">
+```
+
+> **Routing matters.** Tag each fix cluster with the project taxonomy so agile-workflow routes its
+> design correctly: behavior-preserving cleanup → `[refactor]` (→ refactor-design), perf → `[perf]`
+> (→ perf-design), correctness/security → its domain tag (→ feature-design). The gauntlet's
+> Intent-lens constraints ride in the body so the designer can't undo a deliberate choice.