@ikon85/agent-workflow-kit 0.18.0 → 0.19.0

package/.agents/skills/memory-lifecycle/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: memory-lifecycle
+description: "Preview and apply a consumer-owned memory lifecycle without crossing configured roots or overwriting active, archived, or recovery evidence. Use when a user wants to restore archived memories, inspect memory placement, or run an approved memory recovery."
+---
+
+# Memory Lifecycle
+
+Coordinate the current repository's memory placement and recovery through the
+deterministic helper at `scripts/memory-lifecycle/index.mjs`. The helper owns
+path validation, dry-run verdicts, exclusive restore writes, hashing, and
+receipts. Keep this skill thin: do not reimplement those rules with shell file
+operations.
+
+## Boundaries
+
+- Work only below the consumer-owned roots in
+  `docs/agents/workflow-capabilities.json`.
+- Never scan another repository or a user-global memory root that the current
+  consumer profile does not explicitly own.
+- Treat active memories, archives, policy templates, and restore receipts as
+  consumer-owned. Never overwrite them.
+- `init`, `update`, and an ordinary `setup-workflow` rerun must not enable this
+  capability or change placement, retention, restore, or pruning grants.
+- Destructive pruning is outside the helper. It requires a separate preview and
+  explicit user approval; do not infer that approval from restore permission.
+
+## Consumer profile
+
+Adopt the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json`. Missing or disabled configuration is
+a valid no-write `disabled` result.
+
+```json
+{
+  "memoryLifecycle": {
+    "enabled": true,
+    "activeRoot": ".memory/active",
+    "archiveRoot": ".memory/archive",
+    "receiptRoot": ".memory/receipts",
+    "approvals": { "restore": false, "prune": false },
+    "memories": [
+      { "path": "decisions/example.md", "enabled": true }
+    ]
+  }
+}
+```
+
+Preserve unknown profile keys. Every configured root and candidate path must be
+repository-relative. Absolute paths, parent escapes, symlink traversal,
+different-content collisions, and missing restore approval are refused.
+
+## Workflow
+
+1. **Preview.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs
+   ```
+
+   This is the default no-write mode. Count the candidate paths and confirm each
+   appears exactly once as `create`, `restore`, `preserve`, `skip`, or `refuse`.
+2. **Review refusals.** Explain every refusal. Do not weaken root, symlink,
+   collision, or approval checks to make the run green.
+3. **Confirm recovery.** Before applying, require the consumer profile's
+   `approvals.restore` to already record the explicit restore grant. A chat
+   instruction does not silently rewrite the tracked policy.
+4. **Apply.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs --apply
+   ```
+
+   The helper restores with exclusive-create semantics and keeps the archive.
+   A concurrent destination collision becomes `refused`, never an overwrite.
+5. **Read back.** Verify restored files by path and hash, not by printing memory
+   contents. Confirm the receipt has schema/source versions plus
+   `restored`/`skipped`/`refused` path verdicts and contains no memory content.
+6. **Rerun.** Run the preview again. An identical restored file is preserved;
+   the rerun writes no duplicate receipt.
+
+Use `--profile <repository-relative-path>` only when the repository documents a
+different consumer-owned profile location.
+
+## Final report
+
+Report:
+
+- dry-run counts for all five action classes;
+- applied `restored`/`skipped`/`refused` counts;
+- receipt path and source versions, without memory contents;
+- archive-preservation and rerun/no-write result;
+- any pruning request left pending explicit approval.

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -18,6 +18,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
+- **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

package/.claude/skills/memory-lifecycle/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: memory-lifecycle
+description: "Preview and apply a consumer-owned memory lifecycle without crossing configured roots or overwriting active, archived, or recovery evidence. Use when a user wants to restore archived memories, inspect memory placement, or run an approved memory recovery."
+---
+
+# Memory Lifecycle
+
+Coordinate the current repository's memory placement and recovery through the
+deterministic helper at `scripts/memory-lifecycle/index.mjs`. The helper owns
+path validation, dry-run verdicts, exclusive restore writes, hashing, and
+receipts. Keep this skill thin: do not reimplement those rules with shell file
+operations.
+
+## Boundaries
+
+- Work only below the consumer-owned roots in
+  `docs/agents/workflow-capabilities.json`.
+- Never scan another repository or a user-global memory root that the current
+  consumer profile does not explicitly own.
+- Treat active memories, archives, policy templates, and restore receipts as
+  consumer-owned. Never overwrite them.
+- `init`, `update`, and an ordinary `setup-workflow` rerun must not enable this
+  capability or change placement, retention, restore, or pruning grants.
+- Destructive pruning is outside the helper. It requires a separate preview and
+  explicit user approval; do not infer that approval from restore permission.
+
+## Consumer profile
+
+Adopt the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json`. Missing or disabled configuration is
+a valid no-write `disabled` result.
+
+```json
+{
+  "memoryLifecycle": {
+    "enabled": true,
+    "activeRoot": ".memory/active",
+    "archiveRoot": ".memory/archive",
+    "receiptRoot": ".memory/receipts",
+    "approvals": { "restore": false, "prune": false },
+    "memories": [
+      { "path": "decisions/example.md", "enabled": true }
+    ]
+  }
+}
+```
+
+Preserve unknown profile keys. Every configured root and candidate path must be
+repository-relative. Absolute paths, parent escapes, symlink traversal,
+different-content collisions, and missing restore approval are refused.
+
+## Workflow
+
+1. **Preview.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs
+   ```
+
+   This is the default no-write mode. Count the candidate paths and confirm each
+   appears exactly once as `create`, `restore`, `preserve`, `skip`, or `refuse`.
+2. **Review refusals.** Explain every refusal. Do not weaken root, symlink,
+   collision, or approval checks to make the run green.
+3. **Confirm recovery.** Before applying, require the consumer profile's
+   `approvals.restore` to already record the explicit restore grant. A chat
+   instruction does not silently rewrite the tracked policy.
+4. **Apply.** Run:
+
+   ```sh
+   node scripts/memory-lifecycle/index.mjs --apply
+   ```
+
+   The helper restores with exclusive-create semantics and keeps the archive.
+   A concurrent destination collision becomes `refused`, never an overwrite.
+5. **Read back.** Verify restored files by path and hash, not by printing memory
+   contents. Confirm the receipt has schema/source versions plus
+   `restored`/`skipped`/`refused` path verdicts and contains no memory content.
+6. **Rerun.** Run the preview again. An identical restored file is preserved;
+   the rerun writes no duplicate receipt.
+
+Use `--profile <repository-relative-path>` only when the repository documents a
+different consumer-owned profile location.
+
+## Final report
+
+Report:
+
+- dry-run counts for all five action classes;
+- applied `restored`/`skipped`/`refused` counts;
+- receipt path and source versions, without memory contents;
+- archive-preservation and rerun/no-write result;
+- any pruning request left pending explicit approval.

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -18,6 +18,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Multi-session build from a PRD or issue:** use `implement` to drive `tdd` end-to-end, one red-green slice at a time.
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Build or refresh a project-local census:** use `census-update` to scan facts, resolve ambiguous decisions one at a time, and transactionally activate a counted census.
+- **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.

package/.claude/skills/skill-manifest.json

@@ -404,6 +404,16 @@
         "codex"
       ],
       "provenance": "own"
+    },
+    "memory-lifecycle": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
     }
   }
 }

package/PROVENANCE.md

@@ -33,7 +33,7 @@ carries Chase's `THIRD-PARTY-NOTICES.md`.
 
 retro, wrapup, spec-self-critique, board-to-waves, verify-spike, decision-gate,
 codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave,
-census-update — covered by the root LICENSE.
+census-update, memory-lifecycle — covered by the root LICENSE.
 `setup-pre-commit` was rewritten from Matt Pocock's husky-based skill to a
 zero-dep native git `core.hooksPath` scaffold; nothing of the original
 mechanic remains (courtesy attribution).

package/README.md

@@ -332,6 +332,14 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.19.0
+
+- added: `.agents/skills/memory-lifecycle/SKILL.md`
+- added: `.claude/skills/memory-lifecycle/SKILL.md`
+- added: `scripts/memory-lifecycle/index.mjs`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
 ### 0.18.0
 
 - added: `scripts/worktree-lifecycle/capabilities.json`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.18.0",
+  "kitVersion": "0.19.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -352,6 +352,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/memory-lifecycle/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "memory-lifecycle",
+      "surface": "codex",
+      "sha256": "f4cd4a744044b59fd4ce6b7348e30f437ca4200f5f5bbae6e6aebdc30d6b3f35",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/orchestrate-wave/references/builder-contract.md",
       "kind": "skill",
@@ -600,7 +609,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
+      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
       "mode": 420,
       "origin": "kit"
     },
@@ -1334,6 +1343,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/memory-lifecycle/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "memory-lifecycle",
+      "surface": "claude",
+      "sha256": "f4cd4a744044b59fd4ce6b7348e30f437ca4200f5f5bbae6e6aebdc30d6b3f35",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/orchestrate-wave/references/builder-contract.md",
       "kind": "skill",
@@ -1600,7 +1618,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "b83fa87dc0226f21e01d31c91840b78d1ccad0a92e646de203fc3c003e9098f3",
+      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
       "mode": 420,
       "origin": "kit"
     },
@@ -2000,6 +2018,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "scripts/memory-lifecycle/index.mjs",
+      "kind": "script",
+      "sha256": "d83a71891e9c070179a00d6413b18d073061eef75e50919a7f28b8510f7ca20d",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/node_kind.py",
       "kind": "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/memory-lifecycle/index.mjs

@@ -0,0 +1,247 @@
+import {
+  constants,
+  copyFile,
+  lstat,
+  mkdir,
+  readFile,
+  writeFile,
+} from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+async function exists(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function resolveCandidate(root, candidate) {
+  if (isAbsolute(candidate)) return null;
+  const normalized = normalize(candidate);
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) return null;
+  const absolute = resolve(root, normalized);
+  const boundary = `${resolve(root)}${sep}`;
+  return absolute.startsWith(boundary) ? absolute : null;
+}
+
+async function pathHasSymlink(root, candidatePath) {
+  const rootStat = await exists(root);
+  if (rootStat?.isSymbolicLink()) return true;
+
+  const relativePath = relative(resolve(root), candidatePath);
+  let current = resolve(root);
+  for (const segment of relativePath.split(sep).filter(Boolean)) {
+    current = resolve(current, segment);
+    const stat = await exists(current);
+    if (stat?.isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function sha256(path) {
+  return createHash('sha256').update(await readFile(path)).digest('hex');
+}
+
+export async function planMemoryLifecycle({
+  activeRoot,
+  archiveRoot,
+  candidates,
+  approved = false,
+}) {
+  const actions = [];
+  const seen = new Set();
+
+  for (const candidateInput of candidates) {
+    const candidate = typeof candidateInput === 'string'
+      ? { path: candidateInput, enabled: true }
+      : { enabled: true, ...candidateInput };
+    if (seen.has(candidate.path)) continue;
+    seen.add(candidate.path);
+
+    if (!candidate.enabled) {
+      actions.push({
+        path: candidate.path,
+        action: 'skip',
+        reason: 'candidate is disabled by consumer policy',
+      });
+      continue;
+    }
+
+    const activePath = resolveCandidate(activeRoot, candidate.path);
+    const archivePath = resolveCandidate(archiveRoot, candidate.path);
+    let action = 'refuse';
+    let reason = 'outside configured roots';
+
+    if (
+      activePath
+      && archivePath
+      && !(await pathHasSymlink(activeRoot, activePath))
+      && !(await pathHasSymlink(archiveRoot, archivePath))
+    ) {
+      const active = await exists(activePath);
+      const archived = await exists(archivePath);
+      if (active && archived) {
+        const identical = active.isFile() && archived.isFile()
+          && (await sha256(activePath)) === (await sha256(archivePath));
+        action = identical ? 'preserve' : 'refuse';
+        reason = identical
+          ? 'active and archived memory already match'
+          : 'active and archived memory collide';
+      } else if (active) {
+        action = 'preserve';
+        reason = 'active memory already exists';
+      } else if (archived && approved) {
+        action = 'restore';
+        reason = 'approved archived memory is available';
+      } else if (archived) {
+        action = 'refuse';
+        reason = 'restore approval is required';
+      } else {
+        action = 'create';
+        reason = 'memory does not exist';
+      }
+    } else if (activePath && archivePath) {
+      reason = `symlink escape below ${dirname(activePath)}`;
+    }
+
+    actions.push({ path: candidate.path, action, reason });
+  }
+
+  return { dryRun: true, actions };
+}
+
+async function writeReceipt(receiptRoot, receipt) {
+  await mkdir(receiptRoot, { recursive: true });
+  const name = `memory-restore-${Date.now()}-${randomUUID()}.json`;
+  const path = resolve(receiptRoot, name);
+  await writeFile(path, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+  return path;
+}
+
+export async function executeMemoryLifecycle(options) {
+  const plan = await planMemoryLifecycle(options);
+  const verdicts = [];
+
+  for (const item of plan.actions) {
+    if (item.action !== 'restore') {
+      verdicts.push({
+        path: item.path,
+        verdict: item.action === 'refuse' ? 'refused' : 'skipped',
+        reason: item.reason,
+      });
+      continue;
+    }
+
+    const activePath = resolveCandidate(options.activeRoot, item.path);
+    const archivePath = resolveCandidate(options.archiveRoot, item.path);
+    const hash = await sha256(archivePath);
+    await mkdir(dirname(activePath), { recursive: true });
+    try {
+      await copyFile(archivePath, activePath, constants.COPYFILE_EXCL);
+      verdicts.push({ path: item.path, verdict: 'restored', sha256: hash });
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      verdicts.push({
+        path: item.path,
+        verdict: 'refused',
+        reason: 'active memory appeared before restore',
+        sha256: hash,
+      });
+    }
+  }
+
+  const restored = verdicts.some(({ verdict }) => verdict === 'restored');
+  const receiptPath = restored
+    ? await writeReceipt(options.receiptRoot, {
+        schemaVersion: 1,
+        createdAt: new Date().toISOString(),
+        source: options.source,
+        verdicts,
+      })
+    : null;
+
+  return { verdicts, receiptPath };
+}
+
+async function readJsonIfPresent(path) {
+  try {
+    const raw = await readFile(path, 'utf8');
+    return { raw, value: JSON.parse(raw) };
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function runMemoryLifecycle({
+  projectRoot = process.cwd(),
+  profilePath = 'docs/agents/workflow-capabilities.json',
+  apply = false,
+} = {}) {
+  const absoluteProfile = resolveCandidate(projectRoot, profilePath);
+  if (!absoluteProfile || await pathHasSymlink(projectRoot, absoluteProfile)) {
+    return {
+      state: 'refused',
+      dryRun: !apply,
+      actions: [{ path: profilePath, action: 'refuse', reason: 'unsafe profile path' }],
+    };
+  }
+
+  const profileDocument = await readJsonIfPresent(absoluteProfile);
+  const capability = profileDocument?.value?.memoryLifecycle;
+  if (!capability?.enabled) {
+    return { state: 'disabled', dryRun: true, actions: [] };
+  }
+
+  const activeRoot = resolveCandidate(projectRoot, capability.activeRoot);
+  const archiveRoot = resolveCandidate(projectRoot, capability.archiveRoot);
+  const receiptRoot = resolveCandidate(projectRoot, capability.receiptRoot);
+  if (!activeRoot || !archiveRoot || !receiptRoot) {
+    return {
+      state: 'refused',
+      dryRun: !apply,
+      actions: [{ path: 'memoryLifecycle', action: 'refuse', reason: 'configured root escapes project' }],
+    };
+  }
+
+  const consumerManifest = await readJsonIfPresent(
+    resolve(projectRoot, 'agent-workflow-kit.json'),
+  );
+  const source = {
+    kitVersion: consumerManifest?.value?.kitVersion ?? 'unknown',
+    bundleVersion: consumerManifest
+      ? `sha256:${createHash('sha256').update(consumerManifest.raw).digest('hex')}`
+      : 'unknown',
+  };
+  const options = {
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: capability.memories ?? [],
+    approved: capability.approvals?.restore === true,
+    source,
+  };
+  if (apply) {
+    return { state: 'applied', dryRun: false, ...await executeMemoryLifecycle(options) };
+  }
+  return { state: 'planned', ...await planMemoryLifecycle(options) };
+}
+
+async function main(argv) {
+  const apply = argv.includes('--apply');
+  const profileFlag = argv.indexOf('--profile');
+  const profilePath = profileFlag >= 0 ? argv[profileFlag + 1] : undefined;
+  const result = await runMemoryLifecycle({ apply, profilePath });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  main(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/memory-lifecycle/memory-lifecycle.test.mjs

@@ -0,0 +1,170 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, readdir, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  executeMemoryLifecycle,
+  planMemoryLifecycle,
+  runMemoryLifecycle,
+} from './index.mjs';
+
+test('dry-run classifies each candidate once without writing', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'returning.md'), 'archived memory\n');
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: ['new.md', 'returning.md'],
+    approved: true,
+  });
+
+  assert.deepEqual(plan.actions.map(({ path, action }) => [path, action]), [
+    ['new.md', 'create'],
+    ['returning.md', 'restore'],
+  ]);
+  await assert.rejects(readFile(join(activeRoot, 'new.md'), 'utf8'), { code: 'ENOENT' });
+  await assert.rejects(readFile(join(activeRoot, 'returning.md'), 'utf8'), { code: 'ENOENT' });
+});
+
+test('dry-run refuses unsafe roots, collisions, outside paths, and unapproved restores', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  await mkdir(activeRoot, { recursive: true });
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(activeRoot, 'collision.md'), 'active\n');
+  await writeFile(join(archiveRoot, 'collision.md'), 'different archive\n');
+  await writeFile(join(archiveRoot, 'approval.md'), 'archived\n');
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: ['../foreign.md', 'collision.md', 'approval.md'],
+  });
+  assert.deepEqual(plan.actions.map(({ action }) => action), ['refuse', 'refuse', 'refuse']);
+
+  const linkedActive = join(root, 'linked-active');
+  await symlink(activeRoot, linkedActive, 'dir');
+  const symlinkPlan = await planMemoryLifecycle({
+    activeRoot: linkedActive,
+    archiveRoot,
+    candidates: ['safe.md'],
+    approved: true,
+  });
+  assert.equal(symlinkPlan.actions[0].action, 'refuse');
+});
+
+test('execute restores without removing the archive and writes a content-free receipt', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  const receiptRoot = join(root, 'receipts');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'returning.md'), 'private memory contents\n');
+
+  const result = await executeMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: ['returning.md'],
+    approved: true,
+    source: { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' },
+  });
+
+  assert.equal(await readFile(join(activeRoot, 'returning.md'), 'utf8'), 'private memory contents\n');
+  assert.equal(await readFile(join(archiveRoot, 'returning.md'), 'utf8'), 'private memory contents\n');
+  assert.equal(result.verdicts[0].verdict, 'restored');
+  const [receiptName] = await readdir(receiptRoot);
+  const receiptText = await readFile(join(receiptRoot, receiptName), 'utf8');
+  const receipt = JSON.parse(receiptText);
+  assert.equal(receipt.schemaVersion, 1);
+  assert.deepEqual(receipt.source, { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' });
+  assert.match(receipt.verdicts[0].sha256, /^[a-f0-9]{64}$/);
+  assert.ok(!receiptText.includes('private memory contents'));
+});
+
+test('rerun preserves restored memory and never overwrites or duplicates its receipt', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const activeRoot = join(root, 'active');
+  const archiveRoot = join(root, 'archive');
+  const receiptRoot = join(root, 'receipts');
+  await mkdir(archiveRoot, { recursive: true });
+  await writeFile(join(archiveRoot, 'stable.md'), 'stable\n');
+  const options = {
+    activeRoot,
+    archiveRoot,
+    receiptRoot,
+    candidates: ['stable.md'],
+    approved: true,
+    source: { kitVersion: '1.2.3', bundleVersion: 'bundle-abc' },
+  };
+
+  const first = await executeMemoryLifecycle(options);
+  const receiptBefore = await readFile(first.receiptPath, 'utf8');
+  const second = await executeMemoryLifecycle(options);
+
+  assert.equal(second.verdicts[0].verdict, 'skipped');
+  assert.equal(second.receiptPath, null);
+  assert.deepEqual(await readdir(receiptRoot), [first.receiptPath.split('/').at(-1)]);
+  assert.equal(await readFile(first.receiptPath, 'utf8'), receiptBefore);
+});
+
+test('disabled and duplicate candidates produce one explicit skip verdict per path', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const plan = await planMemoryLifecycle({
+    activeRoot: join(root, 'active'),
+    archiveRoot: join(root, 'archive'),
+    candidates: [
+      { path: 'later.md', enabled: false },
+      { path: 'later.md', enabled: false },
+    ],
+    approved: true,
+  });
+
+  assert.deepEqual(plan.actions, [{
+    path: 'later.md',
+    action: 'skip',
+    reason: 'candidate is disabled by consumer policy',
+  }]);
+});
+
+test('missing or disabled consumer profile is a no-write disabled result', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+
+  assert.deepEqual(await runMemoryLifecycle({ projectRoot: root }), {
+    state: 'disabled',
+    dryRun: true,
+    actions: [],
+  });
+  await assert.rejects(readFile(join(root, '.memory'), 'utf8'), { code: 'ENOENT' });
+});
+
+test('frozen Testreporter parity profile classifies all three native memory rows', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'memory-lifecycle-'));
+  const fixture = JSON.parse(await readFile(new URL(
+    '../../test/fixtures/memory-lifecycle/testreporter-parity.json',
+    import.meta.url,
+  )));
+  const activeRoot = join(root, fixture.activeRoot);
+  const archiveRoot = join(root, fixture.archiveRoot);
+  await mkdir(archiveRoot, { recursive: true });
+  for (const { path } of fixture.memories) {
+    await writeFile(join(archiveRoot, path), `${path}\n`);
+  }
+
+  const plan = await planMemoryLifecycle({
+    activeRoot,
+    archiveRoot,
+    candidates: fixture.memories,
+    approved: fixture.approvals.restore,
+  });
+
+  assert.equal(plan.actions.length, 3);
+  assert.deepEqual(plan.actions.map(({ action }) => action), ['restore', 'restore', 'restore']);
+});

package/src/lib/bundle.mjs

@@ -62,6 +62,9 @@ export const HELPER_FILES = [
   { path: 'scripts/census/delta.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/state.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/census/transaction.mjs', kind: 'script', mode: 0o644 },
+  // Consumer-owned memory planning and recovery. The module is both the stable
+  // skill API and the no-write-by-default CLI.
+  { path: 'scripts/memory-lifecycle/index.mjs', kind: 'script', mode: 0o644 },
   // Profile-driven Worktree Lifecycle foundation. The setup adapter imports
   // core.py, while capabilities.json keeps the historical 8/8 denominator
   // explicit until the remaining hook and cleanup adapters are activated.