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

package/dist/src/services/prd/project-scan-sediment.js

@@ -1,445 +0,0 @@
-/**
- * peaks-prd project-scan sediment writer — v2.11.0 D3 (Group C, Tier 5) +
- * v2.12.0 Group C Tier 6 (audit inventory sediment).
- *
- * Appends new business concepts to
- * `.peaks/project-scan/business-knowledge.md` AND new audit-inventory
- * rows to the three v2.12.0 audit templates (security-template.md /
- * perf-template.md / audit-output-schema.md). Idempotent on the
- * `(concept, sourceRid)` tuple for `appendBusinessConcept` and on the
- * `(value, sourceRid)` tuple for the three audit-inventory appenders —
- * re-running with the same input does not duplicate.
- *
- * The on-disk format mirrors the bootstrap templates: a YAML
- * frontmatter carrying `schemaVersion: 1` (with `templateKind` for the
- * audit templates) plus a markdown table in the body whose rows are the
- * sediment tuples. The table format is human-readable (grep-friendly).
- *
- * The audit-template tables are **append-only inventories** (slice
- * v2.12.0 audit-template design): the `#` column is auto-incremented,
- * the body of the file is not re-rendered wholesale — the writer
- * locates the placeholder row `| (empty) |` and replaces it with the
- * first real row, then appends subsequent rows after the table.
- *
- * Companion to `project-scan-reader.ts`. The reader and the writer
- * agree on the same on-disk format for `business-knowledge.md`. The
- * three audit-inventory writers preserve the frontmatter verbatim and
- * use a generic internal row parser (not a typed reader) — those
- * tables are write-mostly and not consumed by `readBusinessKnowledge`.
- */
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { readBusinessKnowledge } from './project-scan-reader.js';
-const BUSINESS_KNOWLEDGE_RELATIVE = join('.peaks', 'project-scan', 'business-knowledge.md');
-const SECURITY_TEMPLATE_RELATIVE = join('.peaks', 'project-scan', 'security-template.md');
-const PERF_TEMPLATE_RELATIVE = join('.peaks', 'project-scan', 'perf-template.md');
-const AUDIT_OUTPUT_SCHEMA_RELATIVE = join('.peaks', 'project-scan', 'audit-output-schema.md');
-/**
- * Append (or create) a business concept row in
- * `.peaks/project-scan/business-knowledge.md`.
- *
- * Idempotency contract (matches the bootstrap file's design intent):
- * - same `(concept, sourceRid)` tuple → skip (return `written: false`)
- * - same `concept`, DIFFERENT `sourceRid` → append (re-definition from a new source)
- * - new concept → append
- *
- * Throws when the existing file has malformed frontmatter or markdown
- * table (no silent corruption). Caller should fix the file before retrying.
- */
-export async function appendBusinessConcept(opts) {
-    const existing = await readBusinessKnowledge(opts.projectRoot);
-    const absolutePath = join(opts.projectRoot, BUSINESS_KNOWLEDGE_RELATIVE);
-    if (existing === null) {
-        const fresh = {
-            schemaVersion: 1,
-            concepts: [opts.concept]
-        };
-        await writeBusinessKnowledgeFile(absolutePath, fresh);
-        return { written: true, created: true, totalConcepts: 1 };
-    }
-    const duplicateIndex = existing.concepts.findIndex((c) => c.concept === opts.concept.concept && c.sourceRid === opts.concept.sourceRid);
-    if (duplicateIndex >= 0) {
-        return {
-            written: false,
-            created: false,
-            totalConcepts: existing.concepts.length
-        };
-    }
-    const updated = {
-        schemaVersion: 1,
-        concepts: [...existing.concepts, opts.concept]
-    };
-    await writeBusinessKnowledgeFile(absolutePath, updated);
-    return {
-        written: true,
-        created: false,
-        totalConcepts: updated.concepts.length
-    };
-}
-// ── internal helpers ─────────────────────────────────────────────────
-async function writeBusinessKnowledgeFile(absolutePath, knowledge) {
-    await mkdir(dirname(absolutePath), { recursive: true });
-    const body = renderBusinessKnowledgeBody(knowledge);
-    await writeFile(absolutePath, body, 'utf8');
-}
-/**
- * Append (or create) a security-audit risk-pattern row in
- * `.peaks/project-scan/security-template.md` "Known risks inventory".
- *
- * The on-disk format is a 5-column markdown table (auto-incremented `#`
- * + 4 string fields). Idempotency: same `(value, sourceRid)` tuple is a
- * no-op; the frontmatter is preserved verbatim. The first append replaces
- * the `| (empty) |` placeholder row; subsequent appends go after the
- * table footer.
- */
-export async function appendSecurityPattern(opts) {
-    return appendAuditPatternInventory({
-        projectRoot: opts.projectRoot,
-        relativePath: SECURITY_TEMPLATE_RELATIVE,
-        templateKind: 'security-audit',
-        tableHeading: 'Known risks inventory',
-        columnHeader: 'Risk pattern',
-        row: opts.row
-    });
-}
-/**
- * Append (or create) a perf-audit baseline row in
- * `.peaks/project-scan/perf-template.md` "Known baselines inventory".
- *
- * Same contract as `appendSecurityPattern` (5-column markdown table,
- * auto-incremented `#`, idempotent on `(value, sourceRid)`,
- * frontmatter preserved verbatim).
- */
-export async function appendPerfPattern(opts) {
-    return appendAuditPatternInventory({
-        projectRoot: opts.projectRoot,
-        relativePath: PERF_TEMPLATE_RELATIVE,
-        templateKind: 'perf-audit',
-        tableHeading: 'Known baselines inventory',
-        columnHeader: 'Baseline',
-        row: opts.row
-    });
-}
-/**
- * Append (or create) an audit-output-schema variant row in
- * `.peaks/project-scan/audit-output-schema.md` "Known schema variants".
- *
- * Same contract as `appendSecurityPattern` (5-column markdown table,
- * auto-incremented `#`, idempotent on `(value, sourceRid)`,
- * frontmatter preserved verbatim).
- */
-export async function appendAuditSchemaVariant(opts) {
-    return appendAuditPatternInventory({
-        projectRoot: opts.projectRoot,
-        relativePath: AUDIT_OUTPUT_SCHEMA_RELATIVE,
-        templateKind: 'audit-output-schema',
-        tableHeading: 'Known schema variants',
-        columnHeader: 'Variant',
-        row: opts.row
-    });
-}
-/**
- * Generic 5-column inventory-table appender shared by the 3 audit
- * sediment operations. The on-disk shape is:
- *
- *   ---
- *   schemaVersion: 1
- *   templateKind: <templateKind>
- *   capturedAt: <ISO 8601>
- *   appliesTo: <skill id list>
- *   ---
- *
- *   # <title>
- *
- *   ... preamble ...
- *
- *   ## <tableHeading>
- *
- *   | # | <columnHeader> | First introduced (rid) | Source | Status |
- *   |---|---|---|---|---|
- *   | (empty) | — | — | — | — |   ← bootstrap placeholder
- *
- *   ... post-table prose ...
- *
- * On append:
- *  1. If the file is absent, write a fresh bootstrap with a single
- *     `| 1 | <row> | ... |` row (replacing the placeholder).
- *  2. If a row with the same `(value, sourceRid)` tuple already exists,
- *     return `written: false` (idempotent no-op).
- *  3. Otherwise:
- *     - if the placeholder `| (empty) |` row is present, replace it
- *       with the new row using the next auto-incremented index
- *       (1, unless other rows already exist);
- *     - if the placeholder is absent (i.e. the table has prior rows),
- *       append the new row after the last table line.
- *
- * The frontmatter and the surrounding prose are preserved verbatim.
- * Cell escaping mirrors the existing `appendBusinessConcept` policy
- * (pipe → `\|`, newline → space).
- */
-async function appendAuditPatternInventory(args) {
-    const absolutePath = join(args.projectRoot, args.relativePath);
-    const existing = await readOptionalFile(absolutePath);
-    if (existing === null) {
-        const freshBody = renderFreshAuditPatternBody(args);
-        await mkdir(dirname(absolutePath), { recursive: true });
-        await writeFile(absolutePath, freshBody, 'utf8');
-        return { written: true, created: true, assignedIndex: 1, totalRows: 1 };
-    }
-    const { openMarker, yaml, closeMarker, body } = splitFrontmatterBlock(existing);
-    const parsed = parseAuditInventoryTable(body, args.tableHeading);
-    if (parsed === null) {
-        // Bootstrap table shape not found — the file was hand-edited or is
-        // from a pre-2.12.0 source. We do NOT silently corrupt; the caller
-        // (peaks-txt sediment step) is expected to surface this.
-        throw new Error(`project-scan sediment: ${args.relativePath} is missing the "${args.tableHeading}" table; cannot append`);
-    }
-    // Idempotency check: same (value, sourceRid) tuple already present.
-    const duplicateIndex = parsed.rows.findIndex((r) => r.value === args.row.value && r.sourceRid === args.row.sourceRid);
-    if (duplicateIndex >= 0) {
-        return {
-            written: false,
-            created: false,
-            assignedIndex: duplicateIndex + 1,
-            totalRows: parsed.rows.length
-        };
-    }
-    const newIndex = parsed.rows.length + 1;
-    const newRow = args.row;
-    const updatedBody = parsed.hasPlaceholder
-        ? replacePlaceholderRow(body, args.tableHeading, {
-            index: newIndex,
-            row: newRow
-        })
-        : appendRowAfterTable(body, {
-            index: newIndex,
-            row: newRow
-        });
-    const next = `${openMarker}\n${yaml}\n${closeMarker}\n${updatedBody}`;
-    await writeFile(absolutePath, next, 'utf8');
-    return {
-        written: true,
-        created: false,
-        assignedIndex: newIndex,
-        totalRows: parsed.rows.length + 1
-    };
-}
-function splitFrontmatterBlock(content) {
-    // The audit templates all start with `---\n...\n---\n` followed by
-    // body. We re-emit the frontmatter verbatim (no YAML reparse) so we
-    // never lose comments or formatting.
-    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(content);
-    if (!match) {
-        throw new Error('project-scan sediment: frontmatter block missing or malformed');
-    }
-    return {
-        openMarker: '---',
-        yaml: match[1] ?? '',
-        closeMarker: '---',
-        body: match[2] ?? ''
-    };
-}
-/**
- * Locate the inventory table under the given heading and return its
- * data rows. Returns `null` when the heading is missing (caller should
- * throw). Recognises the bootstrap `| (empty) |` placeholder row but
- * does NOT include it in the returned `rows` array.
- */
-function parseAuditInventoryTable(body, tableHeading) {
-    // Find the H2 heading, then walk forward scanning for the table
-    // block. The on-disk format includes a `>` blockquote between the
-    // heading and the table (e.g. `> This section is **append-only**...`),
-    // so the parser must skip non-`|` lines until the first `|` line,
-    // then collect until the next non-`|` line.
-    const lines = body.split(/\r?\n/);
-    let headingLineIdx = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (lines[i]?.trim() === `## ${tableHeading}`) {
-            headingLineIdx = i;
-            break;
-        }
-    }
-    if (headingLineIdx === -1) {
-        return null;
-    }
-    const tableLines = [];
-    let inTable = false;
-    for (let i = headingLineIdx + 1; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/^\s*\|/.test(line)) {
-            tableLines.push(line);
-            inTable = true;
-            continue;
-        }
-        if (inTable) {
-            // First non-`|` line after the table starts → table is done.
-            break;
-        }
-        // Otherwise keep scanning past blockquote / blank lines.
-    }
-    if (tableLines.length < 3) {
-        return null;
-    }
-    // First row = header, second row = separator (---|---|---). Skip both.
-    const dataRows = tableLines.slice(2);
-    const rows = [];
-    let hasPlaceholder = false;
-    for (const row of dataRows) {
-        const cells = splitTableRow(row);
-        if (cells.length < 5)
-            continue;
-        const [indexCell, value, sourceRid, source, status] = cells;
-        if (!indexCell || !value || !sourceRid || !source || !status)
-            continue;
-        if (value === '(empty)' || value === '—') {
-            hasPlaceholder = true;
-            continue;
-        }
-        rows.push({ value, sourceRid, source, status });
-    }
-    return { rows, hasPlaceholder };
-}
-function splitTableRow(row) {
-    return row
-        .split('|')
-        .map((cell) => cell.trim())
-        .filter((cell, idx, arr) => !(idx === 0 && cell === '') && !(idx === arr.length - 1 && cell === ''));
-}
-function renderFreshAuditPatternBody(args) {
-    const titleByKind = {
-        'security-audit': 'Security Audit Template (peaks-loop v2.12.0)',
-        'perf-audit': 'Performance Audit Template (peaks-loop v2.12.0)',
-        'audit-output-schema': 'Audit Output Schema (peaks-loop v2.12.0)'
-    };
-    const appliesToByKind = {
-        'security-audit': 'peaks-security-audit skill',
-        'perf-audit': 'peaks-perf-audit skill',
-        'audit-output-schema': 'peaks-security-audit + peaks-perf-audit'
-    };
-    return [
-        '---',
-        'schemaVersion: 1',
-        `templateKind: ${args.templateKind}`,
-        `capturedAt: 2026-06-27T00:00:00.000Z`,
-        `appliesTo: ${appliesToByKind[args.templateKind]}`,
-        '---',
-        '',
-        `# ${titleByKind[args.templateKind]}`,
-        '',
-        `> **Bootstrap template** for the ${args.tableHeading} table. Appended by \`peaks-txt\` sediment step (v2.12.0 Group C Tier 6).`,
-        '',
-        `## ${args.tableHeading}`,
-        '',
-        '> This section is **append-only**. Re-running with the same `(value, sourceRid)` tuple does not duplicate.',
-        '',
-        `| # | ${args.columnHeader} | First introduced (rid) | Source | Status |`,
-        '|---|---|---|---|---|',
-        `| 1 | ${escapeCell(args.row.value)} | ${escapeCell(args.row.sourceRid)} | ${escapeCell(args.row.source)} | ${escapeCell(args.row.status)} |`,
-        ''
-    ].join('\n');
-}
-function replacePlaceholderRow(body, tableHeading, args) {
-    const lines = body.split(/\r?\n/);
-    const out = [];
-    let headingSeen = false;
-    let inTable = false;
-    for (const line of lines) {
-        if (!headingSeen && line.trim() === `## ${tableHeading}`) {
-            headingSeen = true;
-            out.push(line);
-            continue;
-        }
-        if (headingSeen && /^\s*\|/.test(line)) {
-            // Skip the placeholder row (first data row we see after the
-            // separator); emit the new row instead.
-            inTable = true;
-            out.push(`| ${args.index} | ${escapeCell(args.row.value)} | ${escapeCell(args.row.sourceRid)} | ${escapeCell(args.row.source)} | ${escapeCell(args.row.status)} |`);
-            // Then skip the original placeholder by NOT pushing the current line.
-            continue;
-        }
-        if (inTable) {
-            // Past the table — push lines verbatim.
-            out.push(line);
-        }
-        else {
-            out.push(line);
-        }
-    }
-    return out.join('\n');
-}
-function appendRowAfterTable(body, args) {
-    // Find the last `|`-prefixed line and insert the new row right after it.
-    const lines = body.split(/\r?\n/);
-    let lastTableLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/^\s*\|/.test(lines[i] ?? ''))
-            lastTableLine = i;
-    }
-    if (lastTableLine === -1) {
-        // No table found in body — append the row at the end as a new table
-        // tail. (Defensive: parseAuditInventoryTable already guarded this.)
-        return (body.replace(/\n*$/, '\n') +
-            `| ${args.index} | ${escapeCell(args.row.value)} | ${escapeCell(args.row.sourceRid)} | ${escapeCell(args.row.source)} | ${escapeCell(args.row.status)} |\n`);
-    }
-    const newRow = `| ${args.index} | ${escapeCell(args.row.value)} | ${escapeCell(args.row.sourceRid)} | ${escapeCell(args.row.source)} | ${escapeCell(args.row.status)} |`;
-    const before = lines.slice(0, lastTableLine + 1);
-    const after = lines.slice(lastTableLine + 1);
-    return [...before, newRow, ...after].join('\n');
-}
-async function readOptionalFile(absolutePath) {
-    try {
-        return await readFile(absolutePath, 'utf8');
-    }
-    catch (error) {
-        if (isEnoent(error))
-            return null;
-        throw error;
-    }
-}
-function isEnoent(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        error.code === 'ENOENT');
-}
-/** Serialize a `BusinessKnowledge` to the markdown-table body format.
- *  Matches the bootstrap template at `.peaks/project-scan/business-knowledge.md`. */
-function renderBusinessKnowledgeBody(knowledge) {
-    const header = [
-        '# Business Knowledge',
-        '',
-        '> Auto-managed by `peaks-prd` sediment step (v2.11.0 D3 / Group C Tier 5).',
-        '> Schema: `BusinessKnowledge { schemaVersion: 1; concepts: BusinessConcept[] }`.',
-        '> Idempotency key: `(concept, sourceRid)` — re-running with the same tuple does not duplicate.',
-        '',
-        '| Concept | Definition | Source | Decided | Evidence |',
-        '|---|---|---|---|---|'
-    ];
-    const rows = knowledge.concepts.map(formatRow);
-    const footer = [
-        '',
-        '## How to append',
-        '',
-        '```bash',
-        '# programmatic (peaks-txt sediment step):',
-        '#   appendBusinessConcept({ projectRoot, concept })',
-        '#   see src/services/prd/project-scan-sediment.ts',
-        '```',
-        '',
-        '## How to consume',
-        '',
-        '```bash',
-        'peaks project knowledge --project <repo> --json',
-        'peaks project knowledge --project <repo> --filter <concept-substr> --json',
-        '```',
-        ''
-    ];
-    return ['---\nschemaVersion: 1\n---\n', ...header, ...rows, ...footer].join('\n');
-}
-function formatRow(c) {
-    return `| ${escapeCell(c.concept)} | ${escapeCell(c.definition)} | ${escapeCell(c.sourceRid)} | ${escapeCell(c.decidedAt)} | ${escapeCell(c.evidence)} |`;
-}
-/** Escape pipe characters + newlines for safe markdown-table cells. */
-function escapeCell(value) {
-    return value.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
-}

