@nklisch/pi-agile-workflow 0.15.3

package/skills/gate-refactor/SKILL.md

@@ -0,0 +1,408 @@
+---
+name: gate-refactor
+description: >
+  Refactor gate that discovers scan-rule libraries declared in the host project (default roots:
+  {project}/.agents/skills/scan-*/SKILL.md and {project}/.claude/skills/scan-*/SKILL.md; configurable
+  via CONVENTIONS.md: gate_refactor_scan_library_roots), loads every discovered library, checks the
+  release bundle's changed files against all loaded rules, and produces findings as items with
+  gate_origin:refactor; routing tag declared per library (libraries whose fixes are
+  behavior-preserving declare findings-route:refactor; behavior-changing libraries declare no route —
+  findings emit untagged and route through normal feature/story design). Rule libraries are
+  deployment-local — the gate ships the mechanism; adopters supply the rules. Auto-triggers during
+  /agile-workflow:release-deploy when the host project opts in via CONVENTIONS.md: gates_for_release:
+  [..., refactor, ...]. No-libraries behavior: graceful skip (logs "no scan-* libraries discovered"
+  and continues). Item-producer, NOT a pass/fail report.
+---
+
+# Gate-Refactor
+
+You orchestrate a refactor gate over the items bound to a release. You discover scan-rule
+libraries the host project has installed, load them, and dispatch a **deep refactor scanner agent**
+to check the release bundle's changed files against every loaded rule. Your role is library
+discovery, bundle preparation, scanner dispatch, and converting findings into substrate items.
+
+This gate ships **the mechanism, not the rules**. The scan rule libraries that supply the actual
+rules live under the host project's configured `gate_refactor_scan_library_roots` (default:
+`{project}/.agents/skills` and `{project}/.claude/skills`). The gate requires no built-in rule
+knowledge — it adapts to whatever libraries the deploying project provides. This is why the gate is
+opt-in (not in the default `gates_for_release` list): an install with no rule libraries has nothing
+to check, and that is by design, not an error.
+
+Scanner strength is explicit: spawn exactly one source-read-only deep refactor
+scanner with the strongest inspection/reviewer setting the host exposes. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Use extra-high reasoning
+for large/polyglot release bundles or when multiple libraries carry dense rule
+sets. If the host has no scanner path, run the scan inline and record
+the reduced isolation in the release body.
+
+## Trigger
+
+- `/agile-workflow:release-deploy` invokes during `quality-gate` stage when `gates_for_release`
+  in `.work/CONVENTIONS.md` includes `refactor`.
+- User can invoke manually: `/agile-workflow:gate-refactor <release-version>`
+
+**Opt-in gate.** The default `gates_for_release` list does not include `refactor`. Add it
+explicitly when your project has scan-rule libraries to enforce:
+
+```
+gates_for_release: [security, tests, cruft, docs, patterns, refactor]
+```
+
+## Workflow
+
+### Phase 1: Identify bundle changes
+
+```bash
+# Bound non-release items. `--release` auto-widens to ALL tiers (active + archive + releases).
+# Include late-bound archived stubs; their bodies may be pruned, but their item id is still
+# present and can recover the bundle commits/files. Ignore only the release orchestration item.
+.work/bin/work-view --release <version> --paths | while IFS= read -r item; do
+  kind=$(grep -m1 '^kind:' "$item" | awk '{print $2}')
+  [ "$kind" = "release" ] && continue
+  echo "$item"
+done > /tmp/bundle-items-<version>.txt
+
+# Files changed by the bundle. For archived stubs, the body is pruned on disk by design; use the
+# item id to find implementation commits instead of treating the missing body as a skip reason.
+while IFS= read -r item; do
+  id=$(grep -m1 '^id:' "$item" | awk '{print $2}')
+  git log --grep "$id" --format='%H' | xargs -I{} git diff-tree --no-commit-id --name-only -r {}
+done < /tmp/bundle-items-<version>.txt | sort -u > /tmp/bundle-files-<version>.txt
+```
+
+### Phase 2: Discover scan-rule libraries (idempotency prep)
+
+Read `gate_refactor_scan_library_roots` from `.work/CONVENTIONS.md`. If absent, use the default
+plugin-canonical and Claude-compat roots:
+
+```yaml
+gate_refactor_scan_library_roots:
+  - .agents/skills
+  - .claude/skills
+```
+
+Resolve relative roots from the project/substrate root; absolute roots are allowed. For each
+configured root, glob `<root>/scan-*/SKILL.md`. If a configured root points outside the project
+tree, continue but treat it as a trust-boundary expansion: the gate will load instructions and
+reference files from that location.
+
+For each discovered `SKILL.md`, in configured root order:
+1. Read the `SKILL.md` fully — its frontmatter `description` and body carry the rules the gate
+   must enforce.
+2. Read all files in the library's `references/` directory (if present) — reference files carry
+   the detailed per-rule specifications.
+3. Derive a **library tag** from the directory name by stripping `scan-` (e.g., `scan-wcag-aa`
+   → `wcag-aa`, `scan-structural` → `structural`).
+4. Read the library's **routing declaration**: look for a `findings-route:` line in the SKILL.md
+   body (format: `findings-route: refactor` or `findings-route: none`). This line declares whether
+   the library's findings carry `tags: [refactor]`. If the line is absent, the default is **no
+   routing tag** — untagged is safe-by-default (feature-design handles everything; the `[refactor]`
+   route is the optimization a library opts into by asserting its fixes are behavior-preserving).
+   Record the routing decision per library for use in Phase 4.
+5. If another discovered library has the same derived library tag, keep the first one discovered
+   and skip the duplicate. This preserves current `.agents/skills` before `.claude/skills`
+   precedence under the defaults and makes custom-root precedence follow configured root order.
+
+**No-libraries behavior:** if all configured roots return zero results, log to the release body:
+
+```
+gate-refactor (<date>) — no scan-* rule libraries discovered; gate-refactor has nothing to
+check. To activate: install a scan-rule library under gate_refactor_scan_library_roots
+(default: {project}/.agents/skills/scan-<name>/ or {project}/.claude/skills/scan-<name>/).
+See gate-refactor/SKILL.md for the library contract.
+```
+
+Then continue the gate sequence. This is not an error — the gate is designed to ship
+content-free when no libraries are installed.
+
+Read existing gate items (idempotency prep):
+
+```bash
+.work/bin/work-view --release <version> --gate refactor --paths
+```
+
+Capture the set of `(file:line, rule-slug)` already-tracked findings to feed into the
+scanner brief so it skips duplicates.
+
+### Phase 3: Dispatch the refactor scanner
+
+If at least one library was discovered, spawn ONE source-read-only deep scanner
+agent with the full scan brief. Use a generic sub-agent prompted with the scanner
+posture from `../principles/references/subagents.md` and the strongest
+inspection/reviewer setting the host exposes, escalating for large/polyglot
+bundles or dense rule sets. If scanner agents are unavailable, run the scan
+inline and record the reduced isolation in the release body.
+
+The scanner checks all rules from all libraries in one pass per file, returning structured
+findings. Dispatching one scanner with the full library set (rather than one per library) avoids
+M-times-N redundant file reads and allows cross-library finding deduplication.
+
+**Brief template**:
+
+> You are conducting a refactor gate scan for release `<version>` as an agile-workflow
+> scanner. Use read/search/shell tools as needed. Scan ONLY the bundle's changed files —
+> not the whole repo. Do not spawn nested sub-agents or implement fixes.
+>
+> **Bundle scope** (files changed by the bundle):
+> ```
+> <bundle-files>
+> ```
+>
+> **Loaded rule libraries** (N libraries discovered):
+>
+> For each library `<tag>` (e.g. `structural`, `wcag-aa`):
+>
+> **Library: `<tag>`** (source: `{project}/.agents/skills/scan-<name>/` or `{project}/.claude/skills/scan-<name>/`)
+> ```
+> <full SKILL.md content>
+> ```
+> Reference files:
+> ```
+> <full content of each file in references/>
+> ```
+>
+> **Already-tracked findings to skip**:
+> ```
+> <(file:line, rule-slug) pairs already written as items>
+> ```
+>
+> **Instructions**:
+>
+> 1. Read every file in the bundle scope.
+> 2. For each file, check against all rules from all loaded libraries in a single pass.
+> 3. For each finding, record:
+>    - **Library tag**: which library's rule was violated (e.g. `structural`).
+>    - **Rule slug**: which specific rule was violated (from the library's rule inventory).
+>    - **File:line**: exact location.
+>    - **Issue**: one-sentence description of the violation.
+>    - **Fix**: specific proposed change (or "needs analysis" for findings requiring judgment).
+>    - **Confidence**: `high` / `medium` / `low` per the library's guidance for that rule.
+> 4. Deduplicate against the already-tracked set.
+> 5. Return findings as a structured list.
+>
+> **Rules**:
+> - Scan only the bundle scope. Do not expand to the whole repo.
+> - Cite file:line for every finding.
+> - Do not fabricate findings. If a rule produces no matches, emit nothing for it.
+> - Skip already-tracked findings (exact file:line + rule-slug match).
+> - Confidence follows the library's own guidance for each rule. When the library
+>   does not specify, default to medium. Normalize any other severity vocabulary a
+>   library uses (e.g. critical/info, numeric scores) onto `high`/`medium`/`low`
+>   rather than defaulting mismatches to medium.
+>
+> **Output format** — return a single markdown document with:
+>
+> ```
+> ## Findings
+>
+> ### Finding 1
+> - **Title**: <one-line description>
+> - **Library**: <library-tag>
+> - **Rule**: <rule-slug>
+> - **Confidence**: High | Medium | Low
+> - **Location**: `<file>:<line>`
+> - **Issue**: <one sentence>
+> - **Fix**: <specific proposed change or "needs analysis">
+>
+> ### Finding 2
+> ...
+> ```
+>
+> Followed by:
+>
+> ```
+> ## Scan summary
+> - Libraries loaded: <list of library tags>
+> - Files scanned: <count>
+> - Findings by confidence: High=<n>, Medium=<n>, Low=<n>
+> ```
+
+### Phase 4: Convert findings to items
+
+For each finding the scanner returned:
+
+Read `gate_finding_routing` from `.work/CONVENTIONS.md` before writing items. If absent, use the
+default routing below. Normalize refactor confidence to routing keys as: `High -> high`,
+`Medium -> medium`, and `Low -> low`. If a normalized key maps to `skip`, do not emit an item for
+that finding; include the skipped count in the gate output and release-body gate-run record. If it
+maps to `backlog`, write a `.work/backlog/` item instead of an active story.
+
+**`gate_origin: refactor` is unconditional** — it records which gate produced the item, not the
+nature of the fix. The `tags:` field is determined by the source library's routing declaration:
+- Library declared `findings-route: refactor` → `tags: [refactor]` (behavior-preserving; routes
+  through refactor-design).
+- Library declared `findings-route: none` or declaration absent → `tags: []` (behavior-changing or
+  unclassified; routes through the normal feature/story design path).
+
+The rationale: `[refactor]` is strictly behavior-preserving by definition (black-box test — no
+observable behavior change for any caller of the public surface). Libraries whose fixes change
+observable behavior — a11y improvements, SEO changes, API corrections — must not carry the tag or
+refactor-design will bounce them as mistagged.
+
+**Example: behavior-preserving library (e.g. `scan-structural`, `findings-route: refactor`)**
+
+```yaml
+---
+id: gate-refactor-<short-slug>
+kind: story
+stage: implementing | drafting    # by gate_finding_routing
+tags: [refactor]
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: refactor
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+**Example: behavior-changing library (e.g. `scan-wcag-aa`, no findings-route declaration)**
+
+```yaml
+---
+id: gate-refactor-<short-slug>
+kind: story
+stage: implementing | drafting    # by gate_finding_routing
+tags: []
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: refactor
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+Item body (same for both cases):
+
+```markdown
+# <one-line description>
+
+## Library
+<library-tag>
+
+## Rule
+<rule-slug>
+
+## Confidence
+High | Medium | Low
+
+## Location
+`<file>:<line>`
+
+## Issue
+<one-sentence violation description>
+
+## Fix
+<specific proposed change, or "needs analysis" for medium/low>
+```
+
+Default confidence -> placement mapping:
+
+| Confidence | Stage | Tier |
+|---|---|---|
+| High | `stage: implementing` | `.work/active/stories/` |
+| Medium | `stage: drafting` | `.work/active/stories/` |
+| Low | backlog file | `.work/backlog/` |
+
+Slug: derive from library tag + rule slug + file fragment (e.g.
+`gate-refactor-structural-routes-api`, `gate-refactor-wcag-aa-missing-alt`). If the derived
+slug already exists (same rule firing twice in one file or across runs), append a counter
+suffix (`-2`, `-3`, …) to keep slugs unique.
+
+### Phase 5: Update the release body
+
+Append to the release body's gate-runs section:
+
+```markdown
+- **gate-refactor** (YYYY-MM-DD) — N findings (H high, M medium, L low) from K libraries:
+  <library-tag-1> (<n> findings), <library-tag-2> (<n> findings)
+```
+
+If no libraries were discovered, append the no-libraries log entry from Phase 2 instead.
+
+### Phase 6: Commit
+
+```bash
+git add .work/active/stories/ .work/backlog/ .work/active/release-<version>.md
+git commit -m "gate-refactor: <N> findings for <version> (<library-tags>)"
+```
+
+If no findings and no libraries: `gate-refactor: no libraries discovered for <version> — gate skipped`.
+If no findings but libraries ran: `gate-refactor: 0 findings for <version> (<library-tags> — clean)`.
+
+## Output
+
+In conversation:
+- **Bundle**: `<version>` — `<N>` items audited, `<M>` files changed
+- **Libraries**: count and tags (`structural`, `wcag-aa`, ...) or "none discovered"
+- **Findings**: count by confidence (High / Medium / Low), or "no findings"
+- **Items created**: count, with new ids
+- **Already-tracked**: count skipped
+
+## Guardrails
+
+- **The scan happens in the scanner agent, not here.** Your job is library discovery, bundle prep,
+  dispatch, and item-writing. Do not replicate the scanner's analysis.
+- Scan only the bundle's changed files, not the whole repo.
+- Never apply fixes in this skill — produce items only.
+- **No-libraries is not an error.** Graceful skip with a log entry is the correct behavior when
+  no scan-* libraries are installed.
+- Pass already-tracked findings into the scanner brief so it skips duplicates (idempotency).
+- Include archive stubs returned by `work-view --release <version> --paths`. Late-bound archived
+  stubs are part of the release bundle and must be scanned from their associated commits/files,
+  even when their on-disk bodies are pruned.
+- Do NOT add `refactor` to the default `gates_for_release` list. The gate is opt-in by design.
+  Deployers with no scan-rule libraries would get a no-op gate on every release — unnecessary
+  overhead. Adopters opt in by editing their `.work/CONVENTIONS.md`.
+
+## Library contract (for adopters writing scan-rule libraries)
+
+A scan-rule library declares itself by its directory name and the content of its SKILL.md:
+
+- **Location**: `<root>/scan-<name>/SKILL.md`, where `<root>` comes from
+  `gate_refactor_scan_library_roots` in `.work/CONVENTIONS.md` (default:
+  `{project}/.agents/skills` then `{project}/.claude/skills`). Duplicate names are merged by
+  derived library tag; the first discovered library wins, so configured root order determines
+  precedence.
+- **SKILL.md content**: the `description` frontmatter field and the body carry the rules. The
+  gate reads the full SKILL.md and all files in `references/` as the library declaration.
+- **Rule format**: each rule should carry a slug (for deduplication), a description of what
+  constitutes a violation, and confidence guidance (when does a match warrant `high` vs. `medium`
+  vs. `low` confidence). These three values are the **required vocabulary** — the gate and
+  downstream tooling map directly on them.
+- **Routing declaration** (one line in the SKILL.md **body** — NOT a frontmatter key; the gate
+  scans the body for this line, so a frontmatter placement would be silently missed):
+  ```
+  findings-route: refactor
+  ```
+  Declares that this library's rules are **behavior-preserving** (structural, stylistic, dead-code
+  removal) — every fix passes the black-box test: no observable behavior change for any caller of
+  the public surface. Findings from this library carry `tags: [refactor]` and may route through
+  `refactor-design`.
+
+  **Default when absent: no routing tag.** Libraries whose fixes are **behavior-changing** (a11y,
+  SEO, API corrections, anything altering observable behavior for any consumer) omit the
+  declaration or set `findings-route: none`. Their findings emit without a `[refactor]` tag and
+  route through the normal feature/story design path. Untagged is the safe default — feature-design
+  handles everything; the `[refactor]` route is the optimization a library opts into by asserting
+  behavior-preservation.
+- **No registration required**: the gate discovers libraries by glob. No manifest entry needed.
+
+Example library skeleton (behavior-preserving — opts in to `[refactor]` routing):
+
+```
+{project}/.agents/skills/scan-structural/
+  SKILL.md         ← library declaration + rule inventory + findings-route: refactor
+  references/
+    api-shape.md   ← detailed rule: API structural conventions
+    error-shape.md ← detailed rule: error-handling conventions
+```
+
+Example library skeleton (behavior-changing — omits routing declaration):
+
+```
+{project}/.agents/skills/scan-wcag-aa/
+  SKILL.md         ← library declaration + rule inventory (no findings-route line)
+  references/
+    wcag-aa-rules.md ← detailed WCAG 2.x AA rule set
+```

