peaks-loop 4.0.0-beta.3 → 4.0.0-beta.31

package/dist/services/verdict/envelopes.d.ts

@@ -0,0 +1,93 @@
+/**
+ * peaks-loop v2.13.3 — Envelope unification (AC-1: real markdown parse).
+ *
+ * The 5 input envelopes feeding `aggregateVerdict()` have always been
+ * heterogeneous (peaks-security-audit / peaks-perf-audit / karpathy /
+ * peaks-mut / peaks-qa). v2.13.1 shipped precedence wiring without
+ * touching the on-disk shapes. v2.13.2 introduced a discriminated-union
+ * type projection `AnyEnvelope` and 5 pure parser functions.
+ *
+ * v2.13.3 dogfood bug #1: parseSecurity/Perf previously only supported
+ * a JSON.parse path. The real v2.12.0 audit files at
+ * `.peaks/_runtime/<sid>/audit/security.md` and `audit/perf.md` are
+ * YAML frontmatter + markdown body — NOT JSON. The fix preserves
+ * the JSON.parse path (back-compat for unit tests + any consumer that
+ * passed JSON explicitly) and adds a markdown fallback that extracts
+ * `verdict:` from the frontmatter and parses `## Findings` bullets.
+ *
+ * Karpathy §2 (Simplicity First):
+ *   - single file, ~210 lines, zero new IO.
+ *   - re-uses existing strict-shape guards (isSecurityAuditEnvelope /
+ *     isPerfAuditEnvelope) — no duplicate validation logic.
+ *   - parsers return `null` on malformed input (mirrors loadMutReport's
+ *     "missing → null" contract). Callers can detect "envelope missing"
+ *     without throwing.
+ */
+import { type SecurityAuditEnvelope } from 'peaks-loop-audit-independent';
+import { type PerfAuditEnvelope } from 'peaks-loop-audit-independent';
+import { type KarpathyEnvelope, type MutEnvelope, type QaEnvelope, type AggregatorInput } from './verdict-aggregator.js';
+/**
+ * `kind` is the discriminator. The on-disk file format is unchanged;
+ * this field exists only in the TS type projection. The aggregator
+ * accepts both the legacy `{security, perf, ...}` shape and the new
+ * union via a thin adapter (`aggregateFromEnvelopes`).
+ */
+export type AnyEnvelope = {
+    kind: 'security';
+    envelope: SecurityAuditEnvelope;
+} | {
+    kind: 'perf';
+    envelope: PerfAuditEnvelope;
+} | {
+    kind: 'karpathy';
+    envelope: KarpathyEnvelope;
+} | {
+    kind: 'mut';
+    envelope: MutEnvelope;
+} | {
+    kind: 'qa';
+    envelope: QaEnvelope;
+};
+/**
+ * v2.13.3 AC-1 — parse real v2.12.0 audit markdown.
+ *
+ * Strategy (per PRD AC-1 mitigation):
+ *   1. Try JSON.parse first (back-compat with prior unit tests + any
+ *      consumer that passes a JSON string explicitly).
+ *   2. Fall back to markdown parse: extract `verdict:` from YAML
+ *      frontmatter, parse `## Findings` bullets in the body, return
+ *      a SecurityAuditEnvelope.
+ *   3. Return null when neither path yields a valid envelope.
+ */
+export declare function parseSecurityEnvelope(md: string): SecurityAuditEnvelope | null;
+export declare function parsePerfEnvelope(md: string): PerfAuditEnvelope | null;
+/**
+ * Karpathy review is stored as markdown (`.peaks/_runtime/<sid>/rd/karpathy-review.md`).
+ * We parse the 3 state lines that drive the aggregator:
+ *   - `gateAction: pass | warn | block`
+ *   - `verdict: pass | warn | block`  (alias for gateAction)
+ *   - `passed: true | false`
+ * Plus the violations list under a `## Violations` heading, where each
+ * bullet begins with `[SEVERITY] file:line — hint` and declares a
+ * guideline tag like `(simplicity-first)`.
+ */
+export declare function parseKarpathyEnvelope(md: string): KarpathyEnvelope | null;
+/**
+ * Mut envelope is JSON. Mirrors `loadMutReport`'s contract: missing
+ * fields → null. The strict shape matches `MutReportJson` in
+ * `services/mut/types.ts`.
+ */
+export declare function parseMutEnvelope(json: unknown): MutEnvelope | null;
+/**
+ * QA test report is markdown under `qa/test-reports/<rid>.md`.
+ * The verdict line is `verdict: pass | return-to-rd | blocked` and
+ * optionally carries a `reportPath:` line. Anything else → null.
+ */
+export declare function parseQaEnvelope(md: string): QaEnvelope | null;
+/**
+ * Convert a partial list of `AnyEnvelope` values to the legacy
+ * `AggregatorInput` shape. `null` envelopes are skipped (a missing
+ * envelope is treated as "audit not run" — same semantics as
+ * `AggregatorInput` without that key).
+ */
+export declare function envelopesToAggregatorInput(list: ReadonlyArray<AnyEnvelope | null>): AggregatorInput;

