peaks-loop 3.0.0

package/dist/src/services/audit/static-service.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Static audit service — `peaks audit static`.
+ *
+ * Slice #6 L2.3 P2-a: soft-optional ECC AgentShield integration.
+ *
+ * Per spec §5.3, the audit framework integrates with ECC AgentShield
+ * (102 lint rules) on a soft-optional basis. When ECC is installed
+ * AND `agentShieldEnabled: true`, the audit subprocess spawns the
+ * ECC scanner and merges its findings; when either is missing, the
+ * audit completes with peaks-cli-only findings.
+ *
+ * The subprocess is **observability enhancement**, not a structural
+ * gate — every soft-fail path returns a well-formed audit report.
+ */
+import { type ProseRatioResult } from './prose-ratio-calculator.js';
+import type { EnforcerFinding, RedLineAudit } from './types.js';
+export interface StaticAuditInput {
+    readonly projectRoot: string;
+    /** Override the preference for a single call. Default: read from preferences. */
+    readonly enableAgentShield?: boolean | undefined;
+    /**
+     * Optional subprocess runner injection point. Used by tests
+     * to mock `npx ecc-agentshield`. Production callers should
+     * leave this undefined; the default uses `child_process.spawnSync`.
+     */
+    readonly subprocessRunner?: SubprocessRunner | undefined;
+}
+export interface StaticAuditResult {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+    readonly warnings: readonly string[];
+    /** v2.14.0 Slice C: prose-only ratio with informational exclusion (per A3.1). */
+    readonly proseRatio: ProseRatioResult;
+}
+export interface AgentShieldState {
+    /** Whether the agent-shield subprocess was spawned. */
+    readonly spawned: boolean;
+    /** Whether ECC AgentShield is installed (regardless of whether it was spawned). */
+    readonly installed: boolean;
+    /** Why the subprocess was or was not spawned. */
+    readonly reason: 'enabled-and-installed' | 'disabled-by-preference' | 'flag-disabled' | 'flag-enabled-but-ecc-missing' | 'disabled-and-ecc-missing';
+    /** The merged ECC findings (empty if not spawned). */
+    readonly findings: readonly EnforcerFinding[];
+}
+/**
+ * Subprocess runner interface — the only seam tests need to
+ * mock the `npx ecc-agentshield` subprocess. Production callers
+ * leave `subprocessRunner` undefined; the default delegates to
+ * `child_process.spawnSync` (synchronous, captures stdout).
+ */
+export interface SubprocessRunner {
+    run(command: string, args: readonly string[], timeoutMs: number): SubprocessResult;
+}
+export interface SubprocessResult {
+    readonly status: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly error?: Error;
+}
+export declare function runStaticAudit(input: StaticAuditInput): StaticAuditResult;

package/dist/src/services/audit/static-service.js

