peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/core/memory-command-shared.d.ts

@@ -0,0 +1,25 @@
+import { type ProgramIO } from '../../cli-helpers.js';
+/** A `--dry-run --apply` refusal, resolved per verb. */
+export type FlagConflict = {
+    readonly command: string;
+    readonly code: string;
+    readonly nextActions: readonly string[];
+    readonly json: boolean | undefined;
+    readonly dryRun: boolean | undefined;
+    readonly apply: boolean | undefined;
+};
+/**
+ * `--dry-run` and `--apply` are mutually exclusive: previewing and writing in
+ * one invocation has no defined meaning, so refuse before any work happens.
+ */
+export declare function refuseBothFlags(io: ProgramIO, conflict: FlagConflict): boolean;
+/** A verb whose lazy `memory-commands.ts` import or run failed. */
+export type BootstrapFailure = {
+    readonly command: string;
+    readonly code: string;
+    readonly message: string;
+    readonly json: boolean | undefined;
+    readonly nextActions?: readonly string[] | undefined;
+};
+/** Print the `*_BOOTSTRAP_FAILED` envelope and mark the process failed. */
+export declare function emitBootstrapFailure(io: ProgramIO, failure: BootstrapFailure): void;

package/dist/cli/commands/core/memory-command-shared.js

