peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/audit/scanners/skills-tree-scanner.js

@@ -0,0 +1,68 @@
+/**
+ * skills-tree-scanner — walks each `skills/<name>/SKILL.md` and returns
+ * each file's raw lines for the classifier to consume.
+ *
+ * Per `static-scan-must-cover-skills-tree-not-just-src.md`, the red-line
+ * audit MUST cover the skills tree, not just `src/`. This scanner is the
+ * entry point for that coverage.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const SKILLS_DIR = 'skills';
+function readSkillFile(projectRoot, skillDir, file) {
+    const fullPath = join(projectRoot, SKILLS_DIR, skillDir, file);
+    if (!existsSync(fullPath))
+        return [];
+    const rel = relative(projectRoot, fullPath).split('\\').join('/');
+    const content = readFileSync(fullPath, 'utf-8');
+    const lines = content.split(/\r?\n/);
+    return lines.map((text, idx) => ({ file: rel, line: idx + 1, text }));
+}
+export function scanSkillsTree(input) {
+    const skillsRoot = join(input.projectRoot, SKILLS_DIR);
+    if (!existsSync(skillsRoot)) {
+        return { lines: [], warnings: [] };
+    }
+    const lines = [];
+    const warnings = [];
+    let entries;
+    try {
+        entries = readdirSync(skillsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        warnings.push({
+            file: SKILLS_DIR,
+            message: `readdir failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return { lines, warnings };
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        // LLM-internal skills live under `skills/bee/<name>/` per spec 2026-07-05.
+        // Recurse one level into `bee/` to cover all 9 demoted role/audit skills.
+        if (entry.name === 'bee') {
+            let subEntries;
+            try {
+                subEntries = readdirSync(join(skillsRoot, 'bee'), { withFileTypes: true });
+            }
+            catch (error) {
+                warnings.push({
+                    file: 'skills/bee',
+                    message: `readdir failed: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            for (const subEntry of subEntries) {
+                if (!subEntry.isDirectory() || subEntry.name.startsWith('.'))
+                    continue;
+                const skillMd = readSkillFile(input.projectRoot, join('bee', subEntry.name), 'SKILL.md');
+                lines.push(...skillMd);
+            }
+            continue;
+        }
+        const skillMd = readSkillFile(input.projectRoot, entry.name, 'SKILL.md');
+        lines.push(...skillMd);
+    }
+    return { lines, warnings };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Static audit service — `peaks audit static`.
+ *
+ * Slice 3 of 4.0.0-beta.11 dropped the ECC AgentShield subprocess
+ * integration entirely. The pre-Slice-3 implementation probed
+ * `npx ecc-agentshield --version` and shelled out to
+ * `npx ecc-agentshield scan --json --target <path>` on every audit
+ * call, but the upstream `affaan-m/everything-claude-code` v2.0.0
+ * release ships no `ecc-agentshield` binary — the repo is
+ * `agents/*.md` flat files plus SKILL.md descriptors.
+ *
+ * The new contract: `peaks audit static` runs the peaks-loop lint
+ * layer only. There is no subprocess probe, no `installed` flag,
+ * no agent-shield reason code. The `agentShield` field is preserved
+ * on the result type as a frozen "always disabled" stub so any
+ * downstream consumer keeps compiling, but the merged findings list
+ * is always the peaks-loop findings list (no ECC findings).
+ *
+ * The subprocess-runner seam (`SubprocessRunner`, `defaultSubprocessRunner`)
+ * is preserved as an EXPORTED TYPE so legacy tests can still
+ * mock it; the runner itself is never invoked from production code.
+ */
+import { type ProseRatioResult } from './prose-ratio-calculator.js';
+import type { EnforcerFinding, RedLineAudit } from './types.js';
+export interface StaticAuditInput {
+    readonly projectRoot: string;
+    /** Slice 3: retained for backward-compat; no longer wired. */
+    readonly enableAgentShield?: boolean | undefined;
+    /** Slice 3: retained as a type seam; never invoked in production. */
+    readonly subprocessRunner?: SubprocessRunner | undefined;
+}
+export interface StaticAuditResult {
+    readonly audit: RedLineAudit;
+    readonly agentShield: AgentShieldState;
+    readonly warnings: readonly string[];
+    readonly proseRatio: ProseRatioResult;
+}
+/**
+ * Frozen stub. Slice 3 collapsed the agent-shield reason set to a
+ * single value (`'disabled-and-ecc-missing'`) because the
+ * subprocess integration was removed; we preserve the other
+ * reason literals as TYPE-LEVEL members so any test or
+ * downstream consumer that pattern-matches on `'flag-enabled-but-ecc-missing'`
+ * keeps type-checking, but the runtime value is always the
+ * single collapsed state.
+ */
+export interface AgentShieldState {
+    readonly spawned: false;
+    readonly installed: false;
+    readonly reason: 'enabled-and-installed' | 'disabled-by-preference' | 'flag-disabled' | 'flag-enabled-but-ecc-missing' | 'disabled-and-ecc-missing';
+    readonly findings: readonly EnforcerFinding[];
+}
+/**
+ * Subprocess runner interface — preserved as a TYPE for legacy
+ * test code. Production no longer invokes it; the audit always
+ * runs peaks-loop-only findings.
+ */
+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/services/audit/static-service.js