package/skills/gate-security/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: gate-security
+description: >
+  Security gate that scans items bound to a release and produces items as findings. Delegates the full
+  audit to a deep security scanner agent which discovers stack, picks relevant security domains
+  (auth, injection, secrets, deps, API, infra, crypto, data protection, error handling), audits the
+  bundle's code changes, and returns findings. The orchestrator converts findings into items in
+  .work/active/ with gate_origin:security and appropriate tags. Auto-triggers during
+  /agile-workflow:release-deploy quality-gate stage. Item-producer, NOT a pass/fail report.
+---
+
+# Gate-Security
+
+You orchestrate a security gate over the items bound to a release. The actual
+audit runs inside a **deep security scanner agent** (a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`); your role is to prepare the bundle context,
+dispatch the scanner, and convert the findings it returns into items in the
+substrate.
+
+Scanner strength is explicit: spawn exactly one source-read-only deep security
+scanner with the strongest inspection/reviewer setting the host exposes. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md`. Use extra-high reasoning
+only for auth, crypto, data-loss, broad public API, or large/polyglot release
+bundles. If the host has no scanner path, run the audit inline and
+record the reduced isolation in the release body.
+
+This is NOT a standalone audit (for that, use a standalone `repo-eval` skill). This
+is a gate over a specific release bundle, producing items the release-deploy
+flow can drain to `done` before shipping.
+
+## Trigger
+
+- `/agile-workflow:release-deploy` invokes this during the `quality-gate` stage
+- User can invoke manually: `/agile-workflow:gate-security <release-version>`
+
+## Workflow
+
+### Phase 1: Identify the bundle
+
+If a release version was provided:
+```bash
+# Bound non-release items. `--release` auto-widens to ALL tiers (active + archive + releases).
+# Include late-bound archived stubs; their bodies may be pruned, but their item id is still
+# present and can recover the bundle commits/files. Ignore only the release orchestration item.
+.work/bin/work-view --release <version> --paths | while IFS= read -r item; do
+  kind=$(grep -m1 '^kind:' "$item" | awk '{print $2}')
+  [ "$kind" = "release" ] && continue
+  echo "$item"
+done > /tmp/bundle-items-<version>.txt
+```
+
+Otherwise, find the active release file (the one at `stage: planned` or
+`stage: quality-gate`) and use its version.
+
+If no items are bound (the bundle-items file is empty), halt with: "No items
+bound to release `<version>`. Bind items first via
+`/agile-workflow:release-deploy`."
+
+Build the union of files changed by the bundle. For archived stubs, the body is pruned on disk by
+design; use the item id to find implementation commits instead of treating the missing body as a
+skip reason:
+
+```bash
+while IFS= read -r item; do
+  id=$(grep -m1 '^id:' "$item" | awk '{print $2}')
+  git log --grep "$id" --format='%H' | xargs -I{} git diff-tree --no-commit-id --name-only -r {}
+done < /tmp/bundle-items-<version>.txt | sort -u > /tmp/bundle-files-<version>.txt
+```
+
+### Phase 2: Read existing gate items (idempotency prep)
+
+```bash
+.work/bin/work-view --release <version> --gate security --paths
+```
+
+Capture the set of `(file:line, severity)` already-tracked findings so the
+scanner can be told to skip duplicates.
+
+### Phase 3: Dispatch the security scanner
+
+Spawn ONE source-read-only deep scanner agent with the full audit brief. Use a generic sub-agent prompted with the scanner posture from `../principles/references/subagents.md` and the strongest
+inspection/reviewer setting the host exposes, escalating for auth, crypto,
+data-loss, broad public API, or large/polyglot bundles. If scanner agents
+are unavailable, run the audit inline and record the reduced isolation in the
+release body. The scanner does all of the analysis end-to-end — stack discovery,
+domain selection, domain audit passes, severity classification — and returns
+structured findings.
+
+**Brief template** (substitute `<version>`, `<bundle-files>`,
+`<bound-item-ids>`, `<already-tracked>`):
+
+> You are conducting a security gate audit for release `<version>` as an
+> agile-workflow scanner. Use read/search/shell/current-source lookup tools as
+> needed, but do not spawn nested sub-agents or implement fixes.
+>
+> **Bundle scope** (audit ONLY these files; this is a release gate, not a
+> repo-wide audit):
+> ```
+> <bundle-files>
+> ```
+>
+> **Bound items** (an archived stub's body is pruned on disk — hydrate it from
+> the stub's `git_ref` frontmatter via `git show <git_ref>:<path>`, trying the
+> item's former `.work/active/` path at that ref): `<bound-item-ids>`
+>
+> **Already-tracked findings to skip** (do not re-report these):
+> ```
+> <already-tracked file:line / severity pairs>
+> ```
+>
+> **Methodology**:
+>
+> 1. **Stack discovery** — read `package.json`, `tsconfig.json`, `Cargo.toml`,
+>    `go.mod`, `pyproject.toml`, `Dockerfile`, CI configs. Identify languages,
+>    frameworks, package managers, auth systems, entry points (API routes, CLI,
+>    serverless), infrastructure.
+>
+> 2. **Domain selection** — pick the relevant domains for this stack and the
+>    bundle's surface. The nine domains:
+>    1. Authentication & Authorization — auth flows, sessions, RBAC/ABAC,
+>       tokens, password policies. Apps with user accounts; APIs with auth.
+>    2. Input Validation & Injection — XSS, SQLi, command injection, path
+>       traversal, template injection, SSRF. Web apps, APIs.
+>    3. Secrets & Configuration — hardcoded secrets, env leakage, insecure
+>       defaults, exposed config, `.env` in VCS. All projects.
+>    4. Dependencies & Supply Chain — known CVEs, outdated packages, lockfile
+>       integrity, typosquatting risk, unnecessary deps. All projects with
+>       external deps.
+>    5. Data Protection — encryption at rest/in transit, PII handling, log
+>       sanitization, secure deletion, backup security. Apps handling user
+>       data.
+>    6. API Security — rate limiting, CORS, auth on all endpoints, mass
+>       assignment, response leakage, versioning. REST/GraphQL APIs.
+>    7. Infrastructure & Deployment — Dockerfile security, CI/CD secrets,
+>       exposed ports, cloud IAM, container hardening, network policies.
+>       Deployed services.
+>    8. Cryptography — weak algorithms, hardcoded keys, RNG, cert validation,
+>       key management. Apps doing encryption/signing.
+>    9. Error Handling & Logging — stack trace leakage, audit gaps, PII in
+>       logs, missing error boundaries, verbose prod errors. All prod apps.
+>
+> 3. **Domain audit passes** — for each selected domain, audit the bundle's
+>    changed files against that domain's checklist. Use current-source lookup
+>    when needed to verify best practices for `<stack>+<domain>` combinations
+>    before judging.
+>
+> 4. **Severity classification** — every finding gets one of:
+>    | Severity | Meaning |
+>    |---|---|
+>    | Critical | Actively exploitable now (secrets in source, no auth on a public endpoint, plaintext password storage). Must fix before shipping. |
+>    | High | Significant control missing or known CVE in a deployed dep. Strong attacker leverage. Must fix before shipping. |
+>    | Medium | Hardening gap or non-obvious vuln requiring chained conditions. Should fix; can defer with explicit acknowledgement. |
+>    | Low | Defense-in-depth; minor info disclosure; outdated-but-not-vulnerable. Backlog. |
+>    | Info | Observation; not a finding. Don't return Info entries. |
+>
+> **Output format** — return a single markdown document with:
+>
+> ```
+> ## Findings
+>
+> ### Finding 1
+> - **Title**: <one-line>
+> - **Severity**: Critical | High | Medium | Low
+> - **Domain**: <domain name>
+> - **Location**: `<file>:<line>`
+> - **Evidence**:
+>   ```<lang>
+>   <1-5 lines of offending code>
+>   ```
+> - **Remediation direction**: <direction, not finished fix>
+>
+> ### Finding 2
+> ...
+> ```
+>
+> Followed by:
+>
+> ```
+> ## Audit summary
+> - Stack: <one-line>
+> - Domains audited: <list>
+> - Files audited: <count>
+> - Findings by severity: Critical=<n>, High=<n>, Medium=<n>, Low=<n>
+> ```
+>
+> **Rules**:
+> - Audit only the files listed in Bundle scope. Do NOT expand the audit.
+> - Cite file:line for every finding.
+> - Don't fabricate. If evidence is missing, don't report.
+> - Skip findings that match the already-tracked list.
+> - Don't implement fixes. Findings only.
+
+### Phase 4: Convert findings to items
+
+For each finding the scanner returned (above Info severity):
+
+Read `gate_finding_routing` from `.work/CONVENTIONS.md` before writing items.
+If absent, use the default routing below. Normalize security severity to routing
+keys as: `Critical -> critical`, `High -> high`, `Medium -> medium`,
+`Low -> low`, and `Info -> info` (Info is not returned as a finding by the
+scanner, but the route is reserved for consistency). If a normalized key maps
+to `skip`, do not emit an item for that finding; include the skipped count in
+the gate output. If it maps to `backlog`, write a `.work/backlog/` item instead
+of an active story.
+
+```yaml
+---
+id: gate-security-<short-slug>
+kind: story
+stage: implementing      # Critical or High
+                         # OR drafting for Medium
+                         # OR backlog file for Low
+tags: [security]
+parent: null
+depends_on: []
+release_binding: <version>
+gate_origin: security
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <one-line title>
+
+## Severity
+Critical | High | Medium | Low
+
+## Domain
+<domain>
+
+## Location
+`<file>:<line>`
+
+## Evidence
+\`\`\`<lang>
+<short code snippet, 1-5 lines>
+\`\`\`
+
+## Remediation direction
+<what should change — direction, not a finished fix>
+```
+
+Default severity -> placement mapping:
+- **Critical** / **High** → `stage: implementing` in `.work/active/stories/`
+- **Medium** → `stage: drafting` in `.work/active/stories/`
+- **Low** → backlog file in `.work/backlog/` (not stage-managed)
+- **Info** → skipped (no item emitted)
+
+### Phase 5: Commit
+
+```bash
+git add .work/active/stories/ .work/backlog/
+git commit -m "gate-security: <N> findings for <version>"
+```
+
+## Output
+
+In conversation:
+- **Bundle**: `<version>` — `<N>` items audited
+- **Findings**: count by severity (Critical / High / Medium / Low)
+- **Items created**: count, with new ids
+- **Already-tracked**: count of duplicate findings skipped
+- **Next**: gate-security adds to release readiness criteria. Release ships when
+  all bound items (including these) reach `stage: done`.
+
+## Guardrails
+
+- **The audit happens in the scanner agent, not here.** Your job is bundle
+  prep, dispatch, and item-writing. Don't replicate the scanner's analysis in
+  the orchestrator's context.
+- Never implement fixes — produce items only.
+- Always cite file:line in finding bodies.
+- Don't fabricate findings. If the scanner returns nothing for a domain, it
+  returns nothing. Don't paper that over.
+- Idempotent re-runs: pass already-tracked findings into the scanner brief so it
+  skips duplicates. Double-check on item-write before creating.
+- Audit only the bundle's changes, not the whole repo. Repo-wide audits are
+  a standalone `repo-eval`'s job, not a release gate's.