@@ -0,0 +1,20 @@
+import { fail } from 'peaks-loop-shared/result';
+import { printResult } from '../../cli-helpers.js';
+/**
+ * `--dry-run` and `--apply` are mutually exclusive: previewing and writing in
+ * one invocation has no defined meaning, so refuse before any work happens.
+ */
+export function refuseBothFlags(io, conflict) {
+    if (!(conflict.dryRun === true && conflict.apply === true))
+        return false;
+    printResult(io, fail(conflict.command, conflict.code, 'Use either --dry-run or --apply, not both', {}, [
+        ...conflict.nextActions
+    ]), conflict.json);
+    process.exitCode = 1;
+    return true;
+}
+/** Print the `*_BOOTSTRAP_FAILED` envelope and mark the process failed. */
+export function emitBootstrapFailure(io, failure) {
+    printResult(io, fail(failure.command, failure.code, failure.message, {}, [...(failure.nextActions ?? [])]), failure.json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/core/memory-command.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from 'commander';
-import { type ProgramIO } from '../../cli-helpers.js';
+import type { ProgramIO } from '../../cli-helpers.js';
 export declare function registerMemoryCommand(program: Command, io: ProgramIO): void;

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

@@ -1,230 +1,9 @@
-import { describeMemoryBlockDrops, executeProjectMemoryBackup, executeProjectMemoryExtract, SENSITIVE_MEMORY_CHECKS, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult, UnsafeMemoryError, VALID_PROJECT_MEMORY_KINDS } from '../../../services/memory/project-memory-service.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
-/** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
-const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
+import { registerMemoryDelegatedVerbs } from './memory-delegated-verbs.js';
+import { registerMemoryExtractCommand } from './memory-extract-command.js';
+import { registerMemorySyncCommand } from './memory-sync-command.js';
 export function registerMemoryCommand(program, io) {
     const memory = program.command('memory').description('Manage project-local Peaks memory');
-    addJsonOption(memory
-        .command('extract')
-        .description('Extract stable project memory from skill artifacts into project .peaks/memory')
-        .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
-        .option('--dry-run', 'preview writes without changing files')
-        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
-        if (options.dryRun === true && options.apply === true) {
-            printResult(io, fail('memory.extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const result = executeProjectMemoryExtract({
-                projectRoot: options.project,
-                artifactPaths: options.artifact,
-                apply: options.apply === true
-            });
-            // A block that was found but not extracted must not vanish silently: the
-            // parser's rejection reasons ride the envelope's existing `warnings`
-            // channel (JSON: `warnings[]`; human: `warning: …` on stderr). `data` is
-            // unchanged — this adds no field to the summary.
-            printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result), describeMemoryBlockDrops(result.droppedBlocks)), options.json);
-        }
-        catch (error) {
-            const refusal = error instanceof UnsafeMemoryError ? error : null;
-            printResult(io, fail('memory.extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), 
-            // The check and the term are facts about the failure, so they ride
-            // the envelope's data — not just its prose. `fail()` redacts
-            // `message` (see `UnsafeMemoryError`), so the term would otherwise
-            // reach the reader as `[redacted]`; `data` is passed through.
-            refusal === null ? {} : { check: refusal.check, matchedTerm: refusal.matchedTerm }, memoryExtractNextActions(refusal)), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(memory
-        .command('sync')
-        .description('Back up project .peaks/memory into the artifact workspace')
-        .requiredOption('--project <path>', 'target project root')
-        .requiredOption('--workspace <path>', 'artifact workspace path')
-        .option('--dry-run', 'preview copies without changing files')
-        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
-        if (options.dryRun === true && options.apply === true) {
-            printResult(io, fail('memory.sync', 'INVALID_MEMORY_SYNC_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview copies, or pass --apply to back up memories']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const result = executeProjectMemoryBackup({
-                projectRoot: options.project,
-                artifactWorkspacePath: options.workspace,
-                apply: options.apply === true
-            });
-            printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
-        }
-        catch (error) {
-            printResult(io, fail('memory.sync', 'MEMORY_SYNC_FAILED', getErrorMessage(error), {}, [
-                'Use an artifact workspace outside the project root'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(memory
-        .command('list')
-        .description('List all memory entries from .peaks/memory/index.json. Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/memory/picked.json.')
-        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
-        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
-        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
-        .option('--summary', 'emit counts + names-of-first-N only (≤ 2 KB) instead of the full entry array; the default envelope is unchanged')
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
-        void import('../memory-commands.js')
-            .then(({ runMemoryList }) => {
-            void runMemoryList(io, {
-                ...(options.kind !== undefined ? { kind: options.kind } : {}),
-                ...(options.pick === true ? { pick: true } : {}),
-                ...(options.fzfBin ? { fzfBin: options.fzfBin } : {}),
-                ...(options.project !== undefined ? { project: options.project } : {}),
-                ...(options.summary === true ? { summary: true } : {}),
-                ...(options.json !== undefined ? { json: options.json } : {})
-            });
-        })
-            .catch((error) => {
-            const msg = /brew install fzf|apt-get install fzf|older than required/.test(getErrorMessage(error))
-                ? 'fzf binary not found or too old. Install with: brew install fzf (or apt: apt-get install fzf). peaks memory list --pick requires fzf >= 0.38.'
-                : getErrorMessage(error);
-            const code = /brew install fzf|apt-get install fzf|older than required/.test(msg)
-                ? 'FZF_UNAVAILABLE'
-                : 'MEMORY_LIST_BOOTSTRAP_FAILED';
-            printResult(io, fail('memory.list', code, msg, {}, [
-                'Install fzf or run without --pick to list entries as JSON'
-            ]), options.json);
-            if (code === 'FZF_UNAVAILABLE')
-                process.exitCode = 127;
-            else
-                process.exitCode = 1;
-        });
-    });
-    addJsonOption(memory
-        .command('reindex')
-        .description('Rebuild .peaks/memory/index.json from every memory file on disk and regenerate MEMORY.md; reports unclassified files and orphans both ways. Dry-run by default; pass --apply to write.')
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')
-        .option('--dry-run', 'report drift without writing (default)')
-        .option('--apply', 'rebuild index.json and regenerate MEMORY.md')
-        .option('--summary', 'emit drift counts + names-of-first-N only (≤ 2 KB) instead of the full arrays; the default envelope is unchanged')).action((options) => {
-        void import('../memory-commands.js')
-            .then(({ runMemoryReindex }) => {
-            void runMemoryReindex(io, {
-                ...(options.project !== undefined ? { project: options.project } : {}),
-                ...(options.dryRun === true ? { dryRun: true } : {}),
-                ...(options.apply === true ? { apply: true } : {}),
-                ...(options.summary === true ? { summary: true } : {}),
-                ...(options.json !== undefined ? { json: options.json } : {})
-            });
-        })
-            .catch((error) => {
-            printResult(io, fail('memory.reindex', 'MEMORY_REINDEX_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        });
-    });
-    addJsonOption(memory
-        .command('ingest')
-        .description('Import memories written by the IDE-side agent (~/.claude/projects/<hash>/memory/*.md) into the peaks-owned .peaks/memory store. The IDE-side dir is read-only. Dry-run by default; pass --apply to write.')
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')
-        .option('--source-dir <path>', 'override the IDE-side memory directory')
-        .option('--dry-run', 'preview imports without writing (default)')
-        .option('--apply', 'write normalized memories into .peaks/memory')).action((options) => {
-        void import('../memory-commands.js')
-            .then(({ runMemoryIngest }) => {
-            void runMemoryIngest(io, {
-                ...(options.project !== undefined ? { project: options.project } : {}),
-                ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
-                ...(options.dryRun === true ? { dryRun: true } : {}),
-                ...(options.apply === true ? { apply: true } : {}),
-                ...(options.json !== undefined ? { json: options.json } : {})
-            });
-        })
-            .catch((error) => {
-            printResult(io, fail('memory.ingest', 'MEMORY_INGEST_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        });
-    });
-    addJsonOption(memory
-        .command('rotate')
-        .description('Tier-driven retention for .peaks/memory/ (sediment pruning policy, tier 1: archive only, never delete). Tier assignment: explicit `metadata.tier: A|B|C|D` wins; else files under archived/ are D, files pinned in MEMORY.md are B, kinds rule/convention/project-rule are A, kinds decision/reference/feedback/module/bug/investigation/technical-pattern are B, everything else is C. Tier C older than 6 months (frontmatter updatedAt/updated/modified, else file mtime) and not pinned is archived; tier D is reported as a delete-candidate only. Tier A/B are never selected, every candidate must pass a reference grep against src/ + skills/, and --apply refuses an empty plan or a failed gate. Dry-run by default.')
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')
-        .option('--dry-run', 'report the rotation plan without moving anything (default)')
-        .option('--apply', 'move tier-C candidates into .peaks/memory/archived/')).action((options) => {
-        void import('../memory-commands.js')
-            .then(({ runMemoryRotate }) => {
-            void runMemoryRotate(io, {
-                ...(options.project !== undefined ? { project: options.project } : {}),
-                ...(options.dryRun === true ? { dryRun: true } : {}),
-                ...(options.apply === true ? { apply: true } : {}),
-                ...(options.json !== undefined ? { json: options.json } : {})
-            });
-        })
-            .catch((error) => {
-            printResult(io, fail('memory.rotate', 'MEMORY_ROTATE_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        });
-    });
-    addJsonOption(memory
-        .command('search <query>')
-        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
-        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
-        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
-        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
-        // Lazy import avoids a top-of-file import cycle (memory-commands.ts
-        // imports services that the rest of this file may also touch).
-        void import('../memory-commands.js')
-            .then(({ runMemorySearch }) => {
-            void runMemorySearch(io, {
-                query,
-                ...(options.kind !== undefined ? { kind: options.kind } : {}),
-                ...(options.limit !== undefined ? { limit: options.limit } : {}),
-                ...(options.project !== undefined ? { project: options.project } : {}),
-                ...(options.json !== undefined ? { json: options.json } : {})
-            });
-        })
-            .catch((error) => {
-            printResult(io, fail('memory.search', 'MEMORY_SEARCH_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
-            process.exitCode = 1;
-        });
-    });
-}
-/**
- * The remedy for a failed `memory extract`, chosen by the check that refused
- * the write — the same `SENSITIVE_MEMORY_CHECKS` values the refusal message
- * and envelope data are built from, so the message, the data and the advice
- * cannot drift apart.
- *
- * WHY IT IS NOT ONE STATIC STRING. Every failure used to get "Check artifact
- * paths and remove secrets before extracting memory" — including a refusal
- * raised only because a memory TITLE contained a word like `authority`
- * (slice C0). There was no secret anywhere in that memory, so the one thing
- * the hint told the user to do was the one thing that could not help: it sent
- * check that actually failed.
- *
- * `null` (a failure that is not a safety refusal — a path escape, a missing
- * artifact) keeps the pre-C0 hint, which is about paths and secrets rather
- * than about a check.
- */
-function memoryExtractNextActions(refusal) {
-    if (refusal === null) {
-        return ['Check artifact paths and remove secrets before extracting memory'];
-    }
-    if (refusal.check === SENSITIVE_MEMORY_CHECKS.title) {
-        return [
-            'Retitle the memory so it is not named after a credential term, then re-run memory extract'
-        ];
-    }
-    if (refusal.check === SENSITIVE_MEMORY_CHECKS.content) {
-        // Name the rule, not just the family. `matchedTerm` is a closed id
-        // (`credential-assignment`, `bearer-value`, `pem-private-key`, …), so the
-        // reader can tell a credential in the text from a sentence that merely has
-        // the shape of one — which is the difference between removing a value and
-        // rewording prose.
-        return [
-            `Remove the credential value the "${refusal.matchedTerm}" pattern matched, then re-run memory extract`
-        ];
-    }
-    return ['Remove the credential value from the memory content, then re-run memory extract'];
+    registerMemoryExtractCommand(memory, io);
+    registerMemorySyncCommand(memory, io);
+    registerMemoryDelegatedVerbs(memory, io);
 }

package/dist/cli/commands/core/memory-delegated-verbs.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+/** The five verbs whose bodies live in `memory-commands.ts`, in shipping order. */
+export declare function registerMemoryDelegatedVerbs(memory: Command, io: ProgramIO): void;

package/dist/cli/commands/core/memory-delegated-verbs.js

@@ -0,0 +1,178 @@
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+import { fail } from 'peaks-loop-shared/result';
+import { VALID_PROJECT_MEMORY_KINDS } from '../../../services/memory/project-memory-service.js';
+import { emitBootstrapFailure } from './memory-command-shared.js';
+/** Derived from the canonical kind vocabulary — never hand-maintain a list here. */
+const KIND_HELP = VALID_PROJECT_MEMORY_KINDS.join(', ');
+/**
+ * Call a run function from the lazily imported `memory-commands.js`.
+ *
+ * The dynamic import avoids a top-of-file import cycle (memory-commands.ts
+ * imports services the rest of this family also touches).
+ */
+function delegateMemoryRun(args) {
+    void import('../memory-commands.js')
+        .then((mod) => {
+        void args.build(mod)(args.io, args.options);
+    })
+        .catch((error) => {
+        emitBootstrapFailure(args.io, {
+            command: args.spec.command,
+            code: args.spec.code,
+            message: getErrorMessage(error),
+            json: args.spec.json,
+            nextActions: args.spec.nextActions
+        });
+    });
+}
+/** The bootstrap hint `memory list --pick` gives when fzf is missing or old. */
+const FZF_UNAVAILABLE = /brew install fzf|apt-get install fzf|older than required/;
+const FZF_MESSAGE = 'fzf binary not found or too old. Install with: brew install fzf (or apt: apt-get install fzf). peaks memory list --pick requires fzf >= 0.38.';
+/**
+ * `--pick` needs a real fzf, so a missing binary is its own refusal with its
+ * own exit code (127, the shell's "command not found") rather than a generic
+ * bootstrap failure.
+ */
+function listBootstrapFailure(io, options, error) {
+    const msg = FZF_UNAVAILABLE.test(getErrorMessage(error)) ? FZF_MESSAGE : getErrorMessage(error);
+    const code = FZF_UNAVAILABLE.test(msg) ? 'FZF_UNAVAILABLE' : 'MEMORY_LIST_BOOTSTRAP_FAILED';
+    printResult(io, fail('memory.list', code, msg, {}, [
+        'Install fzf or run without --pick to list entries as JSON'
+    ]), options.json);
+    if (code === 'FZF_UNAVAILABLE')
+        process.exitCode = 127;
+    else
+        process.exitCode = 1;
+}
+function registerMemoryList(memory, io) {
+    addJsonOption(memory
+        .command('list')
+        .description('List all memory entries from .peaks/memory/index.json. Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/memory/picked.json.')
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
+        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
+        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
+        .option('--summary', 'emit counts + names-of-first-N only (≤ 2 KB) instead of the full entry array; the default envelope is unchanged')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        void import('../memory-commands.js')
+            .then(({ runMemoryList }) => {
+            void runMemoryList(io, {
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.pick === true ? { pick: true } : {}),
+                ...(options.fzfBin ? { fzfBin: options.fzfBin } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.summary === true ? { summary: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {})
+            });
+        })
+            .catch((error) => listBootstrapFailure(io, options, error));
+    });
+}
+function registerMemoryReindex(memory, io) {
+    addJsonOption(memory
+        .command('reindex')
+        .description('Rebuild .peaks/memory/index.json from every memory file on disk and regenerate MEMORY.md; reports unclassified files and orphans both ways. Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--dry-run', 'report drift without writing (default)')
+        .option('--apply', 'rebuild index.json and regenerate MEMORY.md')
+        .option('--summary', 'emit drift counts + names-of-first-N only (≤ 2 KB) instead of the full arrays; the default envelope is unchanged')).action((options) => {
+        delegateMemoryRun({
+            io,
+            spec: {
+                command: 'memory.reindex',
+                code: 'MEMORY_REINDEX_BOOTSTRAP_FAILED',
+                json: options.json
+            },
+            options: {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.summary === true ? { summary: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {})
+            },
+            build: (mod) => mod.runMemoryReindex
+        });
+    });
+}
+function registerMemoryIngest(memory, io) {
+    addJsonOption(memory
+        .command('ingest')
+        .description('Import memories written by the IDE-side agent (~/.claude/projects/<hash>/memory/*.md) into the peaks-owned .peaks/memory store. The IDE-side dir is read-only. Dry-run by default; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--source-dir <path>', 'override the IDE-side memory directory')
+        .option('--dry-run', 'preview imports without writing (default)')
+        .option('--apply', 'write normalized memories into .peaks/memory')).action((options) => {
+        delegateMemoryRun({
+            io,
+            spec: {
+                command: 'memory.ingest',
+                code: 'MEMORY_INGEST_BOOTSTRAP_FAILED',
+                json: options.json
+            },
+            options: {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.sourceDir !== undefined ? { sourceDir: options.sourceDir } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {})
+            },
+            build: (mod) => mod.runMemoryIngest
+        });
+    });
+}
+function registerMemoryRotate(memory, io) {
+    addJsonOption(memory
+        .command('rotate')
+        .description('Tier-driven retention for .peaks/memory/ (sediment pruning policy, tier 1: archive only, never delete). Tier assignment: explicit `metadata.tier: A|B|C|D` wins; else files under archived/ are D, files pinned in MEMORY.md are B, kinds rule/convention/project-rule are A, kinds decision/reference/feedback/module/bug/investigation/technical-pattern are B, everything else is C. Tier C older than 6 months (frontmatter updatedAt/updated/modified, else file mtime) and not pinned is archived; tier D is reported as a delete-candidate only. Tier A/B are never selected, every candidate must pass a reference grep against src/ + skills/, and --apply refuses an empty plan or a failed gate. Dry-run by default.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--dry-run', 'report the rotation plan without moving anything (default)')
+        .option('--apply', 'move tier-C candidates into .peaks/memory/archived/')).action((options) => {
+        delegateMemoryRun({
+            io,
+            spec: {
+                command: 'memory.rotate',
+                code: 'MEMORY_ROTATE_BOOTSTRAP_FAILED',
+                json: options.json
+            },
+            options: {
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.dryRun === true ? { dryRun: true } : {}),
+                ...(options.apply === true ? { apply: true } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {})
+            },
+            build: (mod) => mod.runMemoryRotate
+        });
+    });
+}
+function registerMemorySearch(memory, io) {
+    addJsonOption(memory
+        .command('search <query>')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--kind <kind>', `filter by memory kind (one of: ${KIND_HELP})`)
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        delegateMemoryRun({
+            io,
+            spec: {
+                command: 'memory.search',
+                code: 'MEMORY_SEARCH_BOOTSTRAP_FAILED',
+                json: options.json
+            },
+            options: {
+                query,
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {})
+            },
+            build: (mod) => mod.runMemorySearch
+        });
+    });
+}
+/** The five verbs whose bodies live in `memory-commands.ts`, in shipping order. */
+export function registerMemoryDelegatedVerbs(memory, io) {
+    registerMemoryList(memory, io);
+    registerMemoryReindex(memory, io);
+    registerMemoryIngest(memory, io);
+    registerMemoryRotate(memory, io);
+    registerMemorySearch(memory, io);
+}

