peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/memory-commands.js

@@ -0,0 +1,129 @@
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { loadMemoryIndex, searchMemoryWithResults } from '../../services/memory/memory-search-service.js';
+import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { join } from 'node:path';
+const VALID_KINDS = [
+    'project',
+    'rule',
+    'decision',
+    'reference',
+    'feedback',
+    'convention',
+    'module',
+    'lesson',
+];
+export async function runMemoryList(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    try {
+        const snapshot = loadMemoryIndex(projectRoot);
+        const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
+            ? options.kind
+            : undefined;
+        const entries = kindFilter === undefined
+            ? snapshot.entries
+            : snapshot.entries.filter((e) => e.kind === kindFilter);
+        const warnings = [];
+        let pickedEntries = entries;
+        let pickedOutputPath = null;
+        let fzfVersion = null;
+        if (options.pick === true) {
+            const outputPath = join(projectRoot, '.peaks', 'memory', 'picked.json');
+            const byName = new Map(entries.map((e) => [e.name, e]));
+            const result = await pickFromList({
+                items: entries,
+                formatLine: (entry) => `${entry.name} | ${entry.kind} | ${entry.description.slice(0, 60)}`,
+                parseLine: (line) => {
+                    const parts = line.split('|').map((p) => p.trim());
+                    if (parts.length < 1)
+                        return null;
+                    const name = parts[0];
+                    if (name === undefined || name.length === 0)
+                        return null;
+                    return byName.get(name) ?? null;
+                },
+                outputPath,
+                meta: { kindFilter: kindFilter ?? null, totalCandidates: entries.length },
+                ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
+                projectRoot,
+                multi: true,
+                prompt: 'memory> '
+            });
+            pickedEntries = [...result.picked];
+            pickedOutputPath = result.outputPath;
+            fzfVersion = result.fzfVersion;
+        }
+        const nextActions = [];
+        if (pickedOutputPath !== null) {
+            nextActions.push(`Picked ${pickedEntries.length} entr(ies); written to ${pickedOutputPath}`);
+        }
+        if (entries.length === 0) {
+            nextActions.push('No entries match; run `peaks memory extract` to build the index from memory/*.md files.');
+        }
+        printResult(io, ok('memory.list', {
+            indexPath: snapshot.indexPath,
+            version: snapshot.version,
+            updatedAt: snapshot.updatedAt,
+            total: entries.length,
+            kindFilter: kindFilter ?? null,
+            entries,
+            ...(options.pick === true ? { picked: pickedEntries, pickedOutputPath, fzfVersion } : {})
+        }, warnings, nextActions), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_LIST_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks memory extract` to build the index from memory/*.md files');
+        }
+        printResult(io, fail('memory.list', code, message, { projectRoot }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export async function runMemorySearch(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const kindFilter = options.kind !== undefined && VALID_KINDS.includes(options.kind)
+        ? options.kind
+        : undefined;
+    try {
+        const out = await searchMemoryWithResults({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {}),
+        }, {
+            ...(options.compressResults === true ? { compressResults: true } : {})
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: out.matches.length,
+            matches: out.matches,
+            ...(out.compressedResults !== null ? { compressedResults: out.compressedResults } : {}),
+            warnings: [],
+        }, []), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'MEMORY_SEARCH_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Run `peaks memory extract --apply` to build the index from memory/*.md files');
+        }
+        if (code === 'EMPTY_QUERY') {
+            suggestions.push('Use `peaks memory index` to list all entries');
+        }
+        printResult(io, fail('memory.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}

package/dist/cli/commands/migrate-1-4-1-command.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004 subcommand.
+ *
+ * Cleanup helper for projects upgraded from 1.4.1 → 1.4.2. Moves per-session
+ * files from the legacy `.peaks/_runtime/<sid>/<role>/<file>.md` path into the canonical
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
+ * `--apply` to actually `rename` the files and remove emptied legacy dirs.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerMigrate1_4_1Command(workspace: Command, io: ProgramIO): void;

package/dist/cli/commands/migrate-1-4-1-command.js

@@ -0,0 +1,34 @@
+/**
+ * `peaks workspace migrate-1-4-1` — R004 subcommand.
+ *
+ * Cleanup helper for projects upgraded from 1.4.1 → 1.4.2. Moves per-session
+ * files from the legacy `.peaks/_runtime/<sid>/<role>/<file>.md` path into the canonical
+ * `.peaks/_runtime/<sid>/<role>/<file>.md` path. Default is dry-run; pass
+ * `--apply` to actually `rename` the files and remove emptied legacy dirs.
+ */
+import { ok, fail } from 'peaks-loop-shared/result';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { addJsonOption } from '../cli-helpers.js';
+import { planMigrate1_4_1, applyMigrate1_4_1 } from '../../services/workspace/migrate-1-4-1-service.js';
+export function registerMigrate1_4_1Command(workspace, io) {
+    addJsonOption(workspace
+        .command('migrate-1-4-1')
+        .description('R004: Move per-session files from the legacy `.peaks/_runtime/<sid>/<role>/<file>.md` path into the canonical `.peaks/_runtime/<sid>/<role>/<file>.md` path. ' +
+        'Default: dry-run. Pass --apply to actually `rename` the files and remove emptied legacy dirs. ' +
+        'Reads each file once, computes sha256, compares to canonical. Identical-content duplicates are removed from legacy. Content-mismatch files are reported and NOT deleted (manual review).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually rename the files and remove empty legacy dirs (destructive); without it, dry-run only', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const apply = options.apply === true;
+            const result = apply ? applyMigrate1_4_1(projectRoot) : planMigrate1_4_1(projectRoot);
+            const envelope = ok('workspace.migrate-1-4-1', result);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+        }
+        catch (err) {
+            const envelope = fail('workspace.migrate-1-4-1', 'MIGRATE_FAILED', err.message, null, ['Run with --apply to attempt the move (default is dry-run only)']);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/migrate-v2-10-to-v2-11-command.d.ts

@@ -0,0 +1,20 @@
+/**
+ * v2.11.0 — Group E (Tier 8): `peaks migrate v2-10-to-v2-11` command.
+ *
+ * Deprecation helper for projects upgraded from 2.10.0 → 2.11.0. The
+ * peaks-rd `tech-doc.md` output was removed in 2.11.0 (Group A). This
+ * migration prepends a YAML banner to every pre-2.11.0 session's
+ * `rd/tech-doc.md` file marking it as `deprecated: historical`. The
+ * immutable peaks-prd handoff at `prd/handoff.md` is the new source
+ * of truth; old files coexist (text-only — no file moves per
+ * Karpathy §3 surgical changes).
+ *
+ * Default: dry-run. Pass `--apply` to actually write.
+ * Idempotent: re-running on an already-migrated tree is a no-op
+ * (all files report `reason: 'already-deprecated'`).
+ *
+ * === Source: .peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md §"Tier 8" ===
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerMigrateV2ToV11Command(workspace: Command, io: ProgramIO): void;

package/dist/cli/commands/migrate-v2-10-to-v2-11-command.js

@@ -0,0 +1,52 @@
+/**
+ * v2.11.0 — Group E (Tier 8): `peaks migrate v2-10-to-v2-11` command.
+ *
+ * Deprecation helper for projects upgraded from 2.10.0 → 2.11.0. The
+ * peaks-rd `tech-doc.md` output was removed in 2.11.0 (Group A). This
+ * migration prepends a YAML banner to every pre-2.11.0 session's
+ * `rd/tech-doc.md` file marking it as `deprecated: historical`. The
+ * immutable peaks-prd handoff at `prd/handoff.md` is the new source
+ * of truth; old files coexist (text-only — no file moves per
+ * Karpathy §3 surgical changes).
+ *
+ * Default: dry-run. Pass `--apply` to actually write.
+ * Idempotent: re-running on an already-migrated tree is a no-op
+ * (all files report `reason: 'already-deprecated'`).
+ *
+ * === Source: .peaks/memory/2026-06-26-v2-11-rm-rd-techdoc-immutable-handoff.md §"Tier 8" ===
+ */
+import { addJsonOption } from '../cli-helpers.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { planV2ToV11Migration, applyV2ToV11Migration, dryRunV2ToV11Migration } from '../../services/migration/v2-10-to-v2-11-service.js';
+import { ok, fail } from 'peaks-loop-shared/result';
+export function registerMigrateV2ToV11Command(workspace, io) {
+    addJsonOption(workspace
+        .command('migrate-v2-10-to-v2-11')
+        .description('v2.11.0 Group E (Tier 8): prepend a YAML deprecation banner to every pre-v2.11.0 session\'s ' +
+        '`rd/tech-doc.md` file. Marks them `deprecated: historical` and points to the new peaks-prd ' +
+        'handoff as the source of truth. Text-only — no file moves. Default: dry-run; pass `--apply` ' +
+        'to actually write. Idempotent: re-running on an already-migrated tree is a no-op. Different ' +
+        'migration family from the legacy 0.5 to 1.4.1 runtime-layout helper — this command does NOT ' +
+        'move files, only prepends the banner.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'actually prepend the deprecation banner to each `rd/tech-doc.md` (idempotent); without it, dry-run only', false)).action(async (options) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
+            const apply = options.apply === true;
+            const result = apply
+                ? applyV2ToV11Migration(planV2ToV11Migration(projectRoot))
+                : dryRunV2ToV11Migration(projectRoot);
+            const envelope = ok('workspace.migrate-v2-10-to-v2-11', result);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const envelope = fail('workspace.migrate-v2-10-to-v2-11', 'MIGRATE_V2_10_TO_V2_11_FAILED', message, null, [
+                'Run with --apply to attempt the deprecation banner write (default is dry-run only)',
+                'Verify the project path exists and contains at least one .peaks/_runtime/<sid>/rd/tech-doc.md'
+            ]);
+            io.stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/mut-commands.d.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import { type StrykerInvoker } from 'peaks-loop-mut';
+import type { ProgramIO } from '../cli-helpers.js';
+export interface MutCommandsOptions {
+    readonly invokeStryker: StrykerInvoker;
+}
+/**
+ * Construct the `peaks mut` family as a standalone Commander command.
+ * Returns the parent `mut` Command so callers can attach it under any
+ * root program (used both by `registerMutCommands` in production and
+ * directly by the unit tests).
+ */
+export declare function createMutCommands(opts: MutCommandsOptions): Command;
+/**
+ * Program-level wiring: attach the `peaks mut` family to the root
+ * program with the production Stryker invoker. Tests should use
+ * `createMutCommands({ invokeStryker })` instead so the heavy
+ * @stryker-mutator/core runtime stays out of the unit-test path.
+ */
+export declare function registerMutCommands(program: Command, _io: ProgramIO): void;

package/dist/cli/commands/mut-commands.js

@@ -0,0 +1,235 @@
+/**
+ * `peaks mut <sub>` — CLI surface for the mutation test-quality skill.
+ * Per spec §4.2 验收审计 + §7 阶段二.
+ *
+ * Hard rules:
+ *   - One-axis envelope layout (Plan 1 followup hotfix, commit 81f00ce):
+ *     `--session-id` is REQUIRED on every artifact-producing subcommand,
+ *     and `--change-id` is NEVER accepted on the parser.
+ *   - H6 (CLI裁决, not LLM): `thresholds.passed` is computed by the
+ *     ReportBuilder, not by the LLM. The CLI merely surfaces it.
+ *   - H8 (audit trail hashable): every artifact carries a 64-hex sha256
+ *     that chains back to TACT.sig via the `inputSig` field.
+ *   - KISS: keep the public surface narrow — run / mutants / asserts /
+ *     report. The CLI is a thin orchestrator over the service layer.
+ */
+import { readFile } from 'node:fs/promises';
+import { Command } from 'commander';
+import { scanAssertions, runMutation, buildMutReport, createProductionStrykerInvoker, MutReportSchema, } from 'peaks-loop-mut';
+/**
+ * Pure helper: a stub AssertionsReport used when only Stryker ran.
+ * The mutants-only path does NOT touch the AST scanner; we still need
+ * a structurally-valid `assertions` block so the Zod schema accepts
+ * the assembled report.
+ */
+function emptyAssertions() {
+    return {
+        totalAssertions: 0,
+        weakAssertions: 0,
+        weakRate: 0,
+        weakPatterns: [],
+    };
+}
+/**
+ * Pure helper: a stub MutationReport used when only the assertion
+ * scan ran. Mirrors the asserts-only path's invariants (killRate = 0,
+ * mutantsTotal = 0, tool = 'stryker' for forward compatibility).
+ */
+function emptyMutation() {
+    return {
+        tool: 'stryker',
+        mutantsTotal: 0,
+        mutantsKilled: 0,
+        mutantsSurvived: 0,
+        mutantsTimeout: 0,
+        killRate: 0,
+        byFile: [],
+    };
+}
+/**
+ * Emit a one-line JSON envelope describing the run's outcome. Used by
+ * both `--json` and the human-readable branches so the `passed` /
+ * `sha256` shape stays consistent regardless of TTY mode.
+ */
+function emitSummary(json, payload) {
+    if (json) {
+        process.stdout.write(JSON.stringify(payload) + '\n');
+    }
+    else {
+        process.stdout.write(`mut-report.json: ${payload.path}\nsha256: ${payload.sha256}\npassed: ${payload.passed}\n`);
+    }
+}
+/**
+ * Construct the `peaks mut` family as a standalone Commander command.
+ * Returns the parent `mut` Command so callers can attach it under any
+ * root program (used both by `registerMutCommands` in production and
+ * directly by the unit tests).
+ */
+export function createMutCommands(opts) {
+    const mut = new Command('mut').description('peaks-mut: mutation testing + assertion validity scan (spec §4.2 / §7)');
+    mut
+        .command('run')
+        .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
+        .requiredOption('--project <path>', 'project root')
+        .requiredOption('--test-files <files...>', 'test files to mutate against')
+        .requiredOption('--input-sig <hex>', 'TACT.sig (sha256) for chain')
+        .requiredOption('--session-id <sid>', 'session id; CLI writes artifacts only under .peaks/_runtime/<sid>/mut/ (one-axis layout)')
+        .requiredOption('--out <path>', 'output path for mut-report.json')
+        .option('--json', 'machine-readable output', false)
+        .action(async (a) => {
+        const { mutation } = await runMutation({
+            project: a.project,
+            testFiles: a.testFiles,
+            invokeStryker: opts.invokeStryker,
+        });
+        const assertions = await scanAssertions({
+            project: a.project,
+            testFiles: a.testFiles,
+        });
+        const report = await buildMutReport({
+            inputSig: a.inputSig,
+            out: a.out,
+            mutation,
+            assertions,
+        });
+        emitSummary(a.json, {
+            ok: true,
+            sha256: report.sha256,
+            passed: report.thresholds.passed,
+            path: a.out,
+        });
+        if (!report.thresholds.passed) {
+            // H6: CLI裁决 — threshold breach is a non-zero exit so callers
+            // (peaks-rd, peaks-qa, CI) can block on it without parsing
+            // stdout.
+            process.exitCode = 1;
+        }
+    });
+    mut
+        .command('mutants')
+        .description('Run Stryker only; write a stub-assertions mut-report.json. One-axis: --session-id required.')
+        .requiredOption('--project <path>', 'project root')
+        .requiredOption('--test-files <files...>', 'test files to mutate against')
+        .requiredOption('--input-sig <hex>', 'TACT.sig')
+        .requiredOption('--session-id <sid>', 'session id')
+        .requiredOption('--out <path>', 'output path for mut-report.json')
+        .option('--json', 'machine-readable output', false)
+        .action(async (a) => {
+        const { mutation } = await runMutation({
+            project: a.project,
+            testFiles: a.testFiles,
+            invokeStryker: opts.invokeStryker,
+        });
+        const report = await buildMutReport({
+            inputSig: a.inputSig,
+            out: a.out,
+            mutation,
+            assertions: emptyAssertions(),
+        });
+        emitSummary(a.json, {
+            ok: true,
+            sha256: report.sha256,
+            passed: report.thresholds.passed,
+            path: a.out,
+        });
+        if (!report.thresholds.passed) {
+            process.exitCode = 1;
+        }
+    });
+    mut
+        .command('asserts')
+        .description('Run the assertion scan only; write a mut-report.json with empty mutation block. One-axis: --session-id required.')
+        .requiredOption('--project <path>', 'project root')
+        .requiredOption('--test-files <files...>', 'test files to scan')
+        .requiredOption('--input-sig <hex>', 'TACT.sig')
+        .requiredOption('--session-id <sid>', 'session id')
+        .requiredOption('--out <path>', 'output path for mut-report.json')
+        .option('--json', 'machine-readable output', false)
+        .action(async (a) => {
+        const assertions = await scanAssertions({
+            project: a.project,
+            testFiles: a.testFiles,
+        });
+        const report = await buildMutReport({
+            inputSig: a.inputSig,
+            out: a.out,
+            mutation: emptyMutation(),
+            assertions,
+        });
+        emitSummary(a.json, {
+            ok: true,
+            sha256: report.sha256,
+            passed: report.thresholds.passed,
+            path: a.out,
+        });
+        if (!report.thresholds.passed) {
+            process.exitCode = 1;
+        }
+    });
+    mut
+        .command('report')
+        .description('Re-read a previously-written mut-report.json (no Stryker / scan invocation). One-axis: --session-id required for the audit trail.')
+        .requiredOption('--in <path>', 'input mut-report.json path')
+        .requiredOption('--session-id <sid>', 'session id')
+        .option('--json', 'machine-readable output', false)
+        .action(async (a) => {
+        const raw = await readFile(a.in, 'utf8');
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(raw);
+        }
+        catch (err) {
+            process.stderr.write(`INVALID_JSON: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const parsed = MutReportSchema.safeParse(parsedJson);
+        if (!parsed.success) {
+            process.stderr.write(`INVALID: ${parsed.error.message}\n`);
+            process.exitCode = 2;
+            return;
+        }
+        const r = parsed.data;
+        const summary = {
+            mutation: {
+                tool: r.mutation.tool,
+                killRate: r.mutation.killRate,
+            },
+            assertions: {
+                total: r.assertions.totalAssertions,
+                weak: r.assertions.weakAssertions,
+                weakRate: r.assertions.weakRate,
+            },
+            thresholds: { passed: r.thresholds.passed },
+            followups: r.followups.length,
+            sha256: r.sha256,
+            sessionId: a.sessionId,
+        };
+        if (a.json) {
+            process.stdout.write(JSON.stringify(summary) + '\n');
+        }
+        else {
+            process.stdout.write([
+                `mutation: tool=${r.mutation.tool} killRate=${(r.mutation.killRate * 100).toFixed(1)}%`,
+                `assertions: total=${r.assertions.totalAssertions} weak=${r.assertions.weakAssertions} rate=${(r.assertions.weakRate * 100).toFixed(1)}%`,
+                `thresholds: passed=${r.thresholds.passed}`,
+                `followups: ${r.followups.length}`,
+                `sha256: ${r.sha256}`,
+            ].join('\n') + '\n');
+        }
+        if (!r.thresholds.passed) {
+            process.exitCode = 1;
+        }
+    });
+    return mut;
+}
+/**
+ * Program-level wiring: attach the `peaks mut` family to the root
+ * program with the production Stryker invoker. Tests should use
+ * `createMutCommands({ invokeStryker })` instead so the heavy
+ * @stryker-mutator/core runtime stays out of the unit-test path.
+ */
+export function registerMutCommands(program, _io) {
+    const invokeStryker = createProductionStrykerInvoker();
+    program.addCommand(createMutCommands({ invokeStryker }));
+}

package/dist/cli/commands/observability-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `peaks observability <subcommand>` — Slice B/C of v2.11.1.
+ *
+ * Slice B ships 4 read-only subcommands (AC-1 to AC-4):
+ *   - `peaks observability status`         (AC-1)
+ *   - `peaks observability slices`         (AC-2)
+ *   - `peaks observability fanout`         (AC-3)
+ *   - `peaks observability repair-cycles`  (AC-4)
+ *
+ * `peaks observability report` (AC-5) lands in Slice D when the
+ * markdown report formatter is implemented.
+ *
+ * Read-only — never writes. Reads the JSONL metrics files emitted
+ * by the `peaks request transition` hook (Slice A) plus the future
+ * Slice C hook sites (dispatch / checkpoint / mode-gate / context
+ * / post-compact). The aggregations tolerate zero events gracefully
+ * so each subcommand returns a meaningful empty result on a fresh
+ * tree.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerObservabilityCommands(program: Command, io: ProgramIO): void;