@ikon85/agent-workflow-kit 0.22.0 → 0.23.0

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle activation and one-time Memory Lifecycle policy seeds (Sections A4–A5) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,8 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile and Worktree Lifecycle hook wiring to adopt.
+- `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -165,6 +166,39 @@ The default setup entry is
 may remain the configured `setupEntry` for parity. The handoff advisory always
 reads that configured entry and never hardcodes a project script.
 
+### 2d. Section A5 — Optional Memory Lifecycle
+
+> Memory Lifecycle keeps project memories inside consumer-owned roots and makes
+> restore operations previewable, collision-safe, and reversible. The policy
+> templates become fully consumer-owned after their first seed.
+
+Read the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json` before offering anything. Missing or
+disabled configuration remains unchanged on an ordinary setup rerun. An
+existing enabled section is adopted byte-for-byte; preserve unknown profile
+keys, placement/retention settings, restore grants, and consumer-specific memory
+rows.
+If no section exists, explain the capability and offer an explicit opt-in. Only
+an affirmative consumer decision may run:
+
+```bash
+node scripts/memory-lifecycle/setup.mjs --enable
+```
+
+That command adds the minimal enabled section while preserving every existing
+top-level profile key, sets restore and pruning approval to `false` unless the
+consumer already recorded values, and seeds
+`meta_decision_layer_choice.md` plus `meta_memory_lifecycle.md` into the
+configured active root exactly once. Existing files are adopted and never
+overwritten. The profile's `templatesSeeded` marker transfers full ownership:
+later setup runs do not recreate a template the consumer edited, moved, or
+deleted.
+Choosing later, declining, or merely running `init`, `update`, or ordinary
+`setup-workflow` performs no Memory Lifecycle write and never changes
+activation, roots, retention, restore, or pruning grants. Template files have
+no kit-managed or `append-managed` region; a future bounded-region contract
+requires a separate decision.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -256,6 +290,11 @@ Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
 this profile. Apply the Worktree Lifecycle transition and hook ownership rules
 from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
 
+For Memory Lifecycle, use only the deterministic setup helper from Section A5.
+Do not copy templates with shell commands or edit the capability profile by
+hand. Report `seeded · adopted · skipped`; do not print memory contents or
+receipt contents.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
 | `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` | consumer-owned capability profile, including optional Worktree Lifecycle activation (Section A4) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle activation and one-time Memory Lifecycle policy seeds (Sections A4–A5) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,8 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — an existing Worktree Lifecycle choice/profile and hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile and Worktree Lifecycle hook wiring to adopt.
+- `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
 ### 2. Section A — Issue tracker
@@ -165,6 +166,39 @@ The default setup entry is
 may remain the configured `setupEntry` for parity. The handoff advisory always
 reads that configured entry and never hardcodes a project script.
 
+### 2d. Section A5 — Optional Memory Lifecycle
+
+> Memory Lifecycle keeps project memories inside consumer-owned roots and makes
+> restore operations previewable, collision-safe, and reversible. The policy
+> templates become fully consumer-owned after their first seed.
+
+Read the `memoryLifecycle` section of
+`docs/agents/workflow-capabilities.json` before offering anything. Missing or
+disabled configuration remains unchanged on an ordinary setup rerun. An
+existing enabled section is adopted byte-for-byte; preserve unknown profile
+keys, placement/retention settings, restore grants, and consumer-specific memory
+rows.
+If no section exists, explain the capability and offer an explicit opt-in. Only
+an affirmative consumer decision may run:
+
+```bash
+node scripts/memory-lifecycle/setup.mjs --enable
+```
+
+That command adds the minimal enabled section while preserving every existing
+top-level profile key, sets restore and pruning approval to `false` unless the
+consumer already recorded values, and seeds
+`meta_decision_layer_choice.md` plus `meta_memory_lifecycle.md` into the
+configured active root exactly once. Existing files are adopted and never
+overwritten. The profile's `templatesSeeded` marker transfers full ownership:
+later setup runs do not recreate a template the consumer edited, moved, or
+deleted.
+Choosing later, declining, or merely running `init`, `update`, or ordinary
+`setup-workflow` performs no Memory Lifecycle write and never changes
+activation, roots, retention, restore, or pruning grants. Template files have
+no kit-managed or `append-managed` region; a future bounded-region contract
+requires a separate decision.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -256,6 +290,11 @@ Lifecycle, Worktree Lifecycle, future sections, and unknown consumer keys share
 this profile. Apply the Worktree Lifecycle transition and hook ownership rules
 from [worktree-lifecycle.md](./worktree-lifecycle.md) transactionally.
 
+For Memory Lifecycle, use only the deterministic setup helper from Section A5.
+Do not copy templates with shell commands or edit the capability profile by
+hand. Report `seeded · adopted · skipped`; do not print memory contents or
+receipt contents.
+
 For the **`## Workflow`**, **`## Agent skills`**, and **`## Prod`** blocks, reconcile per section in **both** CLAUDE.md and AGENTS.md that exist:
 
 - If **both** files exist → write/update the block in **both** (keep them coherent — Codex is a first-class surface).