package/dist/cli/commands/core/memory-extract-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerMemoryExtractCommand(memory: Command, io: ProgramIO): void;

package/dist/cli/commands/core/memory-extract-command.js

@@ -0,0 +1,90 @@
+import { describeMemoryBlockDrops, executeProjectMemoryExtract, SENSITIVE_MEMORY_CHECKS, summarizeProjectMemoryExtractResult, UnsafeMemoryError } from '../../../services/memory/project-memory-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+import { refuseBothFlags } from './memory-command-shared.js';
+/**
+ * The remedy for a failed `memory extract`, chosen by the check that refused
+ * the write — the same `SENSITIVE_MEMORY_CHECKS` values the refusal message
+ * and envelope data are built from, so the message, the data and the advice
+ * cannot drift apart.
+ *
+ * WHY IT IS NOT ONE STATIC STRING. Every failure used to get "Check artifact
+ * paths and remove secrets before extracting memory" — including a refusal
+ * raised only because a memory TITLE contained a word like `authority`
+ * (slice C0). There was no secret anywhere in that memory, so the one thing
+ * the hint told the user to do was the one thing that could not help: it sent
+ * check that actually failed.
+ *
+ * `null` (a failure that is not a safety refusal — a path escape, a missing
+ * artifact) keeps the pre-C0 hint, which is about paths and secrets rather
+ * than about a check.
+ */
+function memoryExtractNextActions(refusal) {
+    if (refusal === null) {
+        return ['Check artifact paths and remove secrets before extracting memory'];
+    }
+    if (refusal.check === SENSITIVE_MEMORY_CHECKS.title) {
+        return [
+            'Retitle the memory so it is not named after a credential term, then re-run memory extract'
+        ];
+    }
+    if (refusal.check === SENSITIVE_MEMORY_CHECKS.content) {
+        // Name the rule, not just the family. `matchedTerm` is a closed id
+        // (`credential-assignment`, `bearer-value`, `pem-private-key`, …), so the
+        // reader can tell a credential in the text from a sentence that merely has
+        // the shape of one — which is the difference between removing a value and
+        // rewording prose.
+        return [
+            `Remove the credential value the "${refusal.matchedTerm}" pattern matched, then re-run memory extract`
+        ];
+    }
+    return ['Remove the credential value from the memory content, then re-run memory extract'];
+}
+function runExtract(io, options) {
+    const result = executeProjectMemoryExtract({
+        projectRoot: options.project,
+        artifactPaths: options.artifact,
+        apply: options.apply === true
+    });
+    // A block that was found but not extracted must not vanish silently: the
+    // parser's rejection reasons ride the envelope's existing `warnings`
+    // channel (JSON: `warnings[]`; human: `warning: …` on stderr). `data` is
+    // unchanged — this adds no field to the summary.
+    printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result), describeMemoryBlockDrops(result.droppedBlocks)), options.json);
+}
+function emitExtractFailure(io, options, error) {
+    const refusal = error instanceof UnsafeMemoryError ? error : null;
+    printResult(io, fail('memory.extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), 
+    // The check and the term are facts about the failure, so they ride
+    // the envelope's data — not just its prose. `fail()` redacts
+    // `message` (see `UnsafeMemoryError`), so the term would otherwise
+    // reach the reader as `[redacted]`; `data` is passed through.
+    refusal === null ? {} : { check: refusal.check, matchedTerm: refusal.matchedTerm }, memoryExtractNextActions(refusal)), options.json);
+    process.exitCode = 1;
+}
+export function registerMemoryExtractCommand(memory, io) {
+    addJsonOption(memory
+        .command('extract')
+        .description('Extract stable project memory from skill artifacts into project .peaks/memory')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
+        const refused = refuseBothFlags(io, {
+            command: 'memory.extract',
+            code: 'INVALID_MEMORY_EXTRACT_FLAGS',
+            nextActions: ['Run without --apply to preview writes, or pass --apply to write memories'],
+            json: options.json,
+            dryRun: options.dryRun,
+            apply: options.apply
+        });
+        if (refused)
+            return;
+        try {
+            runExtract(io, options);
+        }
+        catch (error) {
+            emitExtractFailure(io, options, error);
+        }
+    });
+}

