peaks-loop 3.0.0

package/skills/peaks-sc/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: peaks-sc
+description: Source control, sync, and change-control skill for Peaks. Use when a workflow needs change impact, artifact retention, commit boundaries, GitHub artifact repository pointers, sync state, or rollback evidence.
+---
+
+# Peaks-Cli SC
+
+Peaks-Cli SC records how product, RD, QA, code, and artifacts move together.
+
+## Slice planning first step
+
+The first step in slice planning (before commit-boundary derivation below) is to invoke `peaks-slice-decompose` to produce a v2 topology. The decomposition envelope is the input to every later SC step (impact, retention, boundary). See [peaks-slice-decompose/SKILL.md](../peaks-slice-decompose/SKILL.md).
+
+## Scope directory (slice 10 — read scopeDir from envelope)
+
+The canonical scope dir for this request is provided as `envelope.data.scopeDir` (absolute path). Write all change-id-scoped files under that path. **NEVER** construct paths like `.peaks/_runtime/<sessionId>/...` from frontmatter — the path has already been resolved by the CLI.
+
+## Skill presence (MANDATORY first action)
+
+Before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Read persistent project memory via CLI (durable, LLM-authored memories):
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Cli Skill: peaks-sc | Peaks-Cli Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
+
+## Responsibilities
+
+- produce change-impact artifacts;
+- record commit boundaries;
+- ensure intermediate artifacts are retained locally first;
+- track artifact repository pointers when external sync or git retention is explicitly authorized;
+- record sync state and rollback points.
+
+## Mandatory per-request artifact
+
+Every SC invocation must write a change-control record at `.peaks/_runtime/<sessionId>/sc/change-control/<rid>.md` linking:
+
+- impact evidence (`peaks sc impact` output);
+- retention evidence (`peaks sc retention` output);
+- validation result (`peaks sc validate` output);
+- boundary record (`peaks sc boundary` output).
+
+Solo reads this record before declaring the workflow complete.
+
+## Refactor role
+
+Each refactor slice must leave a traceable local artifact boundary in `.peaks/_runtime/<session-id>/` by default. A git commit boundary containing code changes and PRD/RD/QA/TXT intermediate artifacts is required only when the user or active profile explicitly authorizes committing artifacts.
+
+## GStack integration
+
+Use gstack as a concrete source-control and release workflow reference for the `Ship → Reflect` stages:
+
+- map `/ship` and `/land-and-deploy` concepts to Peaks-Cli commit boundaries, sync state, rollback points, and artifact retention;
+- map checkpoint discipline to traceable code-plus-artifact slices;
+- do not create PRs, merge, deploy, or mutate shared state unless the active Peaks-Cli workflow and user confirmation explicitly allow it.
+
+## Project memory backup
+
+Project `.peaks/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
+
+## Commit boundary derivation
+
+**Primary path — OpenSpec available:** When `openspec/changes/<id>/tasks.md` exists, derive commit boundaries from it:
+
+- `peaks openspec to-rd <id> --project <repo> --json` returns `commitBoundaries[]`, one entry per tasks.md heading.
+- Default to one commit per heading. Each commit message references the change-id and the section heading.
+- If implementation produces diffs outside any todo, surface that as out-of-scope before closing SC.
+
+**Fallback — OpenSpec missing:** When `openspec/` does not exist or `peaks openspec to-rd` fails:
+
+- derive commit boundaries from the RD request artifact's slice spec and the current `git diff --stat`;
+- group changed files by module or feature area, one commit per group;
+- record in the change-control artifact that boundaries were derived from git diff, not OpenSpec, so downstream reviewers know the source.
+
+Concrete rules: `references/openspec-commit-boundaries.md`.
+
+## Default runbook
+
+Use this sequence when SC owns the change-control pass for a refactor or release slice. SC never edits code or tests; it only records boundary evidence through the Peaks-Cli CLI.
+
+```bash
+# 0. Confirm SC's own runbook integrity before recording boundary evidence
+# in:  none
+# out: runbook version, presence set
+peaks skill runbook peaks-sc --json
+peaks skill presence:set peaks-sc --project <repo>  # show persistent skill presence every turn
+
+# 1. Derive commit boundaries (OpenSpec preferred, git diff fallback)
+# in:  change-id, repo path
+# out: commitBoundaries[] or fallback git diff grouping
+peaks openspec to-rd <change-id> --project <repo> --json
+
+# 2. Inventory artifacts already produced by other roles for this session
+# in:  repo path, session-id
+# out: artifact list with paths and statuses
+peaks artifacts status --project <repo> --json
+peaks artifacts workspace --workspace <session-id> --json
+
+# 3. Record change impact for the slice
+# in:  change-id, module, file path
+# out: impact record (JSON)
+peaks sc impact --change-id <change-id> --module <module> --file <path> --json
+
+# 4. Record retention evidence linking PRD / RD / QA artifacts
+# in:  slice-id, artifact paths from other roles
+# out: retention record (JSON)
+peaks sc retention --slice-id <slice-id> --prd <prd-path> --rd <rd-path> --qa <qa-path> --json
+
+# 5. Validate retention completeness
+# in:  slice-id
+# out: validation result (pass/fail + missing items)
+peaks sc validate --slice-id <slice-id> --json
+
+# 6. Record the commit boundary for the slice
+# in:  slice-id, artifact path, code file path
+# out: boundary record (JSON)
+peaks sc boundary --slice-id <slice-id> --artifact <artifact-path> --code <code-file> --json
+
+# 7. Sync memory and artifacts (requires explicit authorization)
+# in:  repo path, workspace
+# out: sync result or dry-run preview
+peaks memory sync --project <repo> --workspace <workspace> --apply --json
+peaks artifacts sync --workspace <workspace> --apply --json
+peaks skill presence:clear --project <repo>                      # SC complete, remove presence indicator
+```
+
+The final two `--apply` calls require explicit authorization. Without it, default to `--dry-run` or omit the sync calls entirely and keep the boundary evidence local under `.peaks/_runtime/<session-id>/`.
+
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare SC complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding.
+
+**Peaks-Cli Gate A — After impact + retention + validate + boundary:**
+```bash
+ls .peaks/_runtime/<sessionId>/sc/change-control/<rid>.md
+# Expected output: .peaks/_runtime/<sessionId>/sc/change-control/<rid>.md
+# "No such file" → STOP, write the change-control record first.
+```
+
+**Peaks-Cli Gate B — Before declaring SC complete (verify commit boundary is recorded):**
+```bash
+git log --oneline -5
+# Expected: at least one recent commit whose message references the change-id or slice-id.
+# No matching commit → STOP, the boundary was not recorded. Re-run steps 3-6.
+```
+
+## Boundaries
+
+Do not implement code or test logic. Do not create GitHub repositories directly from the skill body. Use the Peaks-Cli CLI artifact commands.
+
+Reference: `references/artifact-retention.md`.

package/skills/peaks-sc/references/artifact-contracts.md

@@ -0,0 +1,3 @@
+# artifact-contracts.md
+
+This reference documents artifact-contracts.md for peaks-sc.

package/skills/peaks-sc/references/artifact-retention.md

@@ -0,0 +1,14 @@
+# Artifact Retention
+
+Each refactor slice must retain code and intermediate artifacts together, but the default retention target is local `.peaks/_runtime/<session-id>/` storage rather than git.
+
+## Required retained artifacts
+
+- PRD goal and acceptance artifacts;
+- RD slice spec and task graph;
+- QA coverage and validation reports;
+- TXT context capsule and lessons;
+- SC change impact and sync state;
+- retention-boundary report, including commit details only when commits were explicitly authorized.
+
+The next slice cannot start until code changes and intermediate artifacts are traceable in local `.peaks/_runtime/<session-id>/` storage. Commit or sync those artifacts only after explicit user confirmation or an active profile that clearly authorizes git/external retention.

package/skills/peaks-sc/references/command-migration.md

@@ -0,0 +1,3 @@
+# command-migration.md
+
+This reference documents command-migration.md for peaks-sc.

package/skills/peaks-sc/references/openspec-commit-boundaries.md

@@ -0,0 +1,33 @@
+# OpenSpec-Derived Commit Boundaries for Peaks SC
+
+Peaks SC owns commit boundaries and artifact retention. When the change pack lives in `openspec/changes/<id>/tasks.md`, SC must derive the commit boundaries from that file via the Peaks CLI rather than reinvent them.
+
+## Pulling commit boundary candidates
+
+```bash
+peaks openspec to-rd <change-id> --project <repo> --json
+```
+
+The response includes:
+
+```json
+"commitBoundaries": [
+  { "heading": "1. Discovery", "todos": ["..."], "doneItems": ["..."] },
+  { "heading": "2. Implementation", "todos": ["..."], "doneItems": ["..."] }
+]
+```
+
+Rules SC applies:
+
+- One commit per `heading` is the default. Do not combine unrelated sections into a single commit.
+- `todos[]` items are the in-scope work for that commit. If implementation produced diffs outside any todo description, surface that as an out-of-scope finding before SC closes.
+- `doneItems[]` describes already-shipped sub-tasks; SC may close them out in the same commit only when the current diff actually touches the same surface.
+- Each commit message should reference the change-id and the section heading (e.g. `feat: M3 implement <change-id> 2. Implementation`).
+
+## Wiring with RD slice contracts
+
+When RD has split a change into multiple slices, SC must align each commit with one RD slice and one OpenSpec tasks section. The OpenSpec section heading is the canonical commit boundary name; the RD slice id is the internal reference. If they disagree, return to RD before committing.
+
+## Boundary
+
+SC must not hand-edit `openspec/changes/**` or rewrite history to match a desired boundary. If the OpenSpec tasks list is wrong, raise it as an RD/QA issue and have RD regenerate the change pack through `peaks openspec render` before SC commits.

package/skills/peaks-security-audit/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: peaks-security-audit
+description: Independent security audit skill. Reads the immutable peaks-prd handoff + the project-level security-template.md, performs an OWASP Top-10 + 8-dimension threat model audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/security-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). Use when the slice introduces authn/authz, secrets, input validation, path/filesystem trust, SQL/NoSQL injection, XSS/content injection, dependency supply chain, or external API surface changes.
+metadata:
+  appliesTo: peaks-cli v2.12.0+
+  replaces: peaks-rd 5-way fan-out security-reviewer slot (per AC-2.x)
+  sources:
+    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
+    - template: .peaks/project-scan/security-template.md (git-tracked, schemaVersion: 1)
+    - output: .peaks/_runtime/<sessionId>/audit/security-<rid>.md (frontmatter schemaVersion: 1)
+    - schema: .peaks/project-scan/audit-output-schema.md
+---
+
+# peaks-security-audit
+
+> **Independent security audit skill** — separate from `peaks-rd`'s
+> in-process security-reviewer sub-agent. The skill is invoked explicitly
+> via `peaks security-audit run --rid <id>` and reads the immutable
+> `prd/handoff.md` + the project-level `security-template.md` to produce
+> a structured `security-<rid>.md` artifact. Per v2.11.0 D1 (immutable
+> handoff) and v2.12.0 AC-2.1~2.8.
+
+## Why a standalone skill (not the 5-way fan-out slot)
+
+The `security-reviewer` slot in `peaks-rd`'s 5-way fan-out was a
+**self-deceiving** review (RD reviews its own work, on a per-slice
+basis, every slice paying the same token cost). v2.12.0 promotes
+security review to:
+
+1. **Project-level** — the threat model lives at `.peaks/project-scan/security-template.md`
+   (git-tracked, reviewable in PRs, reusable across slices).
+2. **Handoff-locked** — the audit consumes the immutable `prd/handoff.md`
+   (sha256-verified) so the audit cannot drift from the agreed goals.
+3. **Independent** — invoked explicitly post-`peaks-rd` implementation,
+   not as a sub-agent in the same process tree.
+4. **Sediment-aware** — `peaks-txt` appends new threat patterns to the
+   template's `## Known risks inventory` at session end.
+
+## When to invoke
+
+Invoke this skill when the slice touches any of the 8 threat model
+dimensions (full list in the template's `## Threat model dimensions`).
+For non-security-shaped slices (pure docs / chore / config), the slice
+MUST NOT invoke this skill — the `security-audit run` CLI exits with
+`AUDIT_NOT_REQUIRED` (per AC-2.6).
+
+## Workflow (5 steps)
+
+### Step 1 — Detect (mirrors `detectEcc` from `services/code-review/ecc-bridge.ts`)
+
+```bash
+peaks security-audit detect --rid <id> --sid <sid> --project <repo>
+```
+
+Calls `detectSecurityAudit()` in `src/services/audit-independent/security-audit-service.ts`.
+Returns a 5-state result:
+
+| State | Cause | Action |
+|---|---|---|
+| `ready` | handoff + template + project all present | Proceed to step 2 |
+| `handoff-missing` | `.peaks/_runtime/<sid>/prd/handoff.md` absent | Run `peaks prd handoff init` first |
+| `template-missing` | `.peaks/project-scan/security-template.md` absent | Run `peaks project template init` first |
+| `dispatch-failed` | parent LLM threw before returning envelope | Inspect prompt template; fall back to inline LLM review (degradation note) |
+| `envelope-malformed` | parent LLM returned non-conforming value | Verify the skill prompt matches AC-2.x output shape |
+
+### Step 2 — Read inputs (handoff + template)
+
+Read both inputs via the service (returns null on missing or sha256
+mismatch — see `readAndVerifyHandoff` / `readSecurityTemplate`):
+
+- **Handoff** — the immutable PRD-agreed goal statement. The audit
+  scopes itself to the in-scope surfaces named in the handoff's
+  `## Goals` + `## Acceptance criteria`. The handoff is **not** edited
+  by this skill.
+- **Template** — the project-level threat model (8 dimensions + OWASP
+  Top-10 anchors). The audit walks every dimension and marks each as
+  `clean` / `risk` / `critical` / `n/a (with rationale)`.
+
+### Step 3 — Audit (parent LLM judgement)
+
+The parent LLM (this skill) walks the diff against the 8 dimensions,
+applying the OWASP Top-10 anchors from the template. Output is a
+strict-shape envelope:
+
+```typescript
+interface SecurityAuditEnvelope {
+  verdict: 'pass' | 'warn' | 'block';
+  violations: ReadonlyArray<{
+    dimension: string;        // 1 of 8 from template
+    severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    file: string;             // repo-relative or absolute
+    line: number;             // 1-based
+    hint: string;             // actionable, <200 chars
+  }>;
+  summary: string;            // 1-paragraph risk narrative
+}
+```
+
+Validation lives in `isSecurityAuditEnvelope()` in the service. The
+service **silently drops** non-conforming envelopes; the skill MUST
+re-emit the envelope until it passes validation.
+
+### Step 4 — Write artifact
+
+The service renders the envelope to markdown and writes to
+`.peaks/_runtime/<sid>/audit/security-<rid>.md` (atomic tmp+rename).
+
+```bash
+peaks security-audit run --rid <id> --sid <sid> --project <repo> \
+  --envelope @<path-to-envelope.json>
+# or pipe the envelope via stdin
+peaks security-audit run --rid <id> --sid <sid> --project <repo> < envelope.json
+```
+
+The artifact body has the required sections per `.peaks/project-scan/audit-output-schema.md`:
+
+- `## Summary` — 1-paragraph narrative
+- `## Threat model coverage` — 8-dim status table
+- `## Findings` — bullet list with severity tag
+- `## Required fixes` — actionable bullets
+- `## Recommended` — optional improvements
+- `## Verdict` — block: `verdict: <pass | warn | block>` + `CRITICAL: <n>`
+
+### Step 5 — Hand off
+
+The `peaks-rd` aggregator picks up the artifact from
+`.peaks/_runtime/<sid>/audit/` and folds it into the slice's overall
+`## Verdict` per the aggregation rules in `audit-output-schema.md`:
+
+1. Verdict precedence: `block` > `warn` > `pass`.
+2. CRITICAL counts summed.
+3. Required fixes deduped by `(file, line, hint)`.
+4. Handoff hash consistency: reject if `handoffHash` ≠ canonical.
+
+## Hard contracts (BLOCKING)
+
+- **No fall-back to inline template** — the skill never synthesizes a
+  threat model from scratch. If the template is missing, the CLI exits
+  with `AUDIT_TEMPLATE_MISSING` (per AC-2.5).
+- **No edits to the handoff** — the skill reads the handoff as
+  immutable. Any inconsistency must be surfaced via `nextActions[]`
+  in the detect result, not by editing the handoff.
+- **No self-deception** — the skill is invoked **after** `peaks-rd`
+  implementation, not during. The 5-way fan-out's `security-reviewer`
+  slot is removed in v2.12.0 (Group B Tier 4).
+
+## Cross-references
+
+- PRD handoff: `.peaks/_runtime/<sid>/prd/handoff.md` (sha256-locked)
+- Template: `.peaks/project-scan/security-template.md` (git-tracked)
+- Schema: `.peaks/project-scan/audit-output-schema.md`
+- Service: `src/services/audit-independent/security-audit-service.ts`
+- CLI: `src/cli/commands/security-audit-commands.ts`
+- Tests: `tests/unit/services/audit-independent/security-audit-service.test.ts`
+- Companion: `skills/peaks-perf-audit/SKILL.md` (symmetric structure)
+
+## Karpathy alignment
+
+- **#1 Think Before Coding** — `## Red-line scope` of the handoff
+  defines what the audit covers. The skill surfaces out-of-scope
+  findings as `nextActions[]` rather than silently expanding scope.
+- **#2 Simplicity First** — the service is ~440 LoC, well below the
+  800-line file cap. No speculative features.
+- **#3 Surgical Changes** — the skill does not edit the handoff, the
+  template, or the diff under audit. It only writes a new audit artifact.
+- **#4 Goal-Driven Execution** — every audit output references a
+  verifiable handoff goal via the `handoffHash` field.

package/skills/peaks-security-audit/references/audit-protocol.md

@@ -0,0 +1,175 @@
+# peaks-security-audit — Audit Protocol Reference
+
+> **Operational reference** for the `peaks-security-audit` skill. This
+> file is the parent LLM's step-by-step playbook: how to read the
+> inputs, walk the 8 dimensions, score severity, and emit the envelope.
+> The service (`security-audit-service.ts`) handles the I/O; this
+> reference handles the **judgement**.
+
+## Inputs
+
+| Input | Source | Required | Notes |
+|---|---|---|---|
+| Handoff | `.peaks/_runtime/<sid>/prd/handoff.md` | YES | sha256-locked; verify before reading body |
+| Template | `.peaks/project-scan/security-template.md` | YES | 8 dimensions + OWASP anchors |
+| Diff | git working tree vs. `HEAD` | YES | The slice's changed files |
+| Red-line scope | handoff's `## Red-line scope` | YES | Out-of-scope surfaces go to `nextActions[]`, not violations |
+
+## Output envelope (strict shape)
+
+```typescript
+interface SecurityAuditEnvelope {
+  readonly verdict: 'pass' | 'warn' | 'block';
+  readonly violations: ReadonlyArray<{
+    readonly dimension: string;        // 1 of 8 from template
+    readonly severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    readonly file: string;             // repo-relative
+    readonly line: number;             // 1-based
+    readonly hint: string;             // <200 chars, actionable
+  }>;
+  readonly summary: string;            // 1-paragraph risk narrative
+}
+```
+
+The service's `isSecurityAuditEnvelope()` rejects any deviation. The
+skill MUST re-emit until it passes; if a violation cannot be expressed
+in this shape, surface via `nextActions[]` in the detect result.
+
+## Walking the 8 dimensions
+
+For each dimension, the skill MUST do the following:
+
+1. **Read the dimension's scope** — what files / paths in the diff
+   touch this dimension.
+2. **Apply the OWASP anchor** — use the anchor table in
+   `security-template.md` to map the dimension to the relevant OWASP
+   category.
+3. **Mark the dimension** — exactly one of:
+   - `clean` — no risk; no violations under this dimension.
+   - `risk` — at least one `MED` or `LOW` violation; the dimension
+     stays in the audit but does not block.
+   - `critical` — at least one `HIGH` or `CRITICAL` violation; the
+     dimension is escalated.
+   - `n/a (with rationale)` — the dimension does not apply to this
+     slice; rationale required (e.g. "no external API surface
+     touched").
+4. **Emit violations** — one entry per finding, with `(file, line,
+   hint)` tuple. The `(file, line, hint)` triple is the dedup key in
+   the aggregator.
+
+### Dimension-by-dimension checklist
+
+#### 1. Authentication & authorization (OWASP A01:2021)
+
+- [ ] Login flow's session lifecycle (create / refresh / expire)
+- [ ] Token scope checks; RBAC enforcement
+- [ ] Authorization on every state-changing route
+- [ ] Failure modes: invalid token, expired token, revoked token
+
+#### 2. Secrets management (OWASP A02 + A07:2021)
+
+- [ ] No hardcoded credentials in code or test fixtures
+- [ ] Env vars for secrets, never inlined
+- [ ] Secret rotation policy
+- [ ] Vault integration (or equivalent); no plaintext secret storage
+
+#### 3. Input validation (OWASP A03:2021)
+
+- [ ] Request body validation at the boundary (zod / valibot / etc.)
+- [ ] Query param parsing with type coercion
+- [ ] Allowlist over denylist for untrusted strings
+- [ ] Length limits, charset restrictions, recursive structure caps
+
+#### 4. Path traversal & filesystem trust (OWASP A01 + A03:2021)
+
+- [ ] Path normalization (`path.resolve` or equivalent)
+- [ ] Symlink handling; `realpath` resolution
+- [ ] Parent dir escape prevention (no `..` leak)
+- [ ] Filesystem trust: which paths are user-controlled?
+
+#### 5. SQL/NoSQL injection (OWASP A03:2021)
+
+- [ ] Parameter binding for all queries
+- [ ] No raw concatenation in query construction
+- [ ] ORM usage consistent; raw queries only with parameter binding
+- [ ] For NoSQL: object key injection (`$gt`, `$ne`) blocked
+
+#### 6. XSS & content injection (OWASP A03:2021)
+
+- [ ] Output encoding at the sink (not the source)
+- [ ] CSP headers set; `default-src 'self'` baseline
+- [ ] Sanitization at the rendering layer
+- [ ] URL context escaping for `href` / `src`
+
+#### 7. Dependency supply chain (OWASP A06:2021)
+
+- [ ] Lockfile drift; `npm ci` reproducible
+- [ ] No abandoned packages (last release >2 years + unpatched CVE)
+- [ ] Transitive deps: no known unpatched CVEs
+- [ ] Pin major versions; allow patch + minor
+
+#### 8. External API surface (OWASP A10:2021)
+
+- [ ] Egress auth (mTLS / bearer / signed requests)
+- [ ] SSRF guards: no user-controlled URLs in fetch()
+- [ ] Response validation (shape + status)
+- [ ] Timeout + retry with backoff; circuit breaker for repeated failure
+
+## Severity scoring
+
+| Severity | Trigger |
+|---|---|
+| `CRITICAL` | Direct exploit path in the in-scope surface; no preconditions; data exfiltration or RCE |
+| `HIGH` | Exploit path with preconditions (e.g. authenticated user, specific config); or auth bypass on non-sensitive operation |
+| `MED` | Hardening gap; defense-in-depth; not directly exploitable |
+| `LOW` | Style / hygiene; future-risk; not exploitable in current scope |
+
+When in doubt, mark one severity lower and add a `Recommended:` entry
+explaining the escalation reason. Do not over-flag.
+
+## Verdict aggregation
+
+| Condition | Verdict |
+|---|---|
+| Any `CRITICAL` violation | `block` |
+| Any `HIGH` violation (no `CRITICAL`) | `block` |
+| Any `MED` violation (no `HIGH` / `CRITICAL`) | `warn` |
+| Only `LOW` violations | `warn` |
+| No violations | `pass` |
+
+A dimension marked `critical` MUST produce at least one `HIGH` or
+`CRITICAL` violation; otherwise the dimension marking is inconsistent
+and the skill re-marks.
+
+## Sediment (peaks-txt handoff)
+
+At session end, `peaks-txt` sediment step (Group C) appends new
+recurring risk patterns to the template's
+`## Known risks inventory` table. The skill's `## Recommended` section
+is the source of new sediment rows; the format is:
+
+```
+| # | Risk pattern | First seen (rid) | Source | Status |
+| N | <one-line pattern> | <rid> | peaks-security-audit | active |
+```
+
+The schema for new rows is documented in the template itself.
+
+## Failure modes
+
+- **Handoff sha256 mismatch** — `readAndVerifyHandoff` returns null.
+  The skill MUST surface this via `nextActions[]` in the detect
+  result; do not proceed to step 2.
+- **Template missing** — `readSecurityTemplate` returns null. The
+  skill surfaces via `nextActions[]` pointing to
+  `peaks project template init`.
+- **Envelope rejected by service** — `isSecurityAuditEnvelope` returns
+  false. The skill re-emits until valid; do not write a malformed
+  artifact.
+
+## Cross-references
+
+- Service: `src/services/audit-independent/security-audit-service.ts`
+- Template: `.peaks/project-scan/security-template.md`
+- Schema: `.peaks/project-scan/audit-output-schema.md`
+- Companion: `skills/peaks-perf-audit/references/audit-protocol.md`