package/README.md

@@ -332,6 +332,15 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.23.0
+
+- added: `assets/memory-templates/meta_decision_layer_choice.md`
+- added: `assets/memory-templates/meta_memory_lifecycle.md`
+- added: `scripts/memory-lifecycle/setup.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `scripts/memory-lifecycle/index.mjs`
+
 ### 0.22.0
 
 - added: `.agents/skills/setup-workflow/worktree-lifecycle.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.22.0",
+  "kitVersion": "0.23.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -573,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
+      "sha256": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
       "mode": 420,
       "origin": "kit"
     },
@@ -1642,7 +1642,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "a1145034dbc334fb388be27dfb77cf1d93f3cefc6f760d5f4fa5d3ee98050dff",
+      "sha256": "247250aa38a81b542600db42cfe4d02eecc1236e8af47df1f4def627f4df0668",
       "mode": 420,
       "origin": "kit"
     },
@@ -1970,6 +1970,20 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "assets/memory-templates/meta_decision_layer_choice.md",
+      "kind": "template",
+      "sha256": "b22bd1d0e3daa31cbdbb9a3a81964d7a00d5275e69c92c9bd4ad3b4e40995b41",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "assets/memory-templates/meta_memory_lifecycle.md",
+      "kind": "template",
+      "sha256": "215e865d4e803ce0b2cd43e88d76501a61269dfa90aae5e6a474941a0b72b0ca",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "docs/agents/security-audit-runbook-template.md",
       "kind": "template",
@@ -2099,7 +2113,14 @@
     {
       "path": "scripts/memory-lifecycle/index.mjs",
       "kind": "script",
-      "sha256": "d83a71891e9c070179a00d6413b18d073061eef75e50919a7f28b8510f7ca20d",
+      "sha256": "871507e20133ccbb11f2a57f092bcb41aa1f6b7deaaa74df2418573316e6bd96",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/memory-lifecycle/setup.mjs",
+      "kind": "script",
+      "sha256": "c2c8885b806a830239ae54314c9dd0400399140870b6e62dc1e8b043dffcb78f",
       "mode": 420,
       "origin": "kit"
     },

package/assets/memory-templates/meta_decision_layer_choice.md

@@ -0,0 +1,25 @@
+# Durable Knowledge Placement
+
+Use this consumer-owned policy to decide where a learning belongs. Edit the
+categories and examples to match this repository's terminology.
+
+## Placement layers
+
+- Repository instructions: stable rules that should guide every relevant task.
+- Workflow skill: repeatable procedure with a named entry point and verification.
+- Domain documentation: product language, boundaries, and durable decisions.
+- Local memory: contextual knowledge that helps future sessions but is not yet a
+  repository-wide rule.
+
+## Decision check
+
+Before retaining a learning, record:
+
+1. who needs it;
+2. when it should be loaded;
+3. what evidence would make it stale;
+4. which tracked layer is the narrowest durable owner.
+
+Prefer a tracked repository layer when the knowledge changes how work should be
+performed. Keep personal preferences and user-profile information outside
+project-owned memories unless the user explicitly places them here.

package/assets/memory-templates/meta_memory_lifecycle.md

