peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,35 @@
+/**
+ * `auditGoal()` — the audit + goal primitive that gates autonomous
+ * LLM execution in the 10% human / 90% LLM workflow.
+ *
+ * Contract:
+ *   - Calls an injected `LlmRunner` exactly once.
+ *   - Parses the LLM output as JSON and validates that the `audit`
+ *     array covers ALL six required dimensions
+ *     (correctness, completeness, scope, risks, alternatives, constraints).
+ *   - Throws `IncompleteAuditError` if the JSON is malformed or any
+ *     required dimension is missing. Callers MUST treat this as a
+ *     gate failure (return to human for re-prompting) — autonomous
+ *     work must never proceed on a partial audit.
+ *
+ * The `LlmRunner` interface is intentionally minimal so this
+ * service is reusable by `final-review-service` and the slice
+ * LLMArbitrator without forcing a particular provider implementation.
+ */
+import type { AuditGoalInput, AuditGoalOutput } from './audit-goal-types.js';
+export interface LlmRunner {
+    call(systemPrompt: string, userPrompt: string, opts: {
+        maxTokens: number;
+    }): Promise<{
+        output: string;
+        tokens: {
+            input: number;
+            output: number;
+        };
+    }>;
+}
+export declare class IncompleteAuditError extends Error {
+    readonly code: "INCOMPLETE_AUDIT";
+    constructor(message: string);
+}
+export declare function auditGoal(input: AuditGoalInput, llmRunner: LlmRunner): Promise<AuditGoalOutput>;

package/dist/services/audit/audit-goal-service.js

@@ -0,0 +1,75 @@
+/**
+ * `auditGoal()` — the audit + goal primitive that gates autonomous
+ * LLM execution in the 10% human / 90% LLM workflow.
+ *
+ * Contract:
+ *   - Calls an injected `LlmRunner` exactly once.
+ *   - Parses the LLM output as JSON and validates that the `audit`
+ *     array covers ALL six required dimensions
+ *     (correctness, completeness, scope, risks, alternatives, constraints).
+ *   - Throws `IncompleteAuditError` if the JSON is malformed or any
+ *     required dimension is missing. Callers MUST treat this as a
+ *     gate failure (return to human for re-prompting) — autonomous
+ *     work must never proceed on a partial audit.
+ *
+ * The `LlmRunner` interface is intentionally minimal so this
+ * service is reusable by `final-review-service` and the slice
+ * LLMArbitrator without forcing a particular provider implementation.
+ */
+export class IncompleteAuditError extends Error {
+    code = 'INCOMPLETE_AUDIT';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteAuditError';
+    }
+}
+const REQUIRED_DIMENSIONS = [
+    'correctness',
+    'completeness',
+    'scope',
+    'risks',
+    'alternatives',
+    'constraints'
+];
+const SYSTEM_PROMPT = `You are auditing a software development need. Produce a structured JSON response with EXACTLY these fields:
+- summary (1-2 sentence summary of the need)
+- audit (array of EXACTLY 6 objects, one per dimension: correctness, completeness, scope, risks, alternatives, constraints; each with dimension, finding, severity)
+- proposedGoal (what success looks like)
+- successCriteria (list of acceptance criteria)
+- roughEffort (small | medium | large | epic)
+- confidence (high | medium | low)
+- rationale (one paragraph tying audit to goal)
+
+Output ONLY valid JSON, no prose.`;
+export async function auditGoal(input, llmRunner) {
+    const userPrompt = `Need: ${input.need}\n\nAudit this need across the 6 dimensions and propose a goal.`;
+    const response = await llmRunner.call(SYSTEM_PROMPT, userPrompt, { maxTokens: 2000 });
+    let parsed;
+    try {
+        parsed = JSON.parse(response.output);
+    }
+    catch (err) {
+        throw new IncompleteAuditError(`LLM output is not valid JSON: ${err.message}`);
+    }
+    if (!isAuditGoalOutput(parsed)) {
+        throw new IncompleteAuditError('LLM output is missing required top-level fields (summary, audit, proposedGoal, successCriteria, roughEffort, confidence, rationale).');
+    }
+    const presentDimensions = new Set(parsed.audit.map(d => d.dimension));
+    const missing = REQUIRED_DIMENSIONS.filter(d => !presentDimensions.has(d));
+    if (missing.length > 0) {
+        throw new IncompleteAuditError(`Missing required audit dimensions: ${missing.join(', ')}`);
+    }
+    return parsed;
+}
+function isAuditGoalOutput(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.summary === 'string' &&
+        Array.isArray(v.audit) &&
+        typeof v.proposedGoal === 'string' &&
+        Array.isArray(v.successCriteria) &&
+        typeof v.roughEffort === 'string' &&
+        typeof v.confidence === 'string' &&
+        typeof v.rationale === 'string');
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Type contracts for the `auditGoal()` primitive.
+ *
+ * The audit-goal primitive sits between a human's expressed need and any
+ * autonomous LLM execution. It forces the LLM to:
+ *   1. Summarize the need.
+ *   2. Audit across 6 dimensions (correctness, completeness, scope, risks,
+ *      alternatives, constraints) — each with a severity.
+ *   3. Propose a goal, success criteria, rough effort, and confidence.
+ *
+ * The 6-dimension contract is the unit of validation; the service
+ * rejects any LLM response that omits a dimension so downstream
+ * autonomous work cannot proceed on a partial audit.
+ */
+export type AuditDimensionKind = 'correctness' | 'completeness' | 'scope' | 'risks' | 'alternatives' | 'constraints';
+export type AuditSeverity = 'info' | 'concern' | 'blocker';
+export type AuditEffort = 'small' | 'medium' | 'large' | 'epic';
+export type AuditConfidence = 'high' | 'medium' | 'low';
+export interface AuditGoalInput {
+    readonly need: string;
+    readonly context?: {
+        readonly projectRoot?: string;
+        readonly sessionMemory?: readonly string[];
+        readonly relevantMemories?: readonly string[];
+    };
+}
+export interface AuditDimension {
+    readonly dimension: AuditDimensionKind;
+    readonly finding: string;
+    readonly severity: AuditSeverity;
+}
+export interface AuditGoalOutput {
+    readonly summary: string;
+    readonly audit: readonly AuditDimension[];
+    readonly proposedGoal: string;
+    readonly successCriteria: readonly string[];
+    readonly roughEffort: AuditEffort;
+    readonly confidence: AuditConfidence;
+    readonly rationale: string;
+}

