peaks-loop 4.0.0-beta.7 → 4.0.0-beta.8

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

@@ -1,68 +0,0 @@
-/**
- * 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/src/services/audit/static-service.d.ts

@@ -1,60 +0,0 @@
-/**
- * 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-loop-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

@@ -1,130 +0,0 @@
-/**
- * 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-loop-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-loop CLI flag
-        // (`peaks audit static --project <path>`) follows peaks-loop
-        // 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-loop 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-loop 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

@@ -1,86 +0,0 @@
-/**
- * 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/src/services/audit/types.js

@@ -1,13 +0,0 @@
-/**
- * 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/src/services/audit-independent/perf-audit-service.d.ts

@@ -1,151 +0,0 @@
-/**
- * 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;
-};