@@ -0,0 +1,51 @@
+/**
+ * Static audit service — `peaks audit static`.
+ *
+ * Slice 3 of 4.0.0-beta.11 dropped the ECC AgentShield subprocess
+ * integration entirely. The pre-Slice-3 implementation probed
+ * `npx ecc-agentshield --version` and shelled out to
+ * `npx ecc-agentshield scan --json --target <path>` on every audit
+ * call, but the upstream `affaan-m/everything-claude-code` v2.0.0
+ * release ships no `ecc-agentshield` binary — the repo is
+ * `agents/*.md` flat files plus SKILL.md descriptors.
+ *
+ * The new contract: `peaks audit static` runs the peaks-loop lint
+ * layer only. There is no subprocess probe, no `installed` flag,
+ * no agent-shield reason code. The `agentShield` field is preserved
+ * on the result type as a frozen "always disabled" stub so any
+ * downstream consumer keeps compiling, but the merged findings list
+ * is always the peaks-loop findings list (no ECC findings).
+ *
+ * The subprocess-runner seam (`SubprocessRunner`, `defaultSubprocessRunner`)
+ * is preserved as an EXPORTED TYPE so legacy tests can still
+ * mock it; the runner itself is never invoked from production code.
+ */
+import { runRedLinesAudit } from './red-lines-service.js';
+import { loadPreferences } from '../preferences/preferences-service.js';
+import { computeProseRatio } from './prose-ratio-calculator.js';
+export function runStaticAudit(input) {
+    // Slice 3: agent-shield integration removed. The CLI flag and
+    // preference are still read for backward-compat (a user with a
+    // stale preferences.json that sets `agentShieldEnabled: true`
+    // does not get a hard error) but neither spawns a subprocess.
+    loadPreferences(input.projectRoot);
+    // Always run the peaks-loop lint layer; no ECC findings merged.
+    const peaksResult = runRedLinesAudit({ projectRoot: input.projectRoot });
+    const mergedAudit = {
+        ...peaksResult.audit,
+        enforcerFindings: [...peaksResult.audit.enforcerFindings],
+    };
+    const state = {
+        spawned: false,
+        installed: false,
+        reason: 'disabled-and-ecc-missing',
+        findings: [],
+    };
+    const proseRatio = computeProseRatio(mergedAudit.audit);
+    return {
+        audit: mergedAudit,
+        agentShield: state,
+        warnings: [],
+        proseRatio,
+    };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Red-line audit framework — types.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-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-code-ban-001". */
+    readonly id: string;
+    /** Human-readable rule name, e.g. "Code Commit Ban". */
+    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/services/audit/types.js

@@ -0,0 +1,13 @@
+/**
+ * Red-line audit framework — types.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-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/services/audit-independent/index.d.ts

@@ -0,0 +1,2 @@
+export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit, readSecurityTemplate, renderSecurityAuditArtifact, type SecurityAuditEnvelope, type SecurityAuditViolation, type SecurityAuditVerdict, type SecurityAuditDetectState, type SecurityAuditDetectResult, type HandoffFrontmatter, readAndVerifyHandoff, } from './security-audit-service.js';
+export { runPerfAudit, isPerfAuditEnvelope, detectPerfAudit, readPerfTemplate, renderPerfAuditArtifact, type PerfAuditEnvelope, type PerfAuditViolation, type PerfAuditVerdict, type PerfAuditDetectState, type PerfAuditDetectResult, } from './perf-audit-service.js';

package/dist/services/audit-independent/index.js

@@ -0,0 +1,2 @@
+export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit, readSecurityTemplate, renderSecurityAuditArtifact, readAndVerifyHandoff, } from './security-audit-service.js';
+export { runPerfAudit, isPerfAuditEnvelope, detectPerfAudit, readPerfTemplate, renderPerfAuditArtifact, } from './perf-audit-service.js';

package/dist/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;
+};