peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

package/dist/services/workspace/templates/project-scan/audit-output-schema.md

@@ -0,0 +1,100 @@
+---
+schemaVersion: 1
+templateKind: audit-output-schema
+capturedAt: 2026-06-27T00:00:00.000Z
+appliesTo: peaks-security-audit + peaks-perf-audit
+---
+
+# Audit Output Schema (peaks-loop v2.12.0)
+
+> **Unified output schema** for both `peaks-security-audit` and
+> `peaks-perf-audit` skills. Lives under `.peaks/project-scan/` so it is
+> git-tracked. The schema below is the canonical contract that downstream
+> consumers (peaks-rd aggregator, peaks-qa Gate A3/A4, peaks-txt sediment)
+> read from.
+
+## Schema
+
+The audit output artifact (`audit/security-<rid>.md` or
+`audit/perf-<rid>.md`) is a markdown file with a YAML frontmatter block
+followed by markdown body sections.
+
+### Frontmatter (required, all fields)
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schemaVersion` | integer (currently `1`) | YES | Schema version. Bump on breaking change. |
+| `artifactKind` | enum: `security-audit` \| `perf-audit` | YES | Identifies which skill produced this artifact. |
+| `rid` | string (request-id format: `YYYY-MM-DD-<kebab-slug>`) | YES | The request this audit is bound to. |
+| `sid` | string (session-id) | YES | The session that produced this audit. |
+| `handoffHash` | string (64-char hex sha256) | YES | sha256 of the prd/handoff.md body. Validated against on read. |
+| `templateVersion` | integer | YES | The version of the security-template or perf-template the audit ran against. |
+| `generatedAt` | string (ISO 8601) | YES | When the audit was produced. |
+| `verdict` | enum: `pass` \| `warn` \| `block` | YES | Top-level audit verdict. |
+| `violationsCount` | integer | YES | Total violations across all severities. |
+
+### Frontmatter (optional, schema-version-stable)
+
+| Field | Type | Description |
+|---|---|---|
+| `parentRid` | string | When this audit supersedes a previous one (e.g. re-run after a fix), the original rid. |
+| `previousHash` | string (64-char hex) | sha256 of the prior audit artifact body (chain link for re-runs). |
+| `degradationNote` | string | When the audit had to fall back from the canonical template (e.g. ECC unavailable, parallel-review fan-out degraded). One of the known tokens. |
+
+## Required fields by body section
+
+| Section | Required for security | Required for perf |
+|---|---|---|
+| `## Summary` | YES | YES |
+| `## Threat model coverage` | YES | NO |
+| `## Baseline reference` | NO | YES |
+| `## Measurement result` | NO | YES |
+| `## Threshold check` | NO | YES |
+| `## Findings` | YES | YES |
+| `## Required fixes` | YES | YES |
+| `## Recommended` | YES | NO |
+| `## Verdict` | YES | YES |
+
+## Optional fields
+
+The body MAY include additional markdown sections beyond the required
+list. Consumers MUST ignore unknown sections (forward-compatibility rule).
+Consumers MUST NOT silently drop required sections (regression rule).
+
+## Aggregation rules
+
+When `peaks-rd` aggregates audits from multiple skills, it uses the
+following rules:
+
+1. **Verdict precedence** — `block` > `warn` > `pass`. The aggregator's
+   top-level verdict is the highest of the input verdicts.
+2. **CRITICAL count** — sum of `CRITICAL:` markers across `## Verdict`
+   blocks. The aggregator's overall `CRITICAL:` count is the total.
+3. **Required fix deduplication** — identical `(file, line, hint)` tuples
+   from different audits are merged into one Required Fixes entry. The
+   source audits are listed in the entry.
+4. **Handoff hash consistency** — if any input audit's `handoffHash`
+   differs from the canonical peaks-prd handoff hash, the aggregator
+   rejects the input with `AUDIT_HANDOFF_MISMATCH`.
+
+## Schema version policy
+
+- Bump `schemaVersion` (int) on any **breaking** change to the frontmatter
+  fields or required body sections.
+- Add new optional fields without bumping (forward-compat).
+- A 1-minor-release deprecation window applies: when a new schemaVersion
+  is introduced, the previous version's parsers stay in the codebase for
+  1 minor release, then are removed.
+
+## Known schema variants
+
+> This section is **append-only**. peaks-txt sediment step appends new
+> rows when a downstream consumer requires a schema extension that
+> doesn't fit the current version.
+
+| # | Variant | First introduced (rid) | Source | Status |
+|---|---|---|---|---|
+| (empty) | — | — | — | — |
+
+The schema for new rows is `{ #, variant description, first introduced rid, source, status }`.
+The `status` enum is `active` / `superseded` / `deprecated`.