package/dist/cli/commands/core/memory-sync-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerMemorySyncCommand(memory: Command, io: ProgramIO): void;

package/dist/cli/commands/core/memory-sync-command.js

@@ -0,0 +1,38 @@
+import { executeProjectMemoryBackup, summarizeProjectMemoryBackupResult } from '../../../services/memory/project-memory-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+import { refuseBothFlags } from './memory-command-shared.js';
+export function registerMemorySyncCommand(memory, io) {
+    addJsonOption(memory
+        .command('sync')
+        .description('Back up project .peaks/memory into the artifact workspace')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--workspace <path>', 'artifact workspace path')
+        .option('--dry-run', 'preview copies without changing files')
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
+        const refused = refuseBothFlags(io, {
+            command: 'memory.sync',
+            code: 'INVALID_MEMORY_SYNC_FLAGS',
+            nextActions: ['Run without --apply to preview copies, or pass --apply to back up memories'],
+            json: options.json,
+            dryRun: options.dryRun,
+            apply: options.apply
+        });
+        if (refused)
+            return;
+        try {
+            const result = executeProjectMemoryBackup({
+                projectRoot: options.project,
+                artifactWorkspacePath: options.workspace,
+                apply: options.apply === true
+            });
+            printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('memory.sync', 'MEMORY_SYNC_FAILED', getErrorMessage(error), {}, [
+                'Use an artifact workspace outside the project root'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/core/session-command.d.ts

@@ -1,3 +1,3 @@
 import type { Command } from 'commander';
-import { type ProgramIO } from '../../cli-helpers.js';
+import type { ProgramIO } from '../../cli-helpers.js';
 export declare function registerSessionCommand(program: Command, io: ProgramIO): void;