package/dist/src/services/prd/project-scan-types.d.ts

@@ -1,66 +0,0 @@
-/**
- * peaks-prd project-scan — types.
- *
- * `.peaks/project-scan/` is the **git-tracked** project-level artifact
- * that carries tech-stack snapshot + business-knowledge sediment. It
- * is the load-bearing input to peaks-prd Step 0.8 ("Read project-scan
- * before brainstorm") and the output sink for peaks-txt's sediment
- * step (Group C, AC-5).
- *
- * Layout:
- *   .peaks/project-scan/
- *     project-scan.md         — tech stack snapshot + architecture
- *     business-knowledge.md   — structured concept table (this file)
- *
- * Schema invariants:
- *   - `schemaVersion` is bumped on any breaking shape change.
- *   - `BusinessConcept.concept` + `sourceRid` is the idempotency key
- *     for sediment appends (Group C MUST NOT duplicate on re-run).
- */
-/** Tech-stack snapshot. `language` / `packageManager` are closed
- *  unions (Karpathy §2 — no string sprawl); `runtime` / `buildTool`
- *  are free-form (peaks-loop does not constrain them). */
-export interface ProjectScanTechStack {
-    readonly language: 'typescript';
-    readonly packageManager: 'pnpm';
-    readonly runtime: string;
-    readonly buildTool?: string;
-}
-/** Library versions mirror `package.json` dependencies at snapshot
- *  time. The reader does NOT re-resolve semver — the snapshot is the
- *  truth at `capturedAt`. */
-export interface ProjectScanLibraryVersions {
-    readonly [packageName: string]: string;
-}
-/** Karpathy §2 5-anti-pattern self-check. Captured at snapshot time
- *  by the LLM that runs `peaks project scan`. Mirrors the
- *  `andrej-karpathy-skills:karpathy-guidelines` checklist. */
-export interface ProjectScanKarpathySelfCheck {
-    readonly simpleFirst: string;
-    readonly surgicalChanges: string;
-    readonly goalDriven: string;
-    readonly thinkBefore: string;
-}
-export interface ProjectScan {
-    readonly schemaVersion: 1;
-    readonly capturedAt: string;
-    readonly techStack: ProjectScanTechStack;
-    readonly libraryVersions: ProjectScanLibraryVersions;
-    readonly architecture: string;
-    readonly karpathySelfCheck: ProjectScanKarpathySelfCheck;
-}
-/** Single business concept — schema-sedimented (NOT free text, per
- *  D3 in `v2-11-rm-rd-techdoc-immutable-handoff`). The 5-tuple shape
- *  is enforced by the sediment writer (Group C) so peaks-prd can
- *  query it deterministically. */
-export interface BusinessConcept {
-    readonly concept: string;
-    readonly definition: string;
-    readonly sourceRid: string;
-    readonly decidedAt: string;
-    readonly evidence: string;
-}
-export interface BusinessKnowledge {
-    readonly schemaVersion: 1;
-    readonly concepts: readonly BusinessConcept[];
-}