package/dist/services/workspace/templates/project-scan/business-knowledge.md

@@ -0,0 +1,44 @@
+---
+schemaVersion: 1
+---
+
+# Business Knowledge — peaks-loop v2.11.0 baseline
+
+> Auto-bootstrap of `.peaks/project-scan/business-knowledge.md` (v2.11.0 D3).
+> Schema: `BusinessKnowledge { concepts: BusinessConcept[] }` at
+> `src/services/prd/project-scan-types.ts`. The peaks-txt sediment step (Group C)
+> appends new concepts idempotently by `(concept, sourceRid)`.
+
+| Concept | Definition | Source | Decided | Evidence |
+|---|---|---|---|---|
+| D1 | Immutable shared handoff from peaks-prd (sha256-locked body, frontmatter `schemaVersion: 2`). Written at `.peaks/_runtime/<sid>/prd/handoff.md`. Source of truth for RD + QA + 4 audit sub-agents. | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md` |
+| D2 | Half-white-box merged audit output — code-review + security-review + perf-baseline + qa-test-cases all consolidated into ONE file per slice. Reduces LLM context overhead and avoids split-brain conclusions. | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md` |
+| D3 | project-scan bidirectional learning loop. peaks-prd READS `.peaks/project-scan/{project-scan.md, business-knowledge.md}` before brainstorm; peaks-txt SEDIMENTS new decisions into `business-knowledge.md` after every successful slice. Schema is owned by `services/prd/project-scan-types.ts`. | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md` |
+| D4 | ECC code-review via Agent tool (not Skill tool). The Skill tool has no structured output envelope; the Agent tool returns a JSON-enforced result that the 5-way fan-out aggregator can merge deterministically. | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md` |
+| D5 | full-auto / swarm mode auto-proceed on user recommendation (3 hard-floor categories still ask via AskUserQuestion: auth scope, destructive ops, irreversible bills). assisted / strict always ask. | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-full-auto-self-decision.md` |
+| D6 | Main-session context monitor + IDE-aware compact trigger. Fires when context ≥ 75% (warning) or ≥ 90% (auto-compact recommendation). Coexists with peaks-loop periodic checkpoint (Step N, every 20 tool calls). | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-main-session-context-monitor.md` |
+| D7 | Post-compact auto-resume contract. On same-session re-invocation with no fresh checkpoint file, falls back to memory-files (`peaks project memories --project <repo> --json`) + RD artifact Status section + working-tree diff. D7.b override: all modes auto-proceed on resume regardless of mode. D7.c skips: Steps 0.5/0.55/0.6/1/2/2.5 (already done pre-compact). | `001-v2-11-rd-techdoc-removal-and-runtime-friction` | `2026-06-26T03:05:30Z` | `.peaks/memory/2026-06-26-v2-11-post-compact-resume.md` |
+| G1 | peaks-prd handoff redefinition: D1-immutable, sha256-verified, schemaVersion: 2; new service `services/prd/handoff-service.ts` (init/write/read/verify/show); new CLI `peaks prd handoff init\|verify\|show`; legacy `peaks prd write-handoff` subcommand name is FORBIDDEN in help text (AC-1). | `001-v2-11-cc-group-b-prd-handoff-and-project-scan` | `2026-06-26T04:56:00Z` | `.peaks/_runtime/2026-06-26-session-a28d69/rd/requests/001-v2-11-cc-group-b-prd-handoff-and-project-scan.md` |
+| G2 | peaks-prd reads project-scan.md + business-knowledge.md BEFORE brainstorm (Step 0.8 in SKILL.md). First-run bootstrap writes the two template files if absent; logs `first-run bootstrap` to skip duplication on subsequent runs. | `001-v2-11-cc-group-b-prd-handoff-and-project-scan` | `2026-06-26T04:56:00Z` | `.peaks/_runtime/2026-06-26-session-a28d69/rd/requests/001-v2-11-cc-group-b-prd-handoff-and-project-scan.md` |
+| G3 | Legacy `src/services/handoff/` module (slice-025 slice-dag handoff) CO-EXISTS with new `src/services/prd/` module. AC-1 forbids the CLI subcommand NAME `peaks prd write-handoff` only; underlying module rename is out-of-scope for v2.11.0. | `001-v2-11-cc-group-b-prd-handoff-and-project-scan` | `2026-06-26T04:56:00Z` | `.peaks/_runtime/2026-06-26-session-a28d69/rd/requests/001-v2-11-cc-group-b-prd-handoff-and-project-scan.md` |
+| D2' | v2.12.0 RD fan-out is **3 sub-agents** (code-reviewer + qa-test-cases-writer + karpathy-reviewer). security-reviewer + perf-baseline-reviewer moved out into standalone audit skills (`peaks-security-audit` + `peaks-perf-audit`) that consume the immutable handoff and write `audit/security.md` + `audit/perf.md`. Source of truth: `src/services/rd/reviewer-dispatch-policy.ts` `RD_FANOUT_REVIEWERS` (3-element tuple). | `001-v2-12-independent-security-perf-audit` | `2026-06-27T08:30:00Z` | `.peaks/memory/2026-06-27-v2-12-fanout-3way.md` |
+| G1' | v2.12.0 peaks-txt sediment step appends new audit-inventory rows (Risk pattern / Perf pattern / Schema variant) idempotently by `(value, sourceRid)` to `.peaks/project-scan/{security-template, perf-template, audit-output-schema}.md`. 3 new public functions (`appendSecurityPattern` + `appendPerfPattern` + `appendAuditSchemaVariant`) wrapping a generic internal helper. Frontmatter policy: on fresh-create emit canonical `templateKind`; on existing file preserve verbatim. | `001-v2-12-independent-security-perf-audit` | `2026-06-27T08:30:00Z` | `.peaks/memory/2026-06-27-v2-12-independent-security-perf-audit.md` |
+
+## How to consume
+
+```bash
+peaks project knowledge --project <repo> --json
+peaks project knowledge --project <repo> --filter handoff --json
+```
+
+## How to append (peaks-txt sediment step — Group C)
+
+Match by `(concept, sourceRid)` — if a row with the same `concept` already
+exists, UPDATE `definition` + `decidedAt`; otherwise APPEND a new row. Never
+DELETE. Never reorder. Always preserve the D-row + G-row separation.
+
+## Refresh procedure
+
+1. After every successful slice, peaks-txt sediment step appends the new concept(s)
+2. After every major dependency bump, re-run `peaks scan libraries` and update D1-D7 evidence links if any moved
+3. Schema migration: if `BusinessConcept` shape changes, bump `schemaVersion` and write a migration note

