@nklisch/pi-agile-workflow 0.15.3

package/skills/convert/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Convert"
+  short_description: "Use Convert for repo workflows"
+  default_prompt: "Use $convert for this repository."
+policy:
+  allow_implicit_invocation: false

package/skills/convert/references/legacy-overlap-migration.md

@@ -0,0 +1,179 @@
+# Legacy & Overlap Migration
+
+Convert is **discovery-driven**, not a fixed checklist. Bespoke DIY skills,
+rules files, and plan-doc generators that predate the plugin are usually
+*convergence signals* — the project hand-rolled a concept the plugin now owns —
+not intentional divergence to preserve. This reference holds the detection
+sweep, the DIY→canonical mapping, the classification taxonomy, the
+reference-integrity rule, and the single-owner deferral table that the
+convert workflow points at.
+
+## Detection sweep
+
+Do not glob a hardcoded known-set. Enumerate both skill roots and the rules
+tree, then classify every entry:
+
+```bash
+ls -d .agents/skills/*/ 2>/dev/null
+ls -d .claude/skills/*/ 2>/dev/null
+ls .claude/rules/*.md 2>/dev/null
+```
+
+For each entry, read its `SKILL.md`/file header (name + description) and decide
+whether it mirrors a plugin-owned concept. Flag an **overlap candidate** when
+any of these hold:
+
+- The name or description mirrors a plugin-owned concept: patterns, refactor /
+  refactor-conventions, code conventions, cleanup / cruft, security review,
+  docs drift, test quality.
+- The skill instructs writing a **standalone plan doc** (e.g.
+  `docs/*-refactor-plan.md`, `docs/*-plan.md`, `docs/*-design.md` outside the
+  substrate). The plugin forbids plan docs — work lives in `.work/` items —
+  so any plan-doc generator is a convergence candidate regardless of name.
+- It is a **user-invocable command/skill superseded by a plugin gate** (e.g.
+  `/extract-patterns` → `gate-patterns`). A migration that retires a slash
+  command the user types must always be surfaced, never silently removed.
+
+## DIY → canonical mapping
+
+| Bespoke artifact shapes (examples) | Plugin concept | Canonical owner | Canonical destination |
+|---|---|---|---|
+| `extract-patterns`, bespoke `patterns` skill, structural-pattern content inside `.claude/rules/patterns.md` | reusable code patterns | `gate-patterns` (file/index *format*, Phase 4-5) — but convert *imports* verbatim, see below | `.agents/skills/patterns/` (+ optional `.claude/skills/patterns/` symlink mirror) |
+| `structural-refactor`, `stylistic-refactor`, bespoke `refactor-conventions`, any refactor-rule skill or `*-refactor-plan.md` generator | refactor conventions | `refactor-conventions-creator` (Phase 1, 5) | style rules → canonical instruction file `## Refactor Style Conventions`; detailed references → `.agents/skills/refactor-conventions/` (+ optional Claude mirror) |
+| project style / agent-rule prose in `.claude/rules/*` or a hand-rolled CLAUDE.md section | project agent rules | convert owns | `.agents/rules/<name>.md` (e.g. `project.md`) — a user-owned rules file the hook force-loads, OUTSIDE the plugin `agile-workflow:rules` markers; NOT the canonical instruction file |
+
+> **"Canonical instruction file"** throughout this reference = `AGENTS.md` in
+> the default `agents-canonical` model, or `CLAUDE.md` in a `claude-source`
+> repo. Convert resolves it in Phase 2.5 from `entrypoint_model`; never assume
+> it is literally `AGENTS.md`. **Legacy non-pattern rule prose does NOT route
+> here** — it routes to `.agents/rules/<name>.md`. The canonical instruction
+> file receives only the slim plugin-managed section, imported legacy Claude
+> *entrypoint* instructions, and confirmed refactor-style summaries.
+
+**Verbatim legacy-pattern import (convert-owned, NO discovery filter).**
+`gate-patterns` is a *discovery* writer: its sub-agent only emits patterns that
+recur 3+ times and explicitly defers legacy `.claude/rules/patterns.md` to
+convert. Routing legacy patterns "through gate-patterns Phase 1" would therefore
+silently drop single-use and two-use legacy patterns. Convert owns the lossless
+*import*: write each legacy structural-pattern block to
+`.agents/skills/patterns/<slug>.md` **verbatim**, in the gate-patterns Phase 4
+file format and Phase 5 index format, applying **no occurrence filter**.
+gate-patterns stays the discovery writer for NEW patterns in release bundles;
+convert imports EXISTING legacy ones.
+
+`.claude/rules/patterns.md` is **not** a single-destination file — build the
+block-level preservation manifest and classify its *content*: structural-pattern
+blocks go to `.agents/skills/patterns/` (via the verbatim importer above),
+rule-prose blocks go to `.agents/rules/<name>.md`, ambiguous blocks are preserved
+in place. Never dump the whole file into the canonical instruction file; that
+contradicts the layout convert itself advertises.
+
+## Classification taxonomy
+
+Classify each discovered skill-root entry into exactly one bucket:
+
+| Bucket | Shape | Action |
+|---|---|---|
+| `canonical` | Already at the plugin-canonical location in canonical form (e.g. `.agents/skills/patterns/`) | No action. |
+| `plugin-mirror-symlink` | `.claude/skills/<x>` is a symlink to the `.agents` canonical | Healthy compatibility mirror. Leave it (refresh the link only if dangling). |
+| `plugin-mirror-divergent-copy` | A skill that mirrors a plugin-owned concept where both `.agents` and `.claude` copies exist and differ, OR a `.claude`-only copy of a plugin-owned concept exists with no `.agents` source | Drift risk. Enters the `converge` set (alongside `bespoke`): reconcile unique content into `.agents`, then re-establish the mirror. Ask before discarding either side. |
+| `bespoke` | A DIY skill/rules file that **overlaps a plugin concept** (per the overlap-candidate rules) but lives outside the canonical layout (`structural-refactor`, `extract-patterns`, hand-rolled `patterns`) | Convergence candidate. Map via the table above and surface in the convergence question. |
+| `unrelated` | A project-specific skill that does **not** mirror any plugin-owned concept, isn't a plan-doc generator, and doesn't shadow a plugin command | Leave it untouched. Not a convergence candidate; report in the inventory but never offer it for convergence. |
+
+**Precedence — apply the overlap test FIRST.** Classification is gated on
+whether the entry mirrors a plugin-owned concept (per the overlap-candidate
+rules above). Only if it does can it be `canonical`, `plugin-mirror-symlink`,
+`plugin-mirror-divergent-copy`, or `bespoke`. A skill that does NOT mirror any
+plugin concept is `unrelated` and left untouched — even if it happens to live
+only in `.claude/skills/` with no `.agents` twin. A `.claude`-only skill is
+`plugin-mirror-divergent-copy` (a convergence candidate) **only** when it
+mirrors a plugin concept; otherwise it is just an `unrelated` Claude-only
+project skill. This stops convergence from swallowing legitimately Claude-only
+project skills.
+
+This repo's real-world shape included duplicated copies in **both** `.agents`
+and `.claude` (the `plugin-mirror-divergent-copy` case) — a fixed-path audit
+never looks for that. Diff actual contents; do not assume a single location.
+
+## Content integrity on move (mandatory, runs first)
+
+Reference integrity preserves *pointers*; content integrity preserves *content*.
+A path can be cleanly repointed (no dangling link) while the content it held is
+silently dropped — content integrity closes that hole, and it runs BEFORE
+reference integrity. Before ANY destructive op on a legacy artifact `P` —
+`git rm` / delete, `git mv` / move, replace-with-symlink, replace-with-shim,
+copy-over (overwriting bytes), managed-section overwrite (rewriting content
+between `<!-- ...:start/end -->` markers), or mirror replacement (overwriting or
+symlinking a `.claude` mirror):
+
+1. **Build the block-level preservation manifest** for `P` (Markdown-aware
+   blocks; see the convert SKILL Phase 1.8 manifest):
+   - YAML frontmatter is one block; each heading section is one block; fenced
+     code, tables, and lists are atomic (keep an intro line with the fence it
+     introduces); HTML marker regions are atomic; with no headings, group by
+     blank-line-separated paragraphs.
+2. **Classify and route each block:** `structural-pattern` →
+   `.agents/skills/patterns/` (verbatim importer, no filter); `rule-prose` →
+   `.agents/rules/<name>.md`; `ambiguous` → preserve in place.
+3. **Verify by provenance, not byte-hash** (destinations legitimately
+   reformat): write `sha256(normalized source block)` into the destination as a
+   trailing HTML comment (`<!-- agile-workflow:provenance src-sha256=<digest> -->`)
+   and confirm the destination holds (a) that digest and (b) the block's required
+   semantic anchors (pattern name/slug, or heading text + fenced payload). If no
+   trustworthy provenance can be written, the block is NOT landed — keep `P`.
+4. **Record a terminal state per block** — `landed_existing`,
+   `landed_this_run`, or `preserved_in_place` — idempotently; re-running convert
+   must never duplicate an already-landed block. `empty` files migrate nothing;
+   already-shimmed files are verified non-dangling and left; symlink loops /
+   dangling targets are `unsafe` and left in place.
+5. **Gate:** if any block is `ambiguous` / `unsafe` / unaccounted-for, do NOT
+   perform the destructive op — leave `P` and report it preserved-pending-review.
+   Content inside plugin-managed markers never counts as preserved user-content.
+6. **Atomic ordering** for `drift_user` / ambiguous content: **confirm → import
+   → verify → shim**. Never shim before a verified import.
+
+Only once content integrity passes do you proceed to reference integrity.
+
+## Reference integrity on move (mandatory, runs after content integrity)
+
+Relocating or removing a path dangles every inbound reference to it. Before ANY
+`git mv`, `git rm`, replace-with-symlink, or replace-with-shim of a path `P`
+(and after the content-integrity gate above has passed):
+
+1. **Grep the repo for inbound references:**
+   ```bash
+   grep -rIl --exclude-dir=.git -- "<P>" .
+   ```
+   Pay special attention to `.work/` item bodies and frontmatter, `docs/`,
+   the selected AGENTS target, CLAUDE entrypoints, and other skills.
+2. **If references exist, pick one per the user's cleanup intent:**
+   - **Rewrite** — repoint each reference to the new canonical path when that
+     path is stable and you can reach every referrer safely.
+   - **Redirect shim** — leave a short stub at `P` pointing to the new location
+     when references are numerous, live, or you cannot rewrite them all in this
+     pass. A shim is strictly better than a dangling pointer.
+3. **Never** move or remove `P` while live references point at it without doing
+   step 2.
+4. **Report** the outcome: path moved/removed, number of inbound references
+   found, action taken (rewritten / shimmed), and any references intentionally
+   left in place and why.
+
+This rule is unconditional — it applies even under `cleanup_scope:
+legacy-cleanup` and even for "obviously dead" paths. The grep is cheap; a
+silently broken `.work/` pointer is not.
+
+## Single-owner deferral
+
+Each plugin-owned concept has exactly one owning skill that defines its
+canonical location. Convert **places content** at those locations but does not
+re-author the rules for where they live — read the owner instead of carrying a
+divergent copy of the rule, so the layout has one source of truth.
+
+| Concept | Owner (read its phase) | Convert's job |
+|---|---|---|
+| reusable code patterns | `gate-patterns` (file/index *format*, Phase 4-5) | import legacy structural-pattern content verbatim into `.agents/skills/patterns/` (no occurrence filter); never invent a divergent location. gate-patterns discovers NEW patterns; convert imports EXISTING ones |
+| refactor conventions | `refactor-conventions-creator` Phase 1 & 5 | style rules → canonical instruction file `## Refactor Style Conventions`; detailed refs → `.agents/skills/refactor-conventions/` |
+| project agent rules | convert owns | `.agents/rules/<name>.md` (e.g. `project.md`), OUTSIDE the plugin `agile-workflow:rules` markers — NOT the canonical instruction file |
+
+When in doubt about a destination for a plugin-owned concept, defer to the
+owner's Phase 1 / "existing artifacts" section rather than convert's own prose.