package/dist/services/audit/audit-goal-types.js

@@ -0,0 +1,15 @@
+/**
+ * Type contracts for the `auditGoal()` primitive.
+ *
+ * The audit-goal primitive sits between a human's expressed need and any
+ * autonomous LLM execution. It forces the LLM to:
+ *   1. Summarize the need.
+ *   2. Audit across 6 dimensions (correctness, completeness, scope, risks,
+ *      alternatives, constraints) — each with a severity.
+ *   3. Propose a goal, success criteria, rough effort, and confidence.
+ *
+ * The 6-dimension contract is the unit of validation; the service
+ * rejects any LLM response that omits a dimension so downstream
+ * autonomous work cannot proceed on a partial audit.
+ */
+export {};

package/dist/services/audit/backing-detector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Backing detector — classifies each red line as `cli-backed`, `partial`,
+ * or `prose-only`. The classifier already sets the backing for catalog hits
+ * (cli-backed when an enforcer file path is present). This module exists to
+ * handle the post-classification nuance: heuristics for the "partial" tier
+ * (a gate exists but the LLM can bypass it) and verification that the
+ * enforcer file actually exists on disk.
+ */
+import type { RedLineEntry } from './types.js';
+export interface BackingResult {
+    readonly entry: RedLineEntry;
+    readonly enforcerExists: boolean;
+}
+/**
+ * Re-classify a single RedLineEntry. Returns a new entry with the
+ * `backing` field updated and `enforcerRef` possibly nulled if the
+ * referenced file does not exist on disk.
+ */
+export declare function classifyBacking(entry: RedLineEntry, projectRoot: string): BackingResult;
+export interface BackingBatchResult {
+    readonly entries: readonly RedLineEntry[];
+    readonly warnings: readonly string[];
+}
+export declare function classifyBackingBatch(entries: readonly RedLineEntry[], projectRoot: string): BackingBatchResult;

package/dist/services/audit/backing-detector.js