package/dist/services/verdict/envelopes.js

@@ -0,0 +1,349 @@
+/**
+ * peaks-loop v2.13.3 — Envelope unification (AC-1: real markdown parse).
+ *
+ * The 5 input envelopes feeding `aggregateVerdict()` have always been
+ * heterogeneous (peaks-security-audit / peaks-perf-audit / karpathy /
+ * peaks-mut / peaks-qa). v2.13.1 shipped precedence wiring without
+ * touching the on-disk shapes. v2.13.2 introduced a discriminated-union
+ * type projection `AnyEnvelope` and 5 pure parser functions.
+ *
+ * v2.13.3 dogfood bug #1: parseSecurity/Perf previously only supported
+ * a JSON.parse path. The real v2.12.0 audit files at
+ * `.peaks/_runtime/<sid>/audit/security.md` and `audit/perf.md` are
+ * YAML frontmatter + markdown body — NOT JSON. The fix preserves
+ * the JSON.parse path (back-compat for unit tests + any consumer that
+ * passed JSON explicitly) and adds a markdown fallback that extracts
+ * `verdict:` from the frontmatter and parses `## Findings` bullets.
+ *
+ * Karpathy §2 (Simplicity First):
+ *   - single file, ~210 lines, zero new IO.
+ *   - re-uses existing strict-shape guards (isSecurityAuditEnvelope /
+ *     isPerfAuditEnvelope) — no duplicate validation logic.
+ *   - parsers return `null` on malformed input (mirrors loadMutReport's
+ *     "missing → null" contract). Callers can detect "envelope missing"
+ *     without throwing.
+ */
+import { isSecurityAuditEnvelope } from 'peaks-loop-audit-independent';
+import { isPerfAuditEnvelope } from 'peaks-loop-audit-independent';
+// ─── 5 parsers (pure, never throw) ─────────────────────────────────────
+/**
+ * v2.13.3 AC-1 — parse real v2.12.0 audit markdown.
+ *
+ * Strategy (per PRD AC-1 mitigation):
+ *   1. Try JSON.parse first (back-compat with prior unit tests + any
+ *      consumer that passes a JSON string explicitly).
+ *   2. Fall back to markdown parse: extract `verdict:` from YAML
+ *      frontmatter, parse `## Findings` bullets in the body, return
+ *      a SecurityAuditEnvelope.
+ *   3. Return null when neither path yields a valid envelope.
+ */
+export function parseSecurityEnvelope(md) {
+    if (typeof md !== 'string' || md.length === 0)
+        return null;
+    // Path 1: JSON (legacy / back-compat)
+    try {
+        const jsonValue = JSON.parse(md);
+        if (isSecurityAuditEnvelope(jsonValue))
+            return jsonValue;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // not JSON — fall through to markdown parse
+    }
+    // Path 2: real v2.12.0 markdown (YAML frontmatter + body)
+    return parseAuditMarkdown(md, isSecurityAuditEnvelope);
+}
+export function parsePerfEnvelope(md) {
+    if (typeof md !== 'string' || md.length === 0)
+        return null;
+    // Path 1: JSON (legacy / back-compat)
+    try {
+        const jsonValue = JSON.parse(md);
+        if (isPerfAuditEnvelope(jsonValue))
+            return jsonValue;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // not JSON — fall through to markdown parse
+    }
+    // Path 2: real v2.12.0 markdown (YAML frontmatter + body)
+    return parseAuditMarkdown(md, isPerfAuditEnvelope);
+}
+/**
+ * Karpathy review is stored as markdown (`.peaks/_runtime/<sid>/rd/karpathy-review.md`).
+ * We parse the 3 state lines that drive the aggregator:
+ *   - `gateAction: pass | warn | block`
+ *   - `verdict: pass | warn | block`  (alias for gateAction)
+ *   - `passed: true | false`
+ * Plus the violations list under a `## Violations` heading, where each
+ * bullet begins with `[SEVERITY] file:line — hint` and declares a
+ * guideline tag like `(simplicity-first)`.
+ */
+export function parseKarpathyEnvelope(md) {
+    if (typeof md !== 'string' || md.length === 0)
+        return null;
+    const gateAction = matchEnum(md, /^\s*(?:gateAction|verdict)\s*:\s*(pass|warn|block)\s*$/m);
+    const passedMatch = md.match(/^\s*passed\s*:\s*(true|false)\s*$/m);
+    if (gateAction === null || passedMatch === null)
+        return null;
+    const violations = parseKarpathyViolations(md);
+    return {
+        passed: passedMatch[1] === 'true',
+        violations,
+        gateAction
+    };
+}
+const KARPATHY_GUIDELINES = [
+    'think-before-coding',
+    'simplicity-first',
+    'surgical-changes',
+    'goal-driven-execution'
+];
+const KARPATHY_SEVERITIES = ['CRITICAL', 'HIGH', 'MED', 'LOW'];
+function parseKarpathyViolations(md) {
+    const section = md.split(/^##\s+Violations\s*$/m)[1];
+    if (section === undefined)
+        return [];
+    const lines = section.split('\n').filter((l) => l.trim().startsWith('- '));
+    const out = [];
+    for (const line of lines) {
+        const m = line.match(/\[(CRITICAL|HIGH|MED|LOW)\]\s+([^:\s]+):(\d+)\s+[—-]\s+(.+?)\s+\((\w[\w-]*)\)/);
+        if (m === null)
+            continue;
+        const [, severity, file, lineNo, hint, guideline] = m;
+        if (severity === undefined || file === undefined || lineNo === undefined || hint === undefined || guideline === undefined)
+            continue;
+        if (!KARPATHY_SEVERITIES.includes(severity))
+            continue;
+        if (!KARPATHY_GUIDELINES.includes(guideline))
+            continue;
+        out.push({
+            guideline: guideline,
+            severity: severity,
+            file,
+            line: parseInt(lineNo, 10),
+            hint: hint.trim()
+        });
+    }
+    return out;
+}
+/**
+ * Mut envelope is JSON. Mirrors `loadMutReport`'s contract: missing
+ * fields → null. The strict shape matches `MutReportJson` in
+ * `services/mut/types.ts`.
+ */
+export function parseMutEnvelope(json) {
+    if (json === null || typeof json !== 'object')
+        return null;
+    const obj = json;
+    if (typeof obj.passed !== 'boolean')
+        return null;
+    if (typeof obj.killRate !== 'number' || !Number.isFinite(obj.killRate))
+        return null;
+    if (typeof obj.weakRate !== 'number' || !Number.isFinite(obj.weakRate))
+        return null;
+    if (!Array.isArray(obj.violations))
+        return null;
+    const violations = [];
+    for (const v of obj.violations) {
+        if (v === null || typeof v !== 'object')
+            return null;
+        const vo = v;
+        if (typeof vo.kind !== 'string')
+            return null;
+        if (typeof vo.actual !== 'number' || typeof vo.threshold !== 'number')
+            return null;
+        violations.push({
+            kind: vo.kind,
+            actual: vo.actual,
+            threshold: vo.threshold
+        });
+    }
+    return {
+        passed: obj.passed,
+        killRate: obj.killRate,
+        weakRate: obj.weakRate,
+        violations
+    };
+}
+/**
+ * QA test report is markdown under `qa/test-reports/<rid>.md`.
+ * The verdict line is `verdict: pass | return-to-rd | blocked` and
+ * optionally carries a `reportPath:` line. Anything else → null.
+ */
+export function parseQaEnvelope(md) {
+    if (typeof md !== 'string' || md.length === 0)
+        return null;
+    const verdict = matchEnum(md, /^\s*verdict\s*:\s*(pass|return-to-rd|blocked)\s*$/m);
+    if (verdict === null)
+        return null;
+    const reportPathMatch = md.match(/^\s*reportPath\s*:\s*(.+?)\s*$/m);
+    return {
+        verdict,
+        ...(reportPathMatch !== null ? { reportPath: reportPathMatch[1].trim() } : {})
+    };
+}
+// ─── Adapter: union → AggregatorInput (zero call-site churn) ──────────
+/**
+ * Convert a partial list of `AnyEnvelope` values to the legacy
+ * `AggregatorInput` shape. `null` envelopes are skipped (a missing
+ * envelope is treated as "audit not run" — same semantics as
+ * `AggregatorInput` without that key).
+ */
+export function envelopesToAggregatorInput(list) {
+    const out = {};
+    for (const item of list) {
+        if (item === null)
+            continue;
+        if (item.kind === 'security')
+            out.security = item.envelope;
+        else if (item.kind === 'perf')
+            out.perf = item.envelope;
+        else if (item.kind === 'karpathy')
+            out.karpathy = item.envelope;
+        else if (item.kind === 'mut')
+            out.mut = item.envelope;
+        else if (item.kind === 'qa')
+            out.qa = item.envelope;
+    }
+    return out;
+}
+/**
+ * Parse a v2.12.0 audit markdown file:
+ *   ---
+ *   schemaVersion: 1
+ *   verdict: warn
+ *   violationsCount: 1
+ *   ---
+ *   ## Summary
+ *   Test security envelope for dogfood.
+ *
+ *   ## Findings
+ *   - HIGH: hardcoded password in src/auth.ts:42
+ *
+ *   ## Verdict
+ *   verdict: warn
+ *   CRITICAL: 0
+ *
+ * Strategy:
+ *   1. Strip YAML frontmatter (`---\n...\n---\n`). The frontmatter
+ *      `verdict:` line is the source of truth — the body's `## Verdict`
+ *      block is corroborating.
+ *   2. Pull `verdict` from frontmatter (regex, line-anchored).
+ *   3. Parse `## Findings` bullets — accept 3 real v2.12.0 shapes:
+ *        a. `- [SEV] dim @ file:line — hint` (rendered by renderSecurityAuditArtifact)
+ *        b. `- HIGH: hint in file:line` (real dogfood fixture shape)
+ *        c. `- (none)` — empty
+ *   4. Build a candidate envelope and run through the strict-shape
+ *      guard. Return null if the guard rejects (per the parser
+ *      contract: parsers never throw).
+ */
+function parseAuditMarkdown(md, guard) {
+    const frontmatterMatch = md.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    // The v2.12.0 audit artifact contract is YAML frontmatter + body.
+    // The CLI also writes a body-only variant (no frontmatter) when the
+    // test fixture author writes `## Verdict\nverdict: warn` directly.
+    // We accept both: frontmatter takes precedence; the body fallback
+    // scans `## Verdict` and its `verdict:` line.
+    let verdict = null;
+    let body = md;
+    if (frontmatterMatch !== null) {
+        const frontmatterRaw = frontmatterMatch[1];
+        body = frontmatterMatch[2];
+        const fm = frontmatterRaw.match(/^\s*verdict\s*:\s*(pass|warn|block)\s*$/m);
+        if (fm !== null)
+            verdict = fm[1];
+    }
+    if (verdict === null) {
+        // Body fallback — pull `verdict:` from the `## Verdict` block (or
+        // the first line-anchored hit, whichever comes first).
+        const verdictSection = body.split(/^##\s+Verdict\s*$/m)[1] ?? body;
+        const vm = verdictSection.match(/^\s*verdict\s*:\s*(pass|warn|block)\s*$/m);
+        if (vm !== null)
+            verdict = vm[1];
+    }
+    if (verdict === null)
+        return null;
+    const summary = extractSection(body, 'Summary') ?? '';
+    const violations = parseFindingBullets(body);
+    const candidate = {
+        verdict,
+        violations,
+        summary
+    };
+    return guard(candidate) ? candidate : null;
+}
+/** Extract the body of a `## Heading` section (text up to the next
+ *  `## ` heading or EOF). Returns null when the heading is absent. */
+function extractSection(body, heading) {
+    const re = new RegExp(`^##\\s+${heading}\\s*$`, 'm');
+    const sectionStart = body.search(re);
+    if (sectionStart === -1)
+        return null;
+    const afterHeading = body.slice(sectionStart).split('\n');
+    // skip the heading line
+    afterHeading.shift();
+    // collect lines until next `## ` heading
+    const lines = [];
+    for (const line of afterHeading) {
+        if (/^##\s+/.test(line))
+            break;
+        lines.push(line);
+    }
+    return lines.join('\n').trim();
+}
+/** Parse `## Findings` bullets. Accepts the 3 real v2.12.0 shapes. */
+function parseFindingBullets(body) {
+    const section = body.split(/^##\s+Findings\s*$/m)[1];
+    if (section === undefined)
+        return [];
+    const lines = section.split('\n').filter((l) => l.trim().startsWith('- '));
+    const out = [];
+    for (const line of lines) {
+        const v = parseFindingBullet(line);
+        if (v !== null)
+            out.push(v);
+    }
+    return out;
+}
+/** Parse a single finding bullet. Returns null on malformed input. */
+function parseFindingBullet(line) {
+    // Shape A (rendered by renderSecurityAuditArtifact): `- [SEV] dim @ file:line — hint`
+    const a = line.match(/^\s*-\s*\[(CRITICAL|HIGH|MED|LOW)\]\s+(\S+)\s+@\s+([^:\s]+):(\d+)\s+[—-]\s+(.+)$/);
+    if (a !== null) {
+        const [, severity, dimension, file, lineNo, hint] = a;
+        if (severity === undefined || dimension === undefined || file === undefined || lineNo === undefined || hint === undefined)
+            return null;
+        return {
+            severity: severity,
+            dimension,
+            file,
+            line: parseInt(lineNo, 10),
+            hint: hint.trim()
+        };
+    }
+    // Shape B (real dogfood fixture): `- SEVERITY: hint in file:line`
+    const b = line.match(/^\s*-\s*(CRITICAL|HIGH|MED|LOW)\s*:\s+(.+?)\s+in\s+([^:\s]+):(\d+)\s*$/);
+    if (b !== null) {
+        const [, severity, hint, file, lineNo] = b;
+        if (severity === undefined || hint === undefined || file === undefined || lineNo === undefined)
+            return null;
+        return {
+            severity: severity,
+            // dogfood fixtures omit dimension — fall back to severity. The
+            // aggregator does not surface the dimension string in its output
+            // (it uses `(security-audit|perf-audit)` as the source), so a
+            // generic fallback is sufficient for the legacy real-file path.
+            dimension: severity.toLowerCase(),
+            file,
+            line: parseInt(lineNo, 10),
+            hint: hint.trim()
+        };
+    }
+    // Shape C (real dogfood fixture, no dimension): `- HIGH: hardcoded password in src/auth.ts:42`
+    // — same regex as Shape B; kept as a separate branch only for the
+    // future dimension-extraction contract. Already covered above.
+    return null;
+}
+function matchEnum(md, regex) {
+    const m = md.match(regex);
+    return m === null ? null : m[1];
+}

package/dist/services/verdict/verdict-aggregator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * peaks-code multi-signal verdict aggregator (v2.13.1 Group A).
+ *
+ * Implements the 4 aggregation rules documented in
+ * `.peaks/project-scan/audit-output-schema.md:66-78` plus 3rd-party
+ * inputs (karpathy / peaks-mut / peaks-qa). The 5 envelopes are
+ * heterogeneous on purpose — v2.13.1 ships precedence, NOT a schema
+ * unification (that's v2.14).
+ *
+ * 4 aggregation rules (verbatim from audit-output-schema.md):
+ *   1. Verdict precedence — `block` > `warn` > `pass`. Top-level
+ *      verdict is the highest input verdict.
+ *   2. CRITICAL count — sum of CRITICAL markers across inputs.
+ *   3. Required fix deduplication — identical `(file, line, hint)`
+ *      tuples from different audits are merged.
+ *   4. Handoff hash consistency — handled by the audit skills
+ *      upstream; the aggregator consumes already-verified envelopes.
+ *
+ * Top-level precedence: `block` > `return-to-rd` > `warn` > `pass`.
+ *
+ * The aggregator is intentionally pure (no I/O, no clock, no
+ * filesystem). v2.13.1 wires the result into micro-cycle.md as the
+ * "re-run reason" payload; v2.14 will wire it into a CLI subcommand.
+ *
+ * Karpathy §1 — Simplicity First:
+ *   - single file, no new imports beyond the existing
+ *     SecurityAuditEnvelope / PerfAuditEnvelope type re-exports.
+ *   - hard precedence; no scoring, no weighting, no RFC voting.
+ */
+import type { SecurityAuditEnvelope } from 'peaks-loop-audit-independent';
+import type { PerfAuditEnvelope } from 'peaks-loop-audit-independent';
+import type { ThresholdViolation } from 'peaks-loop-mut';
+export interface KarpathyViolation {
+    readonly guideline: 'think-before-coding' | 'simplicity-first' | 'surgical-changes' | 'goal-driven-execution';
+    readonly severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    readonly file: string;
+    readonly line: number;
+    readonly hint: string;
+}
+export interface KarpathyEnvelope {
+    readonly passed: boolean;
+    readonly violations: ReadonlyArray<KarpathyViolation>;
+    readonly gateAction: 'pass' | 'warn' | 'block';
+}
+export interface MutEnvelope {
+    readonly passed: boolean;
+    readonly killRate: number;
+    readonly weakRate: number;
+    readonly violations: ReadonlyArray<ThresholdViolation>;
+}
+export interface QaEnvelope {
+    readonly verdict: 'pass' | 'return-to-rd' | 'blocked';
+    readonly reportPath?: string;
+}
+export interface AggregatorInput {
+    readonly security?: SecurityAuditEnvelope;
+    readonly perf?: PerfAuditEnvelope;
+    readonly karpathy?: KarpathyEnvelope;
+    readonly mut?: MutEnvelope;
+    readonly qa?: QaEnvelope;
+}
+export type AggregatorVerdict = 'pass' | 'warn' | 'block' | 'return-to-rd';
+export type VerdictSource = 'security-audit' | 'perf-audit' | 'karpathy-reviewer' | 'peaks-mut' | 'peaks-qa';
+export interface VerdictReason {
+    /**
+     * Primary source — kept for the single-source case. When multiple
+     * sources report the same (file,line,hint) tuple, `sources` carries
+     * the full list and `source` is the first source that triggered the
+     * reason entry (deterministic: security → perf → karpathy order).
+     */
+    readonly source: VerdictSource;
+    /**
+     * v2.13.2 — multi-source carrier. Always non-empty when the reason
+     * was deduped across sources; equals `[source]` for single-source
+     * entries. The dedup key uses (file,line,hint) only — not `source` —
+     * per `.peaks/project-scan/audit-output-schema.md:73`.
+     */
+    readonly sources: ReadonlyArray<VerdictSource>;
+    readonly signal: AggregatorVerdict | 'blocked';
+    readonly severity?: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    readonly file?: string;
+    readonly line?: number;
+    readonly hint?: string;
+    readonly kind?: string;
+    readonly actual?: number;
+    readonly threshold?: number;
+    readonly reportPath?: string;
+}
+export interface AggregatorResult {
+    readonly verdict: AggregatorVerdict;
+    readonly reasons: ReadonlyArray<VerdictReason>;
+}
+export declare const VERDICT_PRECEDENCE: ReadonlyArray<AggregatorVerdict>;
+export declare function aggregateVerdict(input: AggregatorInput): AggregatorResult;