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

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

@@ -1,35 +0,0 @@
-/**
- * `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/src/services/audit/audit-goal-service.js

@@ -1,75 +0,0 @@
-/**
- * `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/src/services/audit/audit-goal-types.d.ts

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

@@ -1,15 +0,0 @@
-/**
- * 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/src/services/audit/backing-detector.d.ts

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

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

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

@@ -1,134 +0,0 @@
-/**
- * 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/src/services/audit/decision-writer.d.ts

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