package/dist/services/workspace/templates/project-scan/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Bundled project-scan templates for `peaks workspace init`.
+ *
+ * Slice 2026-07-15-project-scan-bootstrap (PRD G4b / AC9 / R4):
+ *   4 audit/business templates are bundled in the repo at
+ *   `src/services/workspace/templates/project-scan/*.md` and copied
+ *   verbatim to `<projectRoot>/.peaks/project-scan/` on every
+ *   `peaks workspace init` (idempotent skip when the target file
+ *   already exists; `--force-project-scan-templates` overrides).
+ *
+ *   `project-scan.md` is NOT bundled here — it is generated dynamically
+ *   by `bootstrapProjectScan` (slice 2026-07-15-project-scan-bootstrap).
+ *
+ * Template-integrity guarantee:
+ *   The vitest test `tests/unit/workspace/templates/template-integrity.test.ts`
+ *   asserts byte-for-byte equality between these 4 files and the
+ *   canonical sources at `.peaks/project-scan/{4 files}`. Any drift
+ *   fails the suite (R4 engineering guard against template drift).
+ */
+export declare const TEMPLATE_FILES: readonly ["business-knowledge.md", "security-template.md", "perf-template.md", "audit-output-schema.md"];
+export type TemplateFileName = (typeof TEMPLATE_FILES)[number];
+/**
+ * Read a bundled template by name. Throws when the name is not in
+ * TEMPLATE_FILES (TypeScript narrows the union, but runtime callers
+ * may pass arbitrary strings).
+ */
+export declare function readTemplate(name: TemplateFileName): Promise<string>;
+/**
+ * Same as `readTemplate` but throws a descriptive error when the name
+ * is not in TEMPLATE_FILES. Used by the bootstrap service where the
+ * name comes from a known-typed list and a typo would otherwise fail
+ * with an unhelpful ENOENT.
+ */
+export declare function readTemplateStrict(name: string): Promise<string>;