@@ -0,0 +1,59 @@
+/**
+ * Backing detector — classifies each red line as `cli-backed`, `partial`,
+ * or `prose-only`. The classifier already sets the backing for catalog hits
+ * (cli-backed when an enforcer file path is present). This module exists to
+ * handle the post-classification nuance: heuristics for the "partial" tier
+ * (a gate exists but the LLM can bypass it) and verification that the
+ * enforcer file actually exists on disk.
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+const PARTIAL_PHRASES = [
+    'if llm cooperates',
+    'llm-cooperation',
+    'partial cli backing',
+    'best effort',
+    'advisory only',
+    'soft enforcement',
+    'when remembered',
+];
+function detectPartial(context) {
+    const lower = context.toLowerCase();
+    return PARTIAL_PHRASES.some((phrase) => lower.includes(phrase));
+}
+/**
+ * Re-classify a single RedLineEntry. Returns a new entry with the
+ * `backing` field updated and `enforcerRef` possibly nulled if the
+ * referenced file does not exist on disk.
+ */
+export function classifyBacking(entry, projectRoot) {
+    if (detectPartial(entry.source.context)) {
+        return {
+            entry: { ...entry, backing: 'partial' },
+            enforcerExists: entry.enforcerRef !== null && existsSync(resolve(projectRoot, entry.enforcerRef)),
+        };
+    }
+    if (entry.enforcerRef === null) {
+        return { entry, enforcerExists: false };
+    }
+    const enforcerPath = resolve(projectRoot, entry.enforcerRef);
+    const exists = existsSync(enforcerPath);
+    return {
+        entry: { ...entry, backing: exists ? 'cli-backed' : 'prose-only' },
+        enforcerExists: exists,
+    };
+}
+export function classifyBackingBatch(entries, projectRoot) {
+    const updated = [];
+    const warnings = [];
+    for (const entry of entries) {
+        const { entry: reclassified, enforcerExists } = classifyBacking(entry, projectRoot);
+        updated.push(reclassified);
+        if (reclassified.backing === 'cli-backed' && !enforcerExists) {
+            // Defensive: should not happen because classifyBacking downgrades to
+            // prose-only, but keep the assertion in case of future drift.
+            warnings.push(`enforcer ref "${reclassified.enforcerRef}" missing on disk for ${reclassified.id}`);
+        }
+    }
+    return { entries: updated, warnings };
+}

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