@@ -0,0 +1,25 @@
+# Memory Lifecycle Policy
+
+This file is consumer-owned after its first seed. Edit roots, retention classes,
+and review cadence to match the repository. Kit updates must never overwrite it.
+
+## Retention classes
+
+- Active: still relevant to current work and safe to load.
+- Archive candidate: useful history that should leave the active set.
+- Protected: user-profile, preference, or other content that must not be pruned
+  by an automated repository workflow.
+
+## Archive and restore
+
+- Archive only inside the configured consumer-owned archive root.
+- Preview every action before mutation.
+- Restore only with an explicit restore grant.
+- Preserve the archive and refuse destination collisions.
+- Record path verdicts and hashes in a content-free, collision-safe receipt.
+
+## Pruning
+
+Pruning is never implied by setup, update, archive, or restore. It requires a
+separate preview and explicit user approval. A failed or interrupted operation
+must leave the last safe active and archived state recoverable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.22.0",
+  "version": "0.23.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": {
@@ -21,6 +21,7 @@
     ".claude/",
     "!.claude/logs/",
     ".agents/",
+    "assets/",
     "scripts/",
     "docs/",
     "src/",

package/scripts/memory-lifecycle/index.mjs

@@ -10,6 +10,8 @@ import { createHash, randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, normalize, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+export { setupMemoryLifecycle } from './setup.mjs';
+
 async function exists(path) {
   try {
     return await lstat(path);

package/scripts/memory-lifecycle/setup.mjs

@@ -0,0 +1,167 @@
+import {
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+const PROFILE_PATH = 'docs/agents/workflow-capabilities.json';
+const TEMPLATE_NAMES = [
+  'meta_decision_layer_choice.md',
+  'meta_memory_lifecycle.md',
+];
+
+function contained(root, path) {
+  if (isAbsolute(path)) return null;
+  const normalized = normalize(path);
+  if (normalized === '..' || normalized.startsWith(`..${sep}`)) return null;
+  const absolute = resolve(root, normalized);
+  return relative(resolve(root), absolute).split(sep)[0] === '..' ? null : absolute;
+}
+
+async function lstatIfPresent(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function hasSymlink(root, path) {
+  let current = resolve(root);
+  const segments = relative(current, path).split(sep).filter(Boolean);
+  for (const segment of segments) {
+    current = resolve(current, segment);
+    if ((await lstatIfPresent(current))?.isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  const staged = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(staged, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    await rename(staged, path);
+  } finally {
+    await rm(staged, { force: true });
+  }
+}
+
+function defaultCapability() {
+  return {
+    enabled: true,
+    activeRoot: '.memory/active',
+    archiveRoot: '.memory/archive',
+    receiptRoot: '.memory/receipts',
+    approvals: { restore: false, prune: false },
+    memories: TEMPLATE_NAMES.map((path) => ({ path, enabled: true })),
+    templatesSeeded: true,
+  };
+}
+
+export async function setupMemoryLifecycle({
+  projectRoot = process.cwd(),
+  templateRoot = join(projectRoot, 'assets', 'memory-templates'),
+  decision,
+} = {}) {
+  const profilePath = resolve(projectRoot, PROFILE_PATH);
+  if (await hasSymlink(projectRoot, profilePath)) {
+    throw new Error('memoryLifecycle profile path contains a symlink');
+  }
+  const profile = await readJson(profilePath);
+  const existing = profile?.memoryLifecycle;
+
+  if (decision !== 'enable') {
+    return {
+      state: existing?.enabled ? 'enabled' : 'disabled',
+      seeded: [],
+      adopted: [],
+    };
+  }
+
+  const capability = {
+    ...defaultCapability(),
+    ...existing,
+    enabled: true,
+    approvals: {
+      restore: false,
+      prune: false,
+      ...existing?.approvals,
+    },
+    templatesSeeded: true,
+  };
+  const activeRoot = contained(projectRoot, capability.activeRoot);
+  if (!activeRoot) throw new Error('memoryLifecycle.activeRoot must stay inside the project');
+  if (await hasSymlink(projectRoot, activeRoot)) {
+    throw new Error('memoryLifecycle.activeRoot contains a symlink');
+  }
+
+  const shouldSeed = existing?.templatesSeeded !== true;
+  const sources = shouldSeed
+    ? await Promise.all(TEMPLATE_NAMES.map(async (name) => ({
+        name,
+        content: await readFile(join(templateRoot, name)),
+      })))
+    : [];
+  const seeded = [];
+  const adopted = [];
+  const destinations = sources.map(({ name, ...source }) => ({
+    ...source,
+    name,
+    destination: contained(activeRoot, name),
+  }));
+  for (const { destination } of destinations) {
+    if (await hasSymlink(activeRoot, destination)) {
+      throw new Error('memory policy destination contains a symlink');
+    }
+  }
+  for (const { content, destination } of destinations) {
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+      await writeFile(destination, content, { flag: 'wx' });
+      seeded.push(relative(projectRoot, destination));
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      adopted.push(relative(projectRoot, destination));
+    }
+  }
+
+  await writeJsonAtomic(profilePath, {
+    schemaVersion: 1,
+    ...profile,
+    memoryLifecycle: capability,
+  });
+  return { state: 'enabled', seeded, adopted };
+}
+
+export const MEMORY_POLICY_TEMPLATES = Object.freeze([...TEMPLATE_NAMES]);
+
+async function main(argv) {
+  const result = await setupMemoryLifecycle({
+    decision: argv.includes('--enable') ? 'enable' : undefined,
+  });
+  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/src/lib/bundle.mjs

@@ -65,9 +65,11 @@ 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.
+  // Consumer-owned memory planning, one-time policy seeding, and recovery.
   { path: 'scripts/memory-lifecycle/index.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/memory-lifecycle/setup.mjs', kind: 'script', mode: 0o644 },
+  { path: 'assets/memory-templates/meta_decision_layer_choice.md', kind: 'template', mode: 0o644 },
+  { path: 'assets/memory-templates/meta_memory_lifecycle.md', kind: 'template', 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.