@@ -0,0 +1,130 @@
+/**
+ * Static audit service — `peaks audit static`.
+ *
+ * Slice #6 L2.3 P2-a: soft-optional ECC AgentShield integration.
+ *
+ * Per spec §5.3, the audit framework integrates with ECC AgentShield
+ * (102 lint rules) on a soft-optional basis. When ECC is installed
+ * AND `agentShieldEnabled: true`, the audit subprocess spawns the
+ * ECC scanner and merges its findings; when either is missing, the
+ * audit completes with peaks-cli-only findings.
+ *
+ * The subprocess is **observability enhancement**, not a structural
+ * gate — every soft-fail path returns a well-formed audit report.
+ */
+import { spawnSync } from 'node:child_process';
+import { runRedLinesAudit } from './red-lines-service.js';
+import { loadPreferences } from '../preferences/preferences-service.js';
+import { computeProseRatio } from './prose-ratio-calculator.js';
+const ECC_DETECT_TIMEOUT_MS = 5000;
+const ECC_SCAN_TIMEOUT_MS = 30000;
+const defaultSubprocessRunner = {
+    run(command, args, timeoutMs) {
+        try {
+            const r = spawnSync(command, args, {
+                timeout: timeoutMs,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+                maxBuffer: 16 * 1024 * 1024,
+            });
+            return {
+                status: r.status,
+                stdout: r.stdout ?? '',
+                stderr: r.stderr ?? '',
+            };
+        }
+        catch (err) {
+            return {
+                status: null,
+                stdout: '',
+                stderr: '',
+                error: err,
+            };
+        }
+    },
+};
+function isEccInstalled(runner) {
+    const result = runner.run('npx', ['ecc-agentshield', '--version'], ECC_DETECT_TIMEOUT_MS);
+    if (result.error)
+        return false;
+    return result.status === 0;
+}
+function runEccScan(projectRoot, runner) {
+    try {
+        // Per spec §7.2 line 828: the canonical ECC subprocess call uses
+        // `--target <path>`, NOT `--project`. The peaks-cli CLI flag
+        // (`peaks audit static --project <path>`) follows peaks-cli
+        // convention; the inner ecc-agentshield call follows the
+        // upstream ECC contract.
+        const result = runner.run('npx', ['ecc-agentshield', 'scan', '--json', '--target', projectRoot], ECC_SCAN_TIMEOUT_MS);
+        if (result.error || result.status !== 0)
+            return [];
+        const stdout = result.stdout;
+        let parsed;
+        try {
+            parsed = JSON.parse(stdout);
+        }
+        catch {
+            return [];
+        }
+        if (!parsed.findings)
+            return [];
+        return parsed.findings.map((f, idx) => ({
+            enforcerId: `ecc-agentshield:${f.ruleId ?? `unknown-${idx}`}`,
+            rule: f.rule ?? 'ECC AgentShield rule',
+            severity: f.severity ?? 'warn',
+            file: f.file ?? '(unknown)',
+            detail: f.detail ?? '',
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export function runStaticAudit(input) {
+    // Read the project-local preferences; the CLI flag overrides.
+    const prefs = loadPreferences(input.projectRoot);
+    const prefEnabled = prefs.agentShieldEnabled;
+    const flagEnabled = input.enableAgentShield;
+    const runner = input.subprocessRunner ?? defaultSubprocessRunner;
+    // Resolve the effective "should spawn" decision.
+    // flagEnabled (CLI override) > preference > false
+    const shouldSpawn = flagEnabled ?? prefEnabled;
+    // Detect ECC.
+    const installed = isEccInstalled(runner);
+    const warnings = [];
+    let state;
+    if (!shouldSpawn) {
+        // Disabled path — no subprocess, no warnings.
+        const reason = flagEnabled === false
+            ? 'flag-disabled'
+            : 'disabled-by-preference';
+        state = { spawned: false, installed, reason, findings: [] };
+    }
+    else if (!installed) {
+        // Enabled but ECC missing — soft-fail with a warning.
+        warnings.push('agentShieldEnabled is true but `npx ecc-agentshield --version` failed. ' +
+            'Run `npx ecc-agentshield --help` to install. Audit ran with peaks-cli findings only.');
+        state = { spawned: false, installed: false, reason: 'flag-enabled-but-ecc-missing', findings: [] };
+    }
+    else {
+        // Enabled and installed — spawn the subprocess.
+        const findings = runEccScan(input.projectRoot, runner);
+        state = { spawned: true, installed: true, reason: 'enabled-and-installed', findings };
+    }
+    // Always run the peaks-cli lint layer; merge ECC findings.
+    const peaksResult = runRedLinesAudit({ projectRoot: input.projectRoot });
+    const mergedAudit = {
+        ...peaksResult.audit,
+        enforcerFindings: [...peaksResult.audit.enforcerFindings, ...state.findings],
+    };
+    // v2.14.0 Slice C: compute prose-only ratio with informational
+    // exclusion. Surfaced in the JSON envelope so CI can gate on it.
+    const proseRatio = computeProseRatio(mergedAudit.audit);
+    return {
+        audit: mergedAudit,
+        agentShield: state,
+        warnings,
+        proseRatio,
+    };
+}

package/dist/src/services/audit/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Red-line audit framework — types.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5
+ * PRD:  .peaks/_runtime/2026-06-11-session-f0312d/prd/requests/001-001-l2-1-redlines-audit.md
+ * OpenSpec: openspec/changes/2026-06-11-l2-1-redlines-audit/
+ *
+ * The audit framework classifies MANDATORY / BLOCKING / MUST NOT / RED LINE
+ * markers across skills/, .claude/rules/, and openspec/changes/. Each
+ * discovered red line is tagged with its backing (cli-backed / partial /
+ * prose-only) so the L2 redesign can track the prose-only ratio over time.
+ */
+export type RedLineMarker = 'MANDATORY' | 'BLOCKING' | 'MUST NOT' | 'RED LINE';
+export type RedLineBacking = 'cli-backed' | 'partial' | 'prose-only';
+export interface RedLineSource {
+    /** Path relative to project root, posix-style (forward slashes). */
+    readonly file: string;
+    readonly line: number;
+    readonly marker: RedLineMarker;
+    /** ±2 lines of surrounding context for human review. */
+    readonly context: string;
+}
+export interface RedLineEntry {
+    /** Stable id, e.g. "rl-solo-code-ban-001". */
+    readonly id: string;
+    /** Human-readable rule name, e.g. "Solo Code-Change Red Line". */
+    readonly rule: string;
+    readonly source: RedLineSource;
+    readonly backing: RedLineBacking;
+    /** Relative path to the enforcement file, or null when prose-only. */
+    readonly enforcerRef: string | null;
+    /**
+     * v2.12.1 catalog governance: `true` for entries that are
+     * advisory / educational / "discovered-but-not-yet-enforced" and
+     * therefore should NOT count toward the prose-only ratio (per spec
+     * §10.2 L2 acceptance ≤ 5%). Defaults to `false`; the classifier
+     * sets it to `true` for auto-discovered prose-only entries (those
+     * without a catalog match, since they have no enforcer template
+     * to promote to). Callers that want strict accounting can still
+     * read `backing === 'prose-only'` and filter manually.
+     *
+     * Why: the pre-v2.12.1 catalog treated every MANDATORY/BLOCKING
+     * phrase in SKILL.md as a "red line", which produced a 60.1%
+     * prose-only ratio (89/148) for what is mostly LLM behavior
+     * guidance, not machine-enforceable rules. See
+     * `.peaks/memory/2026-06-27-prose-only-catalog-followup.md`.
+     */
+    readonly informational?: boolean;
+}
+export interface RedLineAudit {
+    readonly totalRedLines: number;
+    readonly cliBacked: number;
+    readonly partial: number;
+    readonly proseOnly: number;
+    readonly audit: readonly RedLineEntry[];
+    /** Findings from running the 7 file-system enforcers during the scan (L2.4 P2-b). */
+    readonly enforcerFindings: readonly EnforcerFinding[];
+}
+/**
+ * Enforcer finding — emitted by an enforcer function that runs as part
+ * of the audit scan. Distinct from `RedLineEntry` (which is catalog-matched
+ * markdown text). L2.4 P2-b ships this dimension: the audit framework
+ * actually invokes the 7 file-system enforcers during a scan, not just
+ * catalogs them.
+ */
+export type EnforcerFindingSeverity = 'pass' | 'warn' | 'fail';
+export interface EnforcerFinding {
+    readonly enforcerId: string;
+    readonly rule: string;
+    readonly severity: EnforcerFindingSeverity;
+    readonly file: string;
+    readonly detail: string;
+}
+/**
+ * A single markdown line discovered by a tree scanner. The classifier turns
+ * these into RedLineEntry by matching against the red-line catalog.
+ */
+export interface MarkdownLine {
+    readonly file: string;
+    readonly line: number;
+    readonly text: string;
+}
+export interface ScanWarning {
+    readonly file: string;
+    readonly message: string;
+}

package/dist/src/services/audit/types.js

@@ -0,0 +1,13 @@
+/**
+ * Red-line audit framework — types.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5
+ * PRD:  .peaks/_runtime/2026-06-11-session-f0312d/prd/requests/001-001-l2-1-redlines-audit.md
+ * OpenSpec: openspec/changes/2026-06-11-l2-1-redlines-audit/
+ *
+ * The audit framework classifies MANDATORY / BLOCKING / MUST NOT / RED LINE
+ * markers across skills/, .claude/rules/, and openspec/changes/. Each
+ * discovered red line is tagged with its backing (cli-backed / partial /
+ * prose-only) so the L2 redesign can track the prose-only ratio over time.
+ */
+export {};

package/dist/src/services/audit-independent/perf-audit-service.d.ts

@@ -0,0 +1,151 @@
+/**
+ * peaks-perf-audit service — independent performance audit skill driver.
+ *
+ * Slice v2.12.0 (Group A, Tier 3). Symmetric to security-audit-service.ts:
+ *   - 5-state detection of the perf-audit runtime
+ *   - Loading + sha256 verification of the prd/handoff.md
+ *   - Loading the project-level perf-template.md
+ *   - Producing the audit envelope (verdict + violations) to write
+ *     to `.peaks/_runtime/<sid>/audit/perf-<rid>.md`
+ *
+ * The actual LLM-in-loop audit step is NOT in this service — the
+ * parent LLM (peaks-perf-audit skill prompt) reads the template,
+ * runs the audit, and returns a structured envelope. This service
+ * is the pure I/O + validation core; the LLM is the judgement core.
+ *
+ * Cross-references:
+ *   - PRD: `.peaks/_runtime/<sid>/prd/handoff.md` (sha256-locked, schemaVersion: 2)
+ *   - Template: `.peaks/project-scan/perf-template.md`
+ *   - Output: `.peaks/_runtime/<sid>/audit/perf-<rid>.md`
+ *   - Schema: `.peaks/project-scan/audit-output-schema.md` (schemaVersion: 1)
+ *   - Companion: `src/services/audit-independent/security-audit-service.ts`
+ */
+/**
+ * 5-state detection result. Mirrors `SecurityAuditDetectState` and
+ * the ecc-bridge `detectEcc` shape (slice 7 Group D).
+ *
+ *   - `ready`              — handoff + template + project all present
+ *   - `handoff-missing`    — `.peaks/_runtime/<sid>/prd/handoff.md` absent
+ *   - `template-missing`   — `.peaks/project-scan/perf-template.md` absent
+ *   - `dispatch-failed`    — parent LLM threw before returning the audit envelope
+ *   - `envelope-malformed` — parent LLM returned a value that fails `isPerfAuditEnvelope`
+ */
+export type PerfAuditDetectState = 'ready' | 'handoff-missing' | 'template-missing' | 'dispatch-failed' | 'envelope-malformed';
+export interface PerfAuditDetectResult {
+    readonly state: PerfAuditDetectState;
+    readonly handoffPresent: boolean;
+    readonly templatePresent: boolean;
+    readonly warnings: readonly string[];
+    readonly nextActions: readonly string[];
+}
+export type PerfAuditVerdict = 'pass' | 'warn' | 'block';
+export interface PerfAuditViolation {
+    readonly dimension: string;
+    readonly severity: 'CRITICAL' | 'HIGH' | 'MED' | 'LOW';
+    readonly file: string;
+    readonly line: number;
+    readonly hint: string;
+}
+export interface PerfAuditEnvelope {
+    readonly verdict: PerfAuditVerdict;
+    readonly violations: ReadonlyArray<PerfAuditViolation>;
+    readonly summary: string;
+}
+/**
+ * Validate a raw value as a PerfAuditEnvelope. Mirrors the
+ * `isSecurityAuditEnvelope` strict-shape pattern.
+ */
+export declare function isPerfAuditEnvelope(value: unknown): value is PerfAuditEnvelope;
+/**
+ * Handoff frontmatter — minimal projection of peaks-prd v2.11.0 handoff
+ * frontmatter. We only need sha256 for verification; the rest of the
+ * handoff body is consumed by the parent LLM, not by this service.
+ *
+ * Symmetric to `HandoffFrontmatter` in `security-audit-service.ts`.
+ * We duplicate the type (rather than share) so the two services
+ * can be independently type-evolved.
+ */
+export interface HandoffFrontmatter {
+    readonly sha256: string;
+    readonly schemaVersion: number;
+}
+/**
+ * Read the peaks-prd handoff frontmatter + body, verify sha256 matches
+ * the body. Returns null on missing file or sha256 mismatch; otherwise
+ * returns the parsed frontmatter + body string.
+ *
+ * Defensive: we read frontmatter via a 1-line regex match, not via
+ * a YAML parser. The handoff service (`src/services/prd/handoff-service.ts`)
+ * is the canonical writer; we only consume its output here.
+ */
+export declare function readAndVerifyHandoff(handoffPath: string, projectRoot: string): {
+    frontmatter: HandoffFrontmatter;
+    body: string;
+} | null;
+/**
+ * Read the project-level perf-template.md. Returns the body
+ * string (with frontmatter stripped) or null if the file is absent.
+ * Does NOT validate the template content; the parent LLM validates
+ * by reading.
+ */
+export declare function readPerfTemplate(projectRoot: string): string | null;
+/**
+ * 5-state detector. The parent skill inspects the state and either
+ * proceeds (when `ready`) or records a degradation note and falls
+ * back (when any other state).
+ *
+ * Soft-fail policy mirrors `detectEcc` (slice 7 Group D) and
+ * `detectSecurityAudit`: the CLI never throws; it returns a typed
+ * detect result.
+ */
+export declare function detectPerfAudit(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly dispatchError?: unknown;
+    readonly envelope?: unknown;
+}): PerfAuditDetectResult;
+/**
+ * Render a PerfAuditEnvelope to the canonical audit artifact body
+ * (markdown). Mirrors `renderSecurityAuditArtifact` in
+ * `security-audit-service.ts` and `adaptEccEnvelopeToRdCodeReview`
+ * in ecc-bridge.ts: produce a markdown body with all required
+ * sections, ready to write to
+ * `.peaks/_runtime/<sid>/audit/perf-<rid>.md`.
+ */
+export declare function renderPerfAuditArtifact(env: PerfAuditEnvelope, opts: {
+    rid: string;
+    handoffHash: string;
+    generatedAt: string;
+}): {
+    body: string;
+    violationsCount: number;
+    verdict: PerfAuditVerdict;
+};
+/**
+ * Write the rendered audit artifact to
+ * `.peaks/_runtime/<sid>/audit/perf-<rid>.md`.
+ *
+ * Atomic write (tmp + rename) to avoid partial writes on crash.
+ * Returns the absolute path on success.
+ */
+export declare function writePerfAuditArtifact(projectRoot: string, sessionId: string, rid: string, body: string): string;
+/**
+ * Convenience: run `detectPerfAudit` + `renderPerfAuditArtifact`
+ * + `writePerfAuditArtifact` in one call.
+ *
+ * Returns `{ detect, artifactPath, violationsCount, verdict }` or
+ * `{ detect, artifactPath: null, ... }` when not ready.
+ */
+export declare function runPerfAudit(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly rid: string;
+    readonly generatedAt: string;
+    readonly dispatchError?: unknown;
+    readonly envelope?: unknown;
+}): {
+    detect: PerfAuditDetectResult;
+    artifactPath: string | null;
+    violationsCount: number;
+    verdict: PerfAuditVerdict | null;
+};