package/dist/services/workspace/templates/project-scan/index.js

@@ -0,0 +1,60 @@
+/**
+ * Bundled project-scan templates for `peaks workspace init`.
+ *
+ * Slice 2026-07-15-project-scan-bootstrap (PRD G4b / AC9 / R4):
+ *   4 audit/business templates are bundled in the repo at
+ *   `src/services/workspace/templates/project-scan/*.md` and copied
+ *   verbatim to `<projectRoot>/.peaks/project-scan/` on every
+ *   `peaks workspace init` (idempotent skip when the target file
+ *   already exists; `--force-project-scan-templates` overrides).
+ *
+ *   `project-scan.md` is NOT bundled here — it is generated dynamically
+ *   by `bootstrapProjectScan` (slice 2026-07-15-project-scan-bootstrap).
+ *
+ * Template-integrity guarantee:
+ *   The vitest test `tests/unit/workspace/templates/template-integrity.test.ts`
+ *   asserts byte-for-byte equality between these 4 files and the
+ *   canonical sources at `.peaks/project-scan/{4 files}`. Any drift
+ *   fails the suite (R4 engineering guard against template drift).
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const TEMPLATE_FILES = [
+    'business-knowledge.md',
+    'security-template.md',
+    'perf-template.md',
+    'audit-output-schema.md'
+];
+/**
+ * Resolve the absolute path of this directory at runtime. We avoid
+ * importing `meta.url` literals so the file is portable across tsx
+ * (dev) and built bundles (dist/).
+ */
+function templatesDir() {
+    // fileURLToPath works for both `file:///...` and `file:///C:/...`
+    const here = fileURLToPath(import.meta.url);
+    return dirname(here);
+}
+/**
+ * Read a bundled template by name. Throws when the name is not in
+ * TEMPLATE_FILES (TypeScript narrows the union, but runtime callers
+ * may pass arbitrary strings).
+ */
+export async function readTemplate(name) {
+    const path = join(templatesDir(), name);
+    return readFile(path, 'utf8');
+}
+/**
+ * Same as `readTemplate` but throws a descriptive error when the name
+ * is not in TEMPLATE_FILES. Used by the bootstrap service where the
+ * name comes from a known-typed list and a typo would otherwise fail
+ * with an unhelpful ENOENT.
+ */
+export async function readTemplateStrict(name) {
+    if (!TEMPLATE_FILES.includes(name)) {
+        throw new Error(`readTemplateStrict: unknown template name "${name}". ` +
+            `Allowed: ${TEMPLATE_FILES.join(', ')}`);
+    }
+    return readTemplate(name);
+}

package/dist/services/workspace/templates/project-scan/perf-template.md