package/dist/src/services/prd/project-scan-types.js

@@ -1,20 +0,0 @@
-/**
- * peaks-prd project-scan — types.
- *
- * `.peaks/project-scan/` is the **git-tracked** project-level artifact
- * that carries tech-stack snapshot + business-knowledge sediment. It
- * is the load-bearing input to peaks-prd Step 0.8 ("Read project-scan
- * before brainstorm") and the output sink for peaks-txt's sediment
- * step (Group C, AC-5).
- *
- * Layout:
- *   .peaks/project-scan/
- *     project-scan.md         — tech stack snapshot + architecture
- *     business-knowledge.md   — structured concept table (this file)
- *
- * Schema invariants:
- *   - `schemaVersion` is bumped on any breaking shape change.
- *   - `BusinessConcept.concept` + `sourceRid` is the idempotency key
- *     for sediment appends (Group C MUST NOT duplicate on re-run).
- */
-export {};

package/dist/src/services/preferences/preferences-service.d.ts

@@ -1,38 +0,0 @@
-import { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION, type ProjectPreferences } from './preferences-types.js';
-export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
-export type { ProjectPreferences } from './preferences-types.js';
-export declare function preferencesPath(projectRoot: string): string;
-export declare function loadPreferences(projectRoot: string): ProjectPreferences;
-export declare function savePreferences(projectRoot: string, overrides: Partial<ProjectPreferences>): ProjectPreferences;
-/**
- * Atomic write helper for preferences.json. Writes to `<path>.tmp-<pid>-<ts>`
- * and renames over the target. On Windows, `rename` is atomic for files
- * on the same volume; on POSIX, `rename(2)` is atomic by spec.
- */
-export declare function writeAtomic(filePath: string, prefs: ProjectPreferences): void;
-/**
- * Slice 2026-06-23-audit-4th #C1: migrate a legacy preferences.json
- * (any `schema_version` older than PREFERENCES_SCHEMA_VERSION) to the
- * current shape. Returns the migrated object + a list of changes
- * applied (for surfacing in the CLI envelope and the migration log).
- *
- * The v1 → v2 mapping fills in the `headroom.perTouchpoint` sub-keys
- * that v1 didn't track: each touchpoint gets the v1 `headroom.defaultMode`
- * (or 'balanced' if absent), and `compressMinBytes` is preserved
- * verbatim. v1's `agentShieldPrompt` and `loopAutonomousEnabled` were
- * already present, so they carry through unchanged. The `fanout` field
- * is new in v2 — it defaults to `{ defaultMode: 'fan-out' }` so the
- * pre-v2 behavior (peak-code SKILL instructed fan-out when ≥ 2 leaves)
- * is preserved.
- */
-export type MigrateResult = {
-    readonly fromVersion: string;
-    readonly toVersion: typeof PREFERENCES_SCHEMA_VERSION;
-    readonly migrated: ProjectPreferences;
-    readonly changes: readonly string[];
-    readonly written: boolean;
-};
-export declare function migratePreferences(projectRoot: string, opts?: {
-    write?: boolean;
-    now?: () => Date;
-}): MigrateResult | null;