@@ -0,0 +1,38 @@
+/**
+ * Red-line classifier — turns raw markdown lines into RedLineEntry.
+ *
+ * Algorithm: for each MarkdownLine, check whether the line text contains one
+ * of the four red-line markers (MANDATORY / BLOCKING / MUST NOT / RED LINE).
+ * On a hit, extract the surrounding ±2 lines as context, look up the red
+ * line in the catalog, and emit a RedLineEntry. Lines that contain a marker
+ * but match no catalog entry still produce a RedLineEntry (with backing =
+ * prose-only and enforcerRef = null) — those are the "discovered but not yet
+ * enforced" red lines the L2 redesign is working to eliminate.
+ */
+import type { RedLineEntry, RedLineMarker } from './types.js';
+export declare function detectMarker(lineText: string): RedLineMarker | null;
+/**
+ * Derive a human-readable rule name from the marker line. Heuristic: take
+ * the first 8 words of the line, lowercase, trimmed. Catalog matching is
+ * the source of truth for the canonical rule name; this is the fallback
+ * when no catalog entry matches.
+ */
+export declare function deriveRuleName(lineText: string): string;
+export interface ClassifyFileInput {
+    readonly file: string;
+    readonly lines: readonly string[];
+}
+export interface ClassifyResult {
+    readonly entries: readonly RedLineEntry[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Classify a single markdown file. Returns 0+ RedLineEntry; one entry per
+ * marker hit. Marker hits that appear multiple times on the same line are
+ * counted once.
+ */
+export declare function classifyFile(input: ClassifyFileInput): ClassifyResult;
+/**
+ * Batch wrapper — classify each input file and flatten the entries.
+ */
+export declare function classifyFiles(inputs: readonly ClassifyFileInput[]): ClassifyResult;

package/dist/services/audit/classifier.js

@@ -0,0 +1,134 @@
+/**
+ * Red-line classifier — turns raw markdown lines into RedLineEntry.
+ *
+ * Algorithm: for each MarkdownLine, check whether the line text contains one
+ * of the four red-line markers (MANDATORY / BLOCKING / MUST NOT / RED LINE).
+ * On a hit, extract the surrounding ±2 lines as context, look up the red
+ * line in the catalog, and emit a RedLineEntry. Lines that contain a marker
+ * but match no catalog entry still produce a RedLineEntry (with backing =
+ * prose-only and enforcerRef = null) — those are the "discovered but not yet
+ * enforced" red lines the L2 redesign is working to eliminate.
+ */
+import { findCatalogEntry } from './red-line-catalog.js';
+const MARKER_PATTERN = /\b(MANDATORY|BLOCKING|MUST NOT|RED LINE)\b/;
+const CONTEXT_LINES_BEFORE = 2;
+const CONTEXT_LINES_AFTER = 2;
+function isMarker(s) {
+    return s === 'MANDATORY' || s === 'BLOCKING' || s === 'MUST NOT' || s === 'RED LINE';
+}
+function extractContext(allLines, hitLine) {
+    const start = Math.max(0, hitLine - CONTEXT_LINES_BEFORE);
+    const end = Math.min(allLines.length, hitLine + 1 + CONTEXT_LINES_AFTER);
+    return allLines.slice(start, end).join('\n');
+}
+/**
+ * Detect markers in a single line of markdown. Returns the marker text found
+ * (uppercased), or null when no marker is present.
+ */
+/**
+ * Case-insensitive marker pattern (used only by detectMarker so callers can
+ * write `MANDATORY` / `mandatory` / `Mandatory` interchangeably in prose).
+ * deriveRuleName uses the all-caps MARKER_PATTERN so it doesn't strip a
+ * mid-sentence "Red Line" reference.
+ */
+const MARKER_PATTERN_CI = /\b(MANDATORY|BLOCKING|MUST NOT|RED LINE)\b/i;
+export function detectMarker(lineText) {
+    const match = MARKER_PATTERN_CI.exec(lineText);
+    if (!match)
+        return null;
+    const raw = (match[1] ?? '').toUpperCase();
+    if (raw === 'MUST') {
+        // "MUST NOT" is two tokens in the regex; the match group only captures
+        // "MUST". Re-verify by checking the next character.
+        const after = lineText[match.index + match[0].length];
+        if (after === undefined || /\s/.test(after)) {
+            return 'MUST NOT';
+        }
+        return isMarker(raw) ? raw : null;
+    }
+    return isMarker(raw) ? raw : null;
+}
+/**
+ * Derive a human-readable rule name from the marker line. Heuristic: take
+ * the first 8 words of the line, lowercase, trimmed. Catalog matching is
+ * the source of truth for the canonical rule name; this is the fallback
+ * when no catalog entry matches.
+ */
+export function deriveRuleName(lineText) {
+    const cleaned = lineText
+        .replace(MARKER_PATTERN, '')
+        .replace(/^[*_`#>:]+/, '')
+        .replace(/[*_`#>]/g, '')
+        .trim();
+    const words = cleaned.split(/\s+/).filter(Boolean).slice(0, 8);
+    return words.length > 0 ? words.join(' ').toLowerCase() : 'unspecified red line';
+}
+/**
+ * Classify a single markdown file. Returns 0+ RedLineEntry; one entry per
+ * marker hit. Marker hits that appear multiple times on the same line are
+ * counted once.
+ */
+export function classifyFile(input) {
+    const entries = [];
+    const warnings = [];
+    const seen = new Set();
+    for (let idx = 0; idx < input.lines.length; idx++) {
+        const lineText = input.lines[idx] ?? '';
+        if (seen.has(idx + 1))
+            continue;
+        const marker = detectMarker(lineText);
+        if (marker === null)
+            continue;
+        seen.add(idx + 1);
+        const context = extractContext(input.lines, idx);
+        const ruleName = deriveRuleName(lineText);
+        const markers = [marker];
+        const catalog = findCatalogEntry(ruleName, markers);
+        const source = {
+            file: input.file,
+            line: idx + 1,
+            marker,
+            context,
+        };
+        if (catalog) {
+            entries.push({
+                id: catalog.id,
+                rule: catalog.rule,
+                source,
+                backing: catalog.enforcerRef === null ? 'prose-only' : 'cli-backed',
+                enforcerRef: catalog.enforcerRef,
+            });
+        }
+        else {
+            // Marker hit but no catalog match: discovered, not yet enforced.
+            // v2.12.1 catalog governance: mark these `informational: true`
+            // so the prose-only ratio (per spec §10.2 ≤ 5%) excludes them.
+            // The pre-v2.12.1 ratio was 60.1% because every advisory phrase
+            // in SKILL.md was counted; the new ratio only counts entries
+            // with a real catalog template (those that COULD be promoted
+            // to cli-backed via the enforcer-pipeline).
+            entries.push({
+                id: `rl-discovered-${input.file.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}-${idx + 1}`,
+                rule: ruleName,
+                source,
+                backing: 'prose-only',
+                enforcerRef: null,
+                informational: true,
+            });
+        }
+    }
+    return { entries, warnings };
+}
+/**
+ * Batch wrapper — classify each input file and flatten the entries.
+ */
+export function classifyFiles(inputs) {
+    const allEntries = [];
+    const allWarnings = [];
+    for (const input of inputs) {
+        const result = classifyFile(input);
+        allEntries.push(...result.entries);
+        allWarnings.push(...result.warnings);
+    }
+    return { entries: allEntries, warnings: allWarnings };
+}

package/dist/services/audit/decision-writer.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Audit decision writer — Slice K1.
+ *
+ * Persists a `RedLineAudit` snapshot to `.peaks/memory/audit-decisions/<slug>.md`
+ * so the audit is searchable / indexable by the existing project-memory
+ * machinery (`peaks memory search`, `peaks project memories`).
+ *
+ * Locked decisions (K1 design, user-approved):
+ *
+ * 1. **No `context` field** in the persisted record. `RedLineSource.context`
+ *    is the ±2 lines of raw markdown used only by `backing-detector.ts`
+ *    (`detectPartial(entry.source.context)`) to classify the entry as
+ *    partial / cli-backed / prose-only. It is an *intermediate artifact* —
+ *    once the audit runs, the classification result is captured by
+ *    `RedLineEntry.backing` and the raw context has no consumer. We
+ *    intentionally do not write `context` to the decision record (no
+ *    caller reads it; persisting it would just bloat the file).
+ *
+ * 2. **Path is `.peaks/memory/audit-decisions/`, NOT `_runtime/`** — the
+ *    decision is git-tracked source-of-truth (project memory), not session
+ *    ephemeral state. The subdir is named for human discoverability; the
+ *    memory service's recursive scan picks it up automatically.
+ *
+ * 3. **No new CLI subcommand.** Per `peaks-loop-when-adding-a-new-subcommand-…`
+ *    we extend the existing `peaks audit static` with a `--record` flag
+ *    instead of adding `peaks audit record` (which would be a new
+ *    top-level shape and conflict with the dev-preference red line
+ *    "Default-no on new CLI commands").
+ *
+ * 4. **Memory index auto-regen.** Writing the file does not directly
+ *    manipulate `.peaks/memory/index.json`. The `peaks project memories`
+ *    reader uses mtime-based regeneration; the new file's mtime being
+ *    newer than `index.json` triggers regeneration on next read.
+ *    `readMemoryIndex()` is called eagerly here so the caller sees a
+ *    `hot.decision[]` update synchronously with the write.
+ */
+import type { RedLineAudit } from './types.js';
+export interface AuditDecisionOptions {
+    readonly projectRoot: string;
+    /** ISO date (YYYY-MM-DD). Defaults to today (UTC). */
+    readonly date?: string;
+    /** Optional request id, used to disambiguate multiple audits on the same day. */
+    readonly rid?: string;
+}
+export interface AuditDecisionRecord {
+    readonly name: string;
+    readonly title: string;
+    readonly date: string;
+    readonly filePath: string;
+    readonly memoryDir: string;
+    readonly indexPath: string;
+    readonly totalRedLines: number;
+    readonly cliBacked: number;
+    readonly partial: number;
+    readonly proseOnly: number;
+    readonly enforcerFailures: number;
+    readonly enforcerWarnings: number;
+    readonly enforcerPasses: number;
+    readonly indexSynced: boolean;
+}
+/**
+ * Pure: render the decision markdown body. No I/O. Used by both the
+ * writer and the test suite for byte-exact assertions.
+ */
+export declare function renderDecisionMarkdown(audit: RedLineAudit, options: {
+    date: string;
+    rid?: string;
+}): string;
+/**
+ * Persist the audit as a project-memory decision. Idempotent only at the
+ * file level — repeated calls with the same `(date, rid)` pair will overwrite
+ * the previous decision markdown (the slug collides, the older file is
+ * replaced). This matches the "one audit run = one decision record" model.
+ */
+export declare function writeAuditDecision(audit: RedLineAudit, options: AuditDecisionOptions): AuditDecisionRecord;
+export { writeDecision } from './artifact-writer.js';