@@ -0,0 +1,109 @@
+---
+schemaVersion: 1
+templateKind: perf-audit
+capturedAt: 2026-06-27T00:00:00.000Z
+appliesTo: peaks-perf-audit skill
+---
+
+# Performance Audit Template (peaks-loop v2.12.0)
+
+> **Bootstrap template** for `peaks-perf-audit` skill. Consumed by the
+> skill at audit start. Modified only by peaks-txt sediment step (append-only,
+> idempotent on `(concept, sourceRid)`). Lives under `.peaks/project-scan/` so
+> it is git-tracked and reviewable.
+
+> **Hard gate contract**: when this file is absent at audit start,
+> `peaks perf-audit run` exits with code `AUDIT_TEMPLATE_MISSING`
+> (per PRD AC-3.5).
+
+## Perf dimensions
+
+The perf-audit agent MUST measure or estimate impact on each of the
+following 6 dimensions. The aggregation produces the audit verdict
+(`pass` / `warn` / `block`).
+
+1. **CPU-bound path latency** — hot loops, regex backtracking, JSON serialization, sync vs async I/O
+2. **I/O throughput** — file read/write batching, network round-trips, stream vs buffer
+3. **Memory allocation** — large object retention, GC pressure, buffer reuse, closure capture
+4. **Concurrency model** — single-threaded event loop stalls, microtask queue saturation, worker pool sizing
+5. **Bundle / artifact size** — code split chunks, dead code, polyfill bloat, dependency weight
+6. **Cold-start cost** — first-call latency, module load time, lazy initialization gaps
+
+## Measurement methodology
+
+For each dimension, the agent uses one of the following 3 strategies
+(declared in the audit output's `## Measurement method` field):
+
+- **EMPIRICAL** — runs the actual measurement (e.g. `time` for CPU,
+  `node --heap-prof` for memory, `wc -c` for bundle size). Used when
+  the change has a runnable artifact.
+- **STATIC** — inspects the diff and the codebase to estimate impact
+  (e.g. new sync loop in async path → high CPU risk). Used when
+  empirical measurement is infeasible.
+- **N/A** — the dimension does not apply to this slice (e.g. cold-start
+  cost for a CLI subcommand that always runs to completion). Rationale
+  required.
+
+The audit output MUST declare the strategy for every dimension.
+
+## Threshold table
+
+> This table is project-agnostic defaults. The peaks-txt sediment step
+> MAY append project-specific rows when local measurements reveal
+> tighter thresholds.
+
+| Dimension | Warn threshold | Block threshold | Strategy default |
+|---|---|---|---|
+| CPU-bound path latency | +20% regression | +50% regression | EMPIRICAL |
+| I/O throughput | +15% regression | +40% regression | EMPIRICAL |
+| Memory allocation | +25% regression | +60% regression | EMPIRICAL |
+| Concurrency model | microtask saturation observed | event loop blocked >100ms | STATIC |
+| Bundle / artifact size | +30% size increase | +80% size increase | EMPIRICAL |
+| Cold-start cost | +10% regression | +25% regression | EMPIRICAL |
+
+The audit verdict is `block` when ANY dimension trips its block threshold;
+`warn` when ANY dimension trips its warn threshold but none trip block;
+`pass` otherwise.
+
+## Audit output schema
+
+The audit agent writes a single markdown file at
+`.peaks/_runtime/<sessionId>/audit/perf-<rid>.md`.
+
+### Required frontmatter
+
+```yaml
+---
+schemaVersion: 1
+artifactKind: perf-audit
+rid: <request-id>
+sid: <session-id>
+handoffHash: <sha256 of prd/handoff.md body>
+templateVersion: 1
+generatedAt: <ISO 8601 timestamp>
+verdict: pass | warn | block
+violationsCount: <integer>
+---
+```
+
+### Required body sections
+
+- `## Summary` — one-paragraph performance narrative
+- `## Baseline reference` — link to existing perf baseline (slice 025 plan artifact) or `N/A — no prior baseline`
+- `## Measurement result` — table of 6 dimensions with status
+- `## Threshold check` — table mapping measured delta to warn/block threshold
+- `## Findings` — bullet list with severity tag
+- `## Required fixes` — actionable bullet list
+- `## Verdict` — block: `verdict: <pass | warn | block>`
+
+## Known baselines inventory
+
+> This section is **append-only**. peaks-txt sediment step appends new
+> rows when a perf audit establishes a new stable baseline.
+
+| # | Baseline | First established (rid) | Source | Status |
+|---|---|---|---|---|
+| (empty) | — | — | — | — |
+
+The schema for new rows is `{ #, baseline description, first established rid, source, status }`.
+The `status` enum is `active` / `superseded` / `deprecated`.

package/dist/services/workspace/templates/project-scan/security-template.md

@@ -0,0 +1,99 @@
+---
+schemaVersion: 1
+templateKind: security-audit
+capturedAt: 2026-06-27T00:00:00.000Z
+appliesTo: peaks-security-audit skill
+---
+
+# Security Audit Template (peaks-loop v2.12.0)
+
+> **Bootstrap template** for `peaks-security-audit` skill. Consumed by the
+> skill at audit start. Modified only by peaks-txt sediment step (append-only,
+> idempotent on `(concept, sourceRid)`). Lives under `.peaks/project-scan/` so
+> it is git-tracked and reviewable like `project-scan.md` / `business-knowledge.md`.
+
+> **Hard gate contract**: when this file is absent at audit start,
+> `peaks security-audit run` exits with code `AUDIT_TEMPLATE_MISSING`
+> (per PRD AC-2.5). The CLI never falls back to inline template; the
+> file MUST be present.
+
+## Threat model dimensions
+
+The security-audit agent MUST inspect each of the following 8 dimensions
+in every audit cycle. Mark each dimension as one of: `clean` / `risk` /
+`critical` / `n/a (with rationale)`. The aggregation produces the audit
+verdict (`pass` / `warn` / `block`).
+
+1. **Authentication & authorization** — login flows, token lifecycle, RBAC, scope checks, session expiration
+2. **Secrets management** — hardcoded credentials, env-var leakage, secret rotation, vault integration
+3. **Input validation** — request body validation, query param parsing, type coercion, allowlists vs denylists
+4. **Path traversal & filesystem trust** — path normalization, symlink handling, realpath resolution, parent dir escape
+5. **SQL/NoSQL injection** — parameter binding, query construction, ORM usage, raw concatenation
+6. **Cross-site scripting (XSS) & content injection** — output encoding, CSP headers, sanitization at sink
+7. **Dependency supply chain** — third-party packages, transitive deps, lockfile drift, abandoned packages
+8. **External API surface** — egress auth, SSRF guards, response validation, timeout/retry behavior
+
+## OWASP Top-10 anchors
+
+For each dimension above, the audit agent cross-references the relevant
+OWASP Top-10 (2021) category. The list below is the canonical mapping:
+
+| Dimension | OWASP category (2021) |
+|---|---|
+| Authentication & authorization | A01:2021 — Broken Access Control |
+| Secrets management | A02:2021 — Cryptographic Failures + A07:2021 — Identification and Authentication Failures |
+| Input validation | A03:2021 — Injection |
+| Path traversal & filesystem trust | A01:2021 — Broken Access Control + A03:2021 — Injection |
+| SQL/NoSQL injection | A03:2021 — Injection |
+| XSS & content injection | A03:2021 — Injection |
+| Dependency supply chain | A06:2021 — Vulnerable and Outdated Components |
+| External API surface | A10:2021 — Server-Side Request Forgery (SSRF) |
+
+## Audit output schema
+
+The audit agent writes a single markdown file at
+`.peaks/_runtime/<sessionId>/audit/security-<rid>.md` with the following
+frontmatter and sections.
+
+### Required frontmatter
+
+```yaml
+---
+schemaVersion: 1
+artifactKind: security-audit
+rid: <request-id>
+sid: <session-id>
+handoffHash: <sha256 of prd/handoff.md body>
+templateVersion: 1
+generatedAt: <ISO 8601 timestamp>
+verdict: pass | warn | block
+violationsCount: <integer>
+---
+```
+
+### Required body sections
+
+- `## Summary` — one-paragraph risk narrative
+- `## Threat model coverage` — table of 8 dimensions with status
+- `## Findings` — bullet list with severity tag `[CRITICAL | HIGH | MED | LOW]`
+- `## Required fixes` — actionable bullet list with file:line references
+- `## Recommended` — optional improvement bullet list
+- `## Verdict` — block: `verdict: <pass | warn | block>` + `CRITICAL: <n>`
+
+The `## Verdict` block MUST contain the literal string `CRITICAL: <n>` even
+when the count is zero (per peaks-loop Gate B3 substring contract on the
+`CODE_REVIEW` prerequisite — the security-audit artifact follows the same
+convention).
+
+## Known risks inventory
+
+> This section is **append-only**. peaks-txt sediment step appends new
+> rows when a security audit surfaces a recurring risk pattern. Do not
+> rewrite existing rows.
+
+| # | Risk pattern | First seen (rid) | Source | Status |
+|---|---|---|---|---|
+| (empty) | — | — | — | — |
+
+The schema for new rows is `{ #, risk pattern, first seen rid, source, status }`.
+The `status` enum is `active` / `mitigated` / `accepted` / `deprecated`.