package/skills/deep-code-scan/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: deep-code-scan
+description: >
+  Multi-lane, decomposition-first codebase scan campaign for agile-workflow. Use when the user asks
+  for a deep code scan, comprehensive audit, whole-repo issue hunt, or organized fix plan that spans
+  multiple lanes such as correctness, tests, performance, security, quality, structure, or
+  architecture. Interviews for goal, lanes, rigor, scanner tier, and altitude bands; maps the repo
+  from leaf to system scope; fans out scoped scanners; runs a review gauntlet; and consolidates
+  surviving findings into one fix epic. For a single-domain scan, route to the specialist instead.
+---
+
+# Deep Code Scan
+
+You orchestrate a **scan campaign**: a goal-driven, decomposition-first sweep of a codebase
+that starts at the smallest units and scopes outward, dispatches multi-model scanner agents
+(a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`) in parallel, verifies what they find,
+and returns an organized remediation plan instead of a
+pile of loose findings.
+
+This is the **campaign layer above** the depth scanners. It does not re-implement them. Its
+unique work is the four things none of the specialists do on their own:
+
+1. **Decomposition-first planning** — map the repo into altitude bands and turn that map into a
+   reviewable epic before any scanning tokens burn.
+2. **The small→large sweep** — scan leaves first, then let each wider altitude consume the
+   findings below it, so module- and system-level scanners are primed by what the leaves
+   revealed.
+3. **Temporary durable scan artifacts** — preallocate per-scanner artifact paths and require scanners
+   to write their own packets/findings there, so compaction cannot erase in-flight evidence; prune
+   those raw artifacts after the final summary and fix epic are collated.
+4. **Cross-model verification** — a different-model adversarial/peer pass over findings, so the
+   campaign's output is hardened, not just generated.
+5. **Intelligent fix bundling** — consolidate everything into one coherent fix epic clustered by
+   locality and theme, not 200 backlog stubs.
+
+## Composition, not replacement (read this before worrying about overlap)
+
+The depth specialists stay exactly where they are. In-campaign, `deep-code-scan` **only reuses their
+reference catalogs as scanner knowledge** — it does **not** invoke the specialist skills mid-campaign.
+Several of them mint and commit their own `.work/` items (bold-refactor commits epics, refactor-design
+emits stories, bug-scan gate-writes); invoking them in-campaign would bypass the gauntlet and create
+items outside `fix-<goal>`. The rightmost column is the **standalone alternative** — what to run
+*instead of* a campaign when the user only needs that one specialist:
+
+| Lane | Reuses (loaded as scanner knowledge) | Standalone alternative (instead of a campaign) |
+|---|---|---|
+| correctness | `bug-scan/references/*` (8 bug domains) | `/agile-workflow:bug-scan <path>` |
+| tests | `gate-tests` coverage analysis (bad tests, gaps, stale fixtures, weak assertions) | `/agile-workflow:gate-tests` |
+| performance | `perf-scout/references/*` (11 perf lenses) | `/agile-workflow:perf-scout <path>` |
+| quality / holistic | `code-audit/skills/repo-eval/references/*` (9 dimensions) | `/code-audit:repo-eval <path>` |
+| structure / refactor | `refactor-design` discovery heuristics | `/agile-workflow:refactor-design <path>` |
+| architecture / bold | `bold-refactor` conceptual lenses (elimination, unification, inversion, algebraic, declarative, domain crystallization) | `/agile-workflow:bold-refactor` |
+| security | `gate-security` audit domains | `/agile-workflow:gate-security` |
+| custom | a bespoke brief built from the user's goal | — |
+
+**When NOT to use this skill:** a **single-domain scan — even whole-repo** (just correctness, just
+tests, just perf, just security), a single directory, or a one-shot report. Those are exactly what
+the specialists are *for* (`bug-scan` already scans the whole repo for correctness, `gate-tests` for
+test gaps, etc.) — point the user at them. `deep-code-scan` earns its weight only when the scan
+**spans multiple lanes**, or is a **custom cross-cutting goal that genuinely needs the
+decompose → scan → gauntlet → consolidate campaign**. If the request is narrower, say so and route
+it to the specialist instead of spinning up a campaign.
+
+## The structure it builds
+
+```
+EPIC  scan-<goal>                          the campaign (goal encoded; engagement-owned scaffold)
+ ├─ FEATURE  scan-<goal>-correctness        a LANE (one selected domain/mode; locks its scanner tier)
+ │   ├─ STORY scan-<goal>-correctness-leaf       altitude: functions / single files   deps: []
+ │   ├─ STORY scan-<goal>-correctness-module     altitude: dirs / modules             deps: [leaf]
+ │   ├─ STORY scan-<goal>-correctness-subsystem  altitude: bounded contexts           deps: [module]
+ │   └─ STORY scan-<goal>-correctness-system     altitude: cross-cutting / whole repo deps: [subsystem]
+ ├─ FEATURE  scan-<goal>-performance         another lane (same altitude story spine)
+ └─ FEATURE  scan-<goal>-security            another lane
+        within each altitude story: fan out N parallel multi-model scanners
+        across that altitude's components; each scanner loads the lane's references.
+        later altitudes read the findings recorded by earlier ones.
+
+  ── then consolidation ──>
+
+EPIC  fix-<goal>                            the OUTPUT: one organized remediation plan
+ ├─ FEATURE clustered by locality/theme     (body cites Source: scan-<goal>)
+ └─ STORY   concrete fixes
+```
+
+- **Epic = the campaign** (one per goal). **Feature = a lane** (the user-selected domains/modes;
+  each locks its scanner tier). **Story = an altitude band**, `depends_on`-chained leaf→system so
+  the sweep is a visible, ordered structure and wider scans inherit narrower findings.
+- **Fan-out happens inside an altitude story**, across the components at that altitude — that is
+  where the parallel multi-model agents live.
+- The **scan scaffold is engagement-owned working state** ("we're looking") — `deep-code-scan`
+  creates it, drives it, and closes it to `done` within the same run; it is not a queue for
+  `autopilot`. The **fix epic is the durable deliverable** ("here's the organized work"), carrying
+  the audit summary that outlives the (prunable) scan epic. Keeping them separate mirrors
+  research → handoff.
+- The **scanner packets, candidate findings, and intermediate rollups are temporary durable working
+  artifacts** under `.work/scan-artifacts/scan-<goal>/`. Scanners write their own unique files there;
+  story/fix bodies carry the durable summaries. After Phase 6 collates the final record, remove the
+  artifact root so the git tree does not retain raw scan junk.
+
+## Dials (settle these WITH the user at kickoff — never silently)
+
+Five dials shape the campaign. Propose, discuss, settle — this is an interview, and a
+mispositioned dial costs the whole campaign.
+
+- **`goal`** — the campaign's north star, captured free-form from the conversation ("find every
+  place we drop cancellation", "all correctness risk", "everything"). Presets exist
+  (`all-issues`, `correctness`, `tests`, `security`, `performance`, `quality`) but the goal can be
+  any target the user names. It frames what counts as a finding and becomes the epic slug.
+- **`lanes`** — which scan lanes are in scope (the menu in the table above). The user's picks
+  *become the features*. `all-issues` selects correctness, tests, performance, security, quality, and
+  structure; **`architecture` (bold-refactor) is opt-in even under `all-issues`** — it's the
+  highest-risk, highest-review-cost lane, so the user adds it deliberately. A focused goal may select
+  one lane.
+- **`rigor`** — `floor` / `standard` / `full`, the verification depth (see Verification). Infer
+  from how load-bearing the output is; surface your inference.
+- **`scanner tier`** — which agent/model tier the scanner fan-out uses, **locked per lane** at plan
+  time (recorded in each lane feature's body, not frontmatter). One enum, used everywhere:
+  `opus | mixed | sonnet | codex-high | codex-xhigh | gemini | zai-high | zai-xhigh`. `mixed`
+  (default) gives model diversity — opus on dense/high-altitude components + sonnet on leaves,
+  drawing on the host's available classes; `opus`/`sonnet` pin one Claude model; `codex-high`/
+  `codex-xhigh` set Codex reasoning effort; `gemini` pins Gemini; `zai-high`/`zai-xhigh` set
+  Z.AI GLM 5.2 reasoning effort (model fixed `glm-5.2`). Offer it per lane or once for all. The
+  role→capability→model mapping and which classes count as distinct is in
+  [../principles/references/models.md](../principles/references/models.md). The choice binds that
+  lane's scanners; the cross-model gauntlet still uses a *different* class regardless, and for a
+  deep/complex campaign uses **two** different classes if available (advisory phase + adversarial
+  phase) — independence is non-negotiable.
+- **`altitude bands`** — the default sweep is `leaf → module → subsystem → system`. Trim or
+  rename to fit the repo (a tiny library may be just `file → repo`; a monorepo may add
+  `package`). The bands become each lane's story spine.
+
+## The walk
+
+### Phase 0 — Substrate check + scan-aware preflight
+`deep-code-scan` is substrate-first. If `.work/CONVENTIONS.md` is absent, stop and tell the user
+to run `/agile-workflow:convert` first — the campaign's whole output is substrate items. Do not
+fall back to a loose report; that is what standalone `bug-scan` is for.
+
+Then preflight the **paired scan-aware substrate** this skill assumes (all ship together with it):
+(1) the `scan_origin` field in SPEC + the `work-view --scan-origin` flag; (2) `scan` / lane / band
+tags registered in `.work/CONVENTIONS.md`; (3) **autopilot excludes `[scan]` items from its ready
+queue** — the structural guarantee the scaffold isn't misrouted. Probe cheaply (e.g.
+`work-view --scan-origin x` exits cleanly; CONVENTIONS lists the scan tags). **If the scan-aware
+substrate is missing, do not silently proceed** — warn that active scan items would be
+autopilot-grabbable on this install, and get explicit user acknowledgment (or have them land the
+paired feature first). This is a hard checkpoint, not a footnote.
+
+### Phase 1 — Kickoff interview (set the dials)
+Use the available structured question tool when the harness provides one; otherwise ask concise
+direct questions. Drive the conversation to settle `goal`, `lanes`, `rigor`, `scanner tier`, and
+`altitude bands`.
+Read enough of the repo first (languages, frameworks, top-level layout, entry points —
+`git ls-files`, manifests) to propose *grounded* lanes and bands, not generic ones. Confirm before
+proceeding.
+
+### Phase 2 — Decompose the codebase
+Build the **altitude component map**: for each band, the concrete list of components to scan.
+This is the skill's signature move — get it right and everything downstream is scoped cleanly.
+See [references/decomposition.md](references/decomposition.md) for the method (module-boundary
+detection, dependency-graph cues, `ast-grep` structural probes, how to keep the leaf set
+tractable). Spawn 1–3 parallel exploratory sub-agents for a large repo; do it inline
+for a small one. The output is a map: `band → [components]` with a one-line role per component.
+
+### Phase 3 — Write the scan plan (FIRST DELIVERABLE) + checkpoint
+Create the scan campaign epic, its lane features (each recording its locked scanner tier), and
+their altitude stories, using the frontmatter in
+[references/item-templates.md](references/item-templates.md). Wire `depends_on` leaf→system within
+each lane; lanes are independent (parallel) unless the user says one informs another. Write the
+component map into the relevant story bodies as their scope.
+
+Create the campaign artifact root before fan-out:
+`.work/scan-artifacts/scan-<goal>/`. Record that path in the scan epic body and initialize the
+directory structure described in [references/artifact-ledger.md](references/artifact-ledger.md).
+Before each scanner wave, preallocate one unique `raw`, `candidates`, and `status` path per scanner
+and include those paths in its brief. Treat this directory as durable **in-flight** campaign state:
+leave it untracked/ignored, reload from it after compaction or context reset, and delete it after
+final collation. Checkpoint commits include only the summaries copied into `.work` item bodies, not
+the ignored scanner artifact files.
+
+**Compute and record an agent budget.** The fan-out is `components × (domains per lane)` and can
+explode — eight bug domains across hundreds of leaf files is thousands of agent calls. Before the
+checkpoint, estimate and write into the epic body: max scanners per wave, leaf batch size (files per
+scanner), the total **scanner** calls, AND the **verification/review** calls the rigor dial implies
+(Gate 1 + Gate 2 rounds, revisions, the `full`-rigor campaign evaluate) — the gauntlet is not free.
+Report the **total estimated agent calls**. If it exceeds a sane threshold (rule of thumb: >150 total
+agent calls, or >20 scanners per wave), surface it so the user can narrow lanes, coarsen bands, raise
+the batch size, or drop rigor. The budget — both numbers — is part of what they approve.
+
+Then **stop and present the plan** (the epic/feature/story layout + the component map + the budget)
+for review. This is the plan-first gate: the user approves or adjusts the shape before any scanning
+runs. Adjust and re-confirm if they redirect. Commit the plan:
+`deep-code-scan: plan <goal> (<L> lanes, <B> bands, ~<N> agent calls)`.
+
+> **Engagement-owned, enforced structurally.** The scan scaffold is owned by `deep-code-scan`: it
+> drives the scaffold in Phase 4 and closes it within the run, like research-orchestrator owning its
+> engagement. This is **not** left to a documentation warning — the paired substrate change ships
+> autopilot **scan-awareness**: `autopilot` excludes `[scan]`-tagged items from its ready queue by
+> construction, so a stray `autopilot --all` cannot grab a `stage: implementing` scan story and route
+> it to `implement-orchestrator`. The discriminator is the `[scan]` tag; the **fix** epic carries
+> project routing tags (not `[scan]`), so it drains through normal autopilot like any other work.
+> Until that substrate change lands in a given install, `[scan]` items are still grabbable — so on an
+> un-upgraded install, do not run `autopilot --all` against an in-flight campaign.
+
+### Phase 4 — Drive the scan (the fan-out)
+Walk lanes; within a lane, walk altitude stories **leaf → system in dependency order** (each band
+reads the findings the band below recorded). For each altitude story, fan out **parallel
+multi-model scanner agents across that altitude's components** — use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`, and see
+[references/scanner-brief.md](references/scanner-brief.md) for the brief, the model-diversity
+rule, and the finding schema. Each scanner loads the lane's references (per the
+[lane catalog](references/lane-catalog.md)).
+
+Each scanner writes its own packet, candidate findings, and status files directly to its assigned
+paths, then replies with only a compact status line. The orchestrator must never receive or hold the
+full scanner output in chat. At the band checkpoint, collate scanner status files, spot-check from
+the saved packets/candidates, write accepted findings to the altitude story and rollup, and advance
+only after the artifact manifest is current. A finding is not a finding without a confirmed
+`file:line` and a read-in-context rationale — grep hits alone never count. The full multi-round
+gauntlet runs at **Gate 1** once all lanes/bands have scanned, just before consolidation.
+
+### Phase 5 — Consolidate into the fix epic (gauntleted, operator-confirmed)
+This is what makes the output usable. First materialize the Gate 1 input packet from the artifact
+rollups, then run the **review gauntlet's Gate 1** over that packet (multi-round, cross-model — see
+Verification) so only survivors proceed. Then collect, dedupe by `file:line`, and **cluster** into a
+coherent remediation plan — by fix-locality, by theme, by shared root cause — rather than emitting
+one item per finding. See
+[references/consolidation.md](references/consolidation.md) for the clustering method and the fix
+epic's shape. Persist the proposed plan as a **fix-epic draft packet** inside the artifact root and
+run *that* through the **gauntlet's Gate 2** — fresh-context reviewers need a concrete artifact, and
+clustering can introduce new context/intent problems a single finding didn't have. **Then propose
+the fix epic and ask before materializing it** (like `research-handoff` — never an auto-flood). On
+confirmation, write `fix-<goal>` + its clustered features/stories, each carrying `scan_origin:
+scan-<goal>` back to the campaign. Commit:
+`deep-code-scan: emit fix epic for <goal> (<N> findings -> <M> features)`.
+
+### Phase 6 — Close and report
+Append a campaign record to the scan epic body (lanes run, components scanned, finding counts by
+severity, verification outcomes, artifact root status, fix-epic id) and advance the scan epic to
+`stage: done` — the audit is complete; it is not release-bound, and verification ran inline. Once the
+fix epic and campaign record contain the collated durable summary, delete
+`.work/scan-artifacts/scan-<goal>/`; the closeout commit should contain only the collated `.work`
+item changes. Report to the user:
+goal, lanes, components scanned, findings by severity, the fix epic id + its feature breakdown,
+and the suggested next step (`/agile-workflow:autopilot` scoped to `fix-<goal>`, or
+`/agile-workflow:scope` to reprioritize).
+
+## Scanner dispatch (the fan-out spec)
+
+The scanning happens **in the scanner agents, not in your context** — your job is mapping,
+dispatch, artifact-path preallocation, checkpoint collation, verification, and consolidation. Do
+not re-do a scanner's work in the orchestrator.
+
+- **Parallel, single message.** Dispatch all of an altitude's component-scanners in one message so
+  they run concurrently. Do not serialize.
+- **Honor the lane's locked scanner tier** (the kickoff dial, in the lane feature body). `mixed`
+  is the default for model diversity; `codex-high`/`codex-xhigh` set Codex reasoning effort; other
+  hosts map the same dial to their native high-quality scanner options. The gauntlet still runs with
+  independent fresh context regardless of the scanner tier.
+- **Scoped tight.** Each scanner gets only its component's file list plus the findings inherited
+  from the band below. Never the whole repo per scanner.
+- **References, not re-derivation.** Each scanner loads the lane's reference file(s) and applies
+  their named patterns. That is the progressive-disclosure win — keep it.
+- **Scanners write artifacts themselves.** Each scanner receives unique `raw`, `candidates`, and
+  `status` paths and writes them directly. It returns only a terse completion line to chat. If
+  context compacts mid-campaign, restart from the status files, manifest, and story links, not from
+  memory.
+
+Full brief template, severity rubric, and output format: [references/scanner-brief.md](references/scanner-brief.md).
+Artifact paths, manifest schema, rollups, checkpoint commits, and final cleanup:
+[references/artifact-ledger.md](references/artifact-ledger.md).
+
+## Verification — the multi-round review gauntlet (the rigor dial)
+
+Scanners *generate*; a separate, **iterative, cross-model** pass *hardens*. This is the most
+important quality mechanism in the skill. Auto-generated findings are riddled with three failure
+modes, and each produces a "fix" that is worse than leaving the code alone: **false positives**,
+**context-ignorant fixes** (locally real, but the remedy breaks the wider system), and — worst —
+**goal-fighting fixes** that undo a *deliberate* design choice (swapping out the repo's
+intentionally hand-rolled, dependency-free code for a library it avoids on purpose). The gauntlet
+exists to kill all three before any fix is proposed. It is multi-round on purpose: one pass
+rationalizes, several fresh passes converge on what's true.
+
+Three lenses, applied every round at `rigor ≥ standard`:
+- **Reality** — is the problem real and reachable *here*, or theoretical / already handled?
+- **Context** — does the fix respect callers, invariants, and existing abstractions, or does treating
+  it in isolation break the wider system?
+- **Intent** — does the finding or its fix contradict a *deliberate* choice (foundation docs,
+  `.work/CONVENTIONS.md`, `.agents/skills/patterns/`, "intentionally X" comments)? A documented
+  pattern is **not** a finding; a fix that undoes an intentional decision is a regression wearing a
+  fix's clothes — drop it.
+
+| `rigor` | spot-check (you) | review gauntlet | campaign evaluate |
+|---|---|---|---|
+| `floor` | ✓ always | 1 combined pass (Reality min) | — |
+| `standard` | ✓ always | ≥ 2 rounds, all 3 lenses, cross-model | — |
+| `full` | ✓ always | rounds to convergence (cap 4), all lenses, cross-model, fresh ctx each | ✓ |
+
+- **Independence is the whole game.** Each round runs in **fresh context** and, where a different
+  model class is available, via `peeragent` (pre-approved for cross-review); same-model falls back to
+  a fresh-context sub-agent. A round that re-reads its own prior reasoning converges by fatigue, not
+  truth.
+- **Two gates, same gauntlet.** *Gate 1* culls the raw findings before consolidation. *Gate 2*
+  re-runs on the **drafted fix epic** — clustering can introduce new context/intent problems a single
+  finding didn't have. The fix epic is emitted only after Gate 2 passes.
+- **Persistent dissent → advisory, never forced.** A finding the rounds can't agree on is demoted to
+  a human-judgment note on the scan epic, not shipped as a fix.
+- **spot-check** (always, you, full context) samples survivors and re-reads the cited code, dropping
+  anything grep-only or fabricated in place. **campaign evaluate** (at `full`, isolated context)
+  judges whether the campaign *as a whole* met the goal — coverage gaps, lanes that under-delivered.
+- Escalate upward freely on evidence; never prune below the spot-check floor.
+
+Full loop, lens detail, and the ledger format: [references/review-gauntlet.md](references/review-gauntlet.md).
+
+## Idempotency
+
+Re-running a campaign must not duplicate items. Recall the prior campaign with
+`work-view --scan-origin scan-<goal> --scope all` (or `grep -rl 'scan-<goal>' .work/` if the flag
+isn't installed yet). Match findings by `file:line` against the fix epic's durable **`## Resolved finding index`** — not
+the scan story bodies, which may have been pruned to bodyless archive stubs once `done` (SPEC
+archival). If you must read an archived item's findings, hydrate its body from its `git_ref`.
+Skip duplicates; tally and report skips, as `bug-scan` does for its parked items.
+
+## Guardrails
+
+- **Plan before scanning.** Phase 3's checkpoint is load-bearing — never skip straight to fan-out.
+  The user approving the map is what makes a large campaign safe to run.
+- **Reuse, don't reimplement; never invoke specialists in-campaign.** Load the specialists'
+  references as scanner knowledge; do not paste their catalogs into this skill. If the user needs a
+  single deep scoped pass, route out to the specialist *before* starting a campaign — once
+  in-campaign, every lane is references-only fan-out (invoking an item-minting specialist would bypass
+  the gauntlet and create items outside `fix-<goal>`).
+- **Findings need `file:line` + context.** No fabrication; an empty lane is a valid, honest result.
+  Score and report it as clean, not as ten weak findings.
+- **Consolidate, never flood.** The deliverable is a clustered fix epic, confirmed before writing —
+  not one backlog item per finding. This is the explicit reason `deep-code-scan` exists over a raw
+  scan.
+- **Gauntlet before you propose a single fix.** Every finding clears the multi-round, cross-model
+  review gauntlet (Reality / Context / Intent) before it can become fix work, and the drafted fix
+  epic clears it again. A fix that fights a deliberate repo choice is the worst output this skill can
+  produce — the Intent lens exists to catch exactly that, and contested findings go to a human, not
+  into the epic.
+- **Budget the fan-out.** Compute and get the scanner budget approved at the checkpoint. A campaign
+  that quietly spawns thousands of agents (domains × hundreds of leaves) is a footgun — batch leaves,
+  prune irrelevant scope, and surface the estimate.
+- **Persist before summarizing.** Every scanner packet, scanner candidate-finding file, accepted
+  finding rollup, gauntlet input, and draft fix packet must exist on disk under
+  `.work/scan-artifacts/scan-<goal>/` before you depend on it. The chat transcript is not durable
+  storage; compaction is expected on large campaigns.
+- **Clean after collating.** `.work/scan-artifacts/scan-<goal>/` is temporary campaign state, not the
+  final audit record. After the fix epic, resolved finding index, campaign record, and gauntlet
+  summary are written, remove the artifact root so raw scanner packets do not dirty the repo long
+  term.
+- **Scan scaffold is engagement-owned, enforced by the `[scan]` tag.** The paired substrate change
+  makes `autopilot` skip `[scan]` items, so the scaffold can't be misrouted to `implement-orchestrator`.
+  `deep-code-scan` drives scan execution; only the **fix** epic (no `[scan]` tag) is autopilot work.
+  Never tag a fix item `[scan]`, or autopilot will skip the work you want done.
+- **Not release-bound.** A scan is an input/audit; the scan epic carries `release_binding: null`
+  and verification runs inline. Release gating is `release-deploy`'s job, on the *fix* work.
+- **Respect scope.** Honor the chosen lanes, bands, and component map. Don't widen mid-campaign
+  without surfacing it.
+- **No fixes here.** This skill produces the scan ledger and the fix *plan*. Implementation flows
+  through `/agile-workflow:autopilot` or `/agile-workflow:implement` over the fix epic.
+
+## Related
+
+- [`bug-scan`](../bug-scan/SKILL.md) — single-pass correctness hunt; its references are the
+  correctness lane's knowledge.
+- [`gate-tests`](../gate-tests/SKILL.md) — coverage-gap analysis; the tests lane's method.
+- [`perf-scout`](../perf-scout/SKILL.md) — perf idea generation; its references + peer pass are the
+  performance lane's knowledge.
+- [`bold-refactor`](../bold-refactor/SKILL.md) — conceptual architecture lenses; the architecture
+  lane's knowledge (and it already emits a `[refactor]` epic for a direct pass).
+- [`repo-eval`](../../../code-audit/skills/repo-eval/SKILL.md) — holistic scorecard; the quality
+  lane's knowledge.
+- [`research-orchestrator`](../../../agentic-research/skills/research-orchestrator/SKILL.md) — the
+  dial/checkpoint/verification model this skill mirrors, pointed at code instead of external sources.
+- [`epic-design`](../epic-design/SKILL.md) / [`scope`](../scope/SKILL.md) — the substrate
+  decomposition mechanics this skill writes against.

package/skills/deep-code-scan/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Deep Code Scan"
+  short_description: "Plan multi-lane code scan campaigns"
+  default_prompt: "Use $deep-code-scan to plan a multi-lane scan campaign for this repository."
+policy:
+  allow_implicit_invocation: true