peaks-loop 3.0.0

package/skills/peaks-ide/references/audit-log-helper.md

@@ -0,0 +1,52 @@
+---
+name: peaks-ide-audit-log-helper
+description: Thin Node helper that writes a single JSONL line to `.peaks/audit/peaks-ide-<UTC-date>.log`. Reachable from the peaks-ide SKILL.md Step 5 escape hatch. NOT a `peaks <cmd>` CLI primitive (slice #2 closeout + dev-preference red line).
+---
+
+# peaks-ide audit log helper
+
+The peaks-ide skill's Step 5 (`audit log`) delegates the JSONL write to
+`scripts/peaks-ide-audit-log.mjs`. The helper is a thin Node script, not a
+new `peaks <cmd>`, and is the single source of truth for the audit log
+shape (machine + human readable, one JSON object per line).
+
+## Why a thin helper, not a CLI primitive
+
+Per `.peaks/memory/peaks-ide-skill-ac-10-audit-log-writer-is-a-thin-helper-not-a-separate-cli-primitive.md`
+(slice #2 closeout), the audit log writer is reachable from the skill's
+Step 5 escape hatch but is NOT a new top-level `peaks <cmd>`. The
+`peaks project dashboard` command reads the log via the `audit` scan; the
+helper writes the log. The dev-preference red line "Default-no on new CLI
+commands" still applies — if the audit-trail becomes critical in a future
+slice, the helper can be promoted to a CLI primitive at that point.
+
+## CLI surface
+
+```
+node scripts/peaks-ide-audit-log.mjs --project <repo> --event <name> --adapter <id> [--ok true|false] [--detail <json>] [--dry-run]
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--project <path>` | yes | Target project root (parent of `.peaks/`) |
+| `--event <name>` | yes | Event identifier (`install`, `statusline`, `hook-handle`, ...) |
+| `--adapter <id>` | yes | Adapter id (`claude-code`, `trae`, ...) |
+| `--ok <bool>` | no, default `true` | Outcome flag — `false` to record a failure |
+| `--detail <json>` | no | Free-form JSON object attached to the entry |
+| `--dry-run` | no | Print the would-be line; do not write |
+
+## Log line shape
+
+```json
+{"timestamp":"2026-06-07T16:00:00.000Z","event":"install","adapter":"trae","ok":true}
+```
+
+The log file path is `<projectRoot>/.peaks/audit/peaks-ide-<UTC-date>.log`
+and is gitignored per the repo root `.gitignore` (`.peaks/audit/`).
+
+## Contract pinned by tests
+
+`tests/unit/skills/peaks-ide/audit-log-helper.test.ts` pins 4 sub-cases
+(per AC-5): helper is at the documented path, write emits one JSONL line
+with `timestamp + event + adapter + ok`, the log path is in `.gitignore`,
+and `--dry-run` returns the would-be line without writing.

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

@@ -0,0 +1,166 @@
+---
+name: peaks-perf-audit
+description: Independent performance audit skill. Reads the immutable peaks-prd handoff + the project-level perf-template.md, performs a 6-dimension perf audit, and writes a structured envelope to `.peaks/_runtime/<sessionId>/audit/perf-<rid>.md`. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). Use when the slice introduces CPU-bound hot loops, I/O throughput changes, memory allocation patterns, concurrency model changes, bundle size deltas, or cold-start costs.
+metadata:
+  appliesTo: peaks-cli v2.12.0+
+  replaces: peaks-rd 5-way fan-out perf-baseline-reviewer slot (per AC-3.x)
+  sources:
+    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
+    - template: .peaks/project-scan/perf-template.md (git-tracked, schemaVersion: 1)
+    - output: .peaks/_runtime/<sessionId>/audit/perf-<rid>.md (frontmatter schemaVersion: 1)
+    - schema: .peaks/project-scan/audit-output-schema.md
+---
+
+# peaks-perf-audit
+
+> **Independent performance audit skill** — separate from `peaks-rd`'s
+> in-process `perf-baseline-reviewer` sub-agent. The skill is invoked
+> explicitly via `peaks perf-audit run --rid <id>` and reads the
+> immutable `prd/handoff.md` + the project-level `perf-template.md`
+> to produce a structured `perf-<rid>.md` artifact. Per v2.11.0 D1
+> (immutable handoff) and v2.12.0 AC-3.1~3.7.
+
+## Why a standalone skill (not the 5-way fan-out slot)
+
+The `perf-baseline-reviewer` slot in `peaks-rd`'s 5-way fan-out had two
+structural problems:
+
+1. **Self-deceiving** — RD reviews its own work; the perf baseline is
+   the slice's own `perf-baseline.md`, not a project-level reference.
+2. **No stable baseline** — every slice writes a fresh baseline,
+   paying the same token cost for re-derived thresholds; and
+   recurring patterns (e.g. "Node 22 fs.renameSync on Windows" or
+   "vitest --changed mode") are not accumulated.
+
+v2.12.0 promotes performance review to:
+
+1. **Project-level** — the perf template lives at
+   `.peaks/project-scan/perf-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 perf baselines to
+   the template's `## Known baselines inventory` at session end.
+
+## When to invoke
+
+Invoke this skill when the slice touches any of the 6 perf
+dimensions (full list in the template's `## Perf dimensions`).
+For non-perf-shaped slices (pure docs / chore / config / tests-only),
+the slice MUST NOT invoke this skill — the `perf-audit run` CLI
+exits with `AUDIT_NOT_REQUIRED` (per AC-3.6).
+
+## Workflow (5 steps)
+
+### Step 1 — Detect
+
+```bash
+peaks perf-audit detect --rid <id> --sid <sid> --project <repo>
+```
+
+Calls `detectPerfAudit()` in `src/services/audit-independent/perf-audit-service.ts`.
+Returns a 5-state result (mirrors `detectSecurityAudit`):
+
+| 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/perf-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 |
+| `envelope-malformed` | parent LLM returned non-conforming value | Verify the skill prompt matches AC-3.x output shape |
+
+### Step 2 — Read inputs (handoff + template)
+
+- **Handoff** — the immutable PRD-agreed goal statement. The audit
+  scopes itself to the in-scope surfaces named in the handoff.
+- **Template** — the project-level perf template (6 dimensions +
+  threshold table + measurement methodology). The audit walks every
+  dimension and declares a strategy (EMPIRICAL / STATIC / N/A).
+
+### Step 3 — Audit (parent LLM judgement)
+
+The parent LLM (this skill) walks the diff against the 6 dimensions,
+applying the threshold table from the template. Output is a
+strict-shape envelope (mirrors `SecurityAuditEnvelope`):
+
+```typescript
+interface PerfAuditEnvelope {
+  verdict: 'pass' | 'warn' | 'block';
+  violations: ReadonlyArray<{
+    dimension: string;        // 1 of 6 from template
+    severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    file: string;             // repo-relative
+    line: number;             // 1-based
+    hint: string;             // actionable, <200 chars
+  }>;
+  summary: string;            // 1-paragraph perf narrative
+}
+```
+
+Validation lives in `isPerfAuditEnvelope()` in the service.
+
+### Step 4 — Write artifact
+
+```bash
+peaks perf-audit run --rid <id> --sid <sid> --project <repo> \
+  --envelope @<path-to-envelope.json>
+# or via stdin
+peaks perf-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
+- `## Baseline reference` — link to existing baseline or `N/A — no prior baseline`
+- `## Measurement result` — 6-dim status table
+- `## Threshold check` — measured delta vs. warn/block
+- `## Findings` — bullet list with severity tag
+- `## Required fixes` — actionable bullets
+- `## 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`
+(verdict precedence `block > warn > pass`; CRITICAL counts summed;
+required fixes deduped by `(file, line, hint)`).
+
+## Hard contracts (BLOCKING)
+
+- **No fall-back to inline template** — the skill never synthesizes
+  a perf baseline from scratch. If the template is missing, the CLI
+  exits with `AUDIT_TEMPLATE_MISSING` (per AC-3.5).
+- **No edits to the handoff** — the skill reads the handoff as
+  immutable.
+- **No self-deception** — the skill is invoked **after** `peaks-rd`
+  implementation, not during. The 5-way fan-out's
+  `perf-baseline-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/perf-template.md` (git-tracked)
+- Schema: `.peaks/project-scan/audit-output-schema.md`
+- Service: `src/services/audit-independent/perf-audit-service.ts`
+- CLI: `src/cli/commands/perf-audit-commands.ts`
+- Tests: `tests/unit/services/audit-independent/perf-audit-service.test.ts`
+- Companion: `skills/peaks-security-audit/SKILL.md` (symmetric structure)
+
+## Karpathy alignment
+
+- **#1 Think Before Coding** — `## Red-line scope` of the handoff
+  defines what the audit covers. Out-of-scope findings surface via
+  `nextActions[]`, not violations.
+- **#2 Simplicity First** — the service is ~470 LoC, well below the
+  800-line file cap. Symmetric to security-audit-service.ts; the
+  duplication is intentional (independent type evolution per skill).
+- **#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-perf-audit/references/audit-protocol.md

@@ -0,0 +1,173 @@
+# peaks-perf-audit — Audit Protocol Reference
+
+> **Operational reference** for the `peaks-perf-audit` skill. This file
+> is the parent LLM's step-by-step playbook: how to read the inputs,
+> walk the 6 dimensions, declare a measurement strategy, score
+> severity, and emit the envelope. The service
+> (`perf-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/perf-template.md` | YES | 6 dimensions + threshold table + methodology |
+| 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 |
+| Optional: prior baseline | slice 025 `peaks perf baseline` output | NO | The template's `## Known baselines inventory` references stable baselines; first-run baseline is N/A |
+
+## Output envelope (strict shape)
+
+```typescript
+interface PerfAuditEnvelope {
+  readonly verdict: 'pass' | 'warn' | 'block';
+  readonly violations: ReadonlyArray<{
+    readonly dimension: string;        // 1 of 6 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 perf narrative
+}
+```
+
+The service's `isPerfAuditEnvelope()` rejects any deviation.
+
+## Walking the 6 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. **Declare a strategy** — exactly one of:
+   - `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 (with rationale)` — the dimension does not apply to this
+     slice (e.g. cold-start cost for a CLI subcommand that always
+     runs to completion). Rationale required.
+3. **Measure or estimate** — produce a delta value (e.g. "+15% CPU",
+   "+5% bundle", "static risk: high").
+4. **Compare to threshold** — read the template's threshold table
+   (warn / block) for the dimension and mark the dimension as
+   `clean` / `warn` / `block` / `n/a`.
+5. **Emit violations** — one entry per finding, with `(file, line,
+   hint)` tuple. The triple is the dedup key in the aggregator.
+
+### Dimension-by-dimension checklist
+
+#### 1. CPU-bound path latency (warn +20% / block +50%)
+
+- [ ] New hot loops? O(n²) where O(n) was sufficient?
+- [ ] Regex backtracking risk (nested quantifiers)?
+- [ ] JSON serialization in tight loops?
+- [ ] Sync I/O in async path?
+
+#### 2. I/O throughput (warn +15% / block +40%)
+
+- [ ] File read/write batching: are reads/writes coalesced?
+- [ ] Network round-trips: N+1 query risk?
+- [ ] Stream vs buffer: large file reads streamed or slurped?
+
+#### 3. Memory allocation (warn +25% / block +60%)
+
+- [ ] Large object retention (closures, module-scope caches)?
+- [ ] GC pressure (per-iteration allocations)?
+- [ ] Buffer reuse (manual pools / `Buffer.alloc` vs `Buffer.from`)?
+- [ ] Closure capture (large outer-scope captures)?
+
+#### 4. Concurrency model (warn: microtask saturation / block: >100ms event-loop block)
+
+- [ ] Single-threaded event loop stalls (sync loops, JSON.parse on huge blobs)?
+- [ ] Microtask queue saturation (Promise.all over huge arrays)?
+- [ ] Worker pool sizing (CPU-bound work off-loaded)?
+
+#### 5. Bundle / artifact size (warn +30% / block +80%)
+
+- [ ] Code split chunks: are large libs lazy-loaded?
+- [ ] Dead code: unused exports / polyfills?
+- [ ] Polyfill bloat: ES5 shims in modern targets?
+- [ ] Dependency weight: bloated transitive deps?
+
+#### 6. Cold-start cost (warn +10% / block +25%)
+
+- [ ] First-call latency (eager init of unused modules)?
+- [ ] Module load time (top-level awaits / heavy imports)?
+- [ ] Lazy initialization gaps (eager work in module body)?
+
+## Measurement methodology
+
+Per dimension, the skill chooses **EMPIRICAL / STATIC / N/A** and
+records the strategy in the audit output's `## Measurement result`
+section. EMPIRICAL is preferred when the slice has a runnable
+artifact (binary, library, CLI). STATIC is the fallback.
+
+```bash
+# Empirical examples
+time node ./bin/peaks.js slice check --rid <rid>  # CPU + cold-start
+node --heap-prof ./bin/peaks.js slice check 2>&1 | head -100  # memory
+wc -c dist/peaks.js  # bundle size
+du -sh node_modules/<new-dep>  # dep weight
+```
+
+When the slice has no runnable artifact (pure docs / config / types),
+declare N/A on every dimension with a single rationale.
+
+## Severity scoring
+
+| Severity | Trigger |
+|---|---|
+| `CRITICAL` | Block threshold tripped (e.g. +80% bundle size); direct user-visible perf regression |
+| `HIGH` | Block threshold tripped on a secondary path; or warn threshold tripped by 2x |
+| `MED` | Warn threshold tripped; defense-in-depth; not user-visible today |
+| `LOW` | Style / hygiene; future-risk; not measurable in current scope |
+
+When in doubt, mark one severity lower and add a `Recommended:`
+entry explaining the escalation reason.
+
+## 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 `block` 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 baselines to the template's
+`## Known baselines inventory` table. The skill's `## Recommended`
+section is the source of new sediment rows; the format is:
+
+```
+| # | Baseline | First established (rid) | Source | Status |
+| N | <one-line baseline> | <rid> | peaks-perf-audit | active |
+```
+
+## Failure modes
+
+- **Handoff sha256 mismatch** — `readAndVerifyHandoff` returns null.
+  Surface via `nextActions[]`; do not proceed to step 2.
+- **Template missing** — `readPerfTemplate` returns null. Surface
+  via `nextActions[]` pointing to `peaks project template init`.
+- **Envelope rejected by service** — `isPerfAuditEnvelope` returns
+  false. Re-emit until valid; do not write a malformed artifact.
+
+## Cross-references
+
+- Service: `src/services/audit-independent/perf-audit-service.ts`
+- Template: `.peaks/project-scan/perf-template.md`
+- Schema: `.peaks/project-scan/audit-output-schema.md`
+- Companion: `skills/peaks-security-audit/references/audit-protocol.md`