contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/workflow.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * `/workflow` — thin macro that chains `/roadmap` → `/new-adr` → `/pipeline`
+ * → `/ship` into a single explicit narrative (ticket 041, Compozy follow-
+ * through). The script does NOT invoke the other commands — Claude does that
+ * by reading the slash-command briefing. This script owns the **breadcrumb
+ * file** so the user can `/workflow status` or `/workflow resume <slug>`
+ * across sessions / machines.
+ *
+ * Subcommands:
+ *   workflow.mjs new <slug>          — create breadcrumb, set first phase pending
+ *   workflow.mjs advance <slug> [ref] — mark current phase done, advance pointer
+ *   workflow.mjs status              — list every workflow + its current phase
+ *   workflow.mjs status <slug>       — show one workflow's breadcrumb
+ *   workflow.mjs status --json       — machine-readable
+ *
+ * Breadcrumb path: `contextkit/memory/workflows/<slug>.md`. One file per slug;
+ * the YAML-ish frontmatter is parsed by hand (no yaml dep). The body carries
+ * one bullet per phase transition for human inspection.
+ *
+ * Zero-dep, pure ESM. Slug is kebab-case `[a-z0-9-]`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const WF_DIR = resolve(pathsFor(ROOT).memory, 'workflows');
+const PHASES = ['roadmap', 'adr', 'tickets', 'ship'];
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,60}$/;
+
+function ensureDir() { mkdirSync(WF_DIR, { recursive: true }); }
+
+function fileFor(slug) { return resolve(WF_DIR, `${slug}.md`); }
+
+/**
+ * Parses the lightweight YAML-ish frontmatter. Recognises three top-level keys
+ * (slug, started, currentPhase) + a `phases:` list with one entry per phase.
+ * Body content after `---` is preserved on update so user notes survive.
+ */
+function parse(text) {
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!fmMatch) return null;
+  const fm = fmMatch[1];
+  const body = fmMatch[2] ?? '';
+  const slug = (fm.match(/^slug:\s*(.+)$/m) || [])[1]?.trim();
+  const started = (fm.match(/^started:\s*(.+)$/m) || [])[1]?.trim();
+  const currentPhase = (fm.match(/^currentPhase:\s*(.+)$/m) || [])[1]?.trim();
+  const phases = {};
+  for (const p of PHASES) {
+    const status = (fm.match(new RegExp(`^${p}:\\s*(\\S+)(?:\\s+(.+))?$`, 'm')) || [])[1]?.trim() || 'pending';
+    const ref = (fm.match(new RegExp(`^${p}-ref:\\s*(.+)$`, 'm')) || [])[1]?.trim() || '';
+    phases[p] = { status, ref };
+  }
+  return { slug, started, currentPhase, phases, body };
+}
+
+function render(wf) {
+  const lines = ['---', `slug: ${wf.slug}`, `started: ${wf.started}`, `currentPhase: ${wf.currentPhase}`];
+  for (const p of PHASES) { lines.push(`${p}: ${wf.phases[p].status}`); if (wf.phases[p].ref) lines.push(`${p}-ref: ${wf.phases[p].ref}`); }
+  lines.push('---');
+  lines.push('');
+  lines.push(`# Workflow — ${wf.slug}`);
+  lines.push('');
+  // Strip a previous identical heading from the preserved body so re-rendering doesn't dup.
+  const cleanBody = wf.body.replace(/^\s*#\s*Workflow\s+—\s+\S+\s*\n+/m, '').trim();
+  lines.push(cleanBody || '_(history will accumulate here as phases advance)_');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function appendHistory(wf, line) { wf.body = (wf.body.trim() ? wf.body.trim() + '\n' : '') + `- ${line}`; return wf; }
+
+function cmdNew(slug) {
+  if (!SLUG_RE.test(slug)) { console.error(`✗ slug must match ${SLUG_RE} (got "${slug}")`); process.exit(1); }
+  ensureDir();
+  if (existsSync(fileFor(slug))) { console.error(`✗ workflow "${slug}" already exists at ${fileFor(slug)}`); process.exit(1); }
+  const started = new Date().toISOString();
+  const wf = { slug, started, currentPhase: 'roadmap', phases: Object.fromEntries(PHASES.map((p) => [p, { status: 'pending', ref: '' }])), body: '' };
+  appendHistory(wf, `${started.slice(0, 10)} · created · next phase: roadmap`);
+  writeFileSync(fileFor(slug), render(wf));
+  console.log(`▶  Workflow "${slug}" created. Next phase: /roadmap (then \`workflow.mjs advance ${slug} <ref>\`).`);
+}
+
+function cmdAdvance(slug, ref) {
+  if (!existsSync(fileFor(slug))) { console.error(`✗ workflow "${slug}" not found.`); process.exit(1); }
+  const wf = parse(readFileSync(fileFor(slug), 'utf-8'));
+  if (!wf) { console.error(`✗ workflow "${slug}" has a malformed breadcrumb.`); process.exit(1); }
+  const idx = PHASES.indexOf(wf.currentPhase);
+  if (idx < 0) { console.error(`✗ workflow "${slug}" has an unknown currentPhase: ${wf.currentPhase}`); process.exit(1); }
+  wf.phases[wf.currentPhase].status = 'done';
+  if (ref) wf.phases[wf.currentPhase].ref = ref;
+  const nextPhase = PHASES[idx + 1];
+  const stamp = new Date().toISOString().slice(0, 10);
+  if (!nextPhase) {
+    wf.currentPhase = 'done';
+    appendHistory(wf, `${stamp} · ${PHASES[idx]} done${ref ? ` (ref: ${ref})` : ''} · workflow complete`);
+    writeFileSync(fileFor(slug), render(wf));
+    console.log(`✅  Workflow "${slug}" complete — all 4 phases done.`);
+    return;
+  }
+  wf.currentPhase = nextPhase;
+  appendHistory(wf, `${stamp} · ${PHASES[idx]} done${ref ? ` (ref: ${ref})` : ''} · next phase: ${nextPhase}`);
+  writeFileSync(fileFor(slug), render(wf));
+  console.log(`▶  Workflow "${slug}" advanced — ${PHASES[idx]} → ${nextPhase}.`);
+}
+
+function listAll() {
+  ensureDir();
+  return readdirSync(WF_DIR).filter((f) => f.endsWith('.md') && f !== '.gitkeep')
+    .map((f) => parse(readFileSync(resolve(WF_DIR, f), 'utf-8'))).filter(Boolean)
+    .sort((a, b) => b.started.localeCompare(a.started));
+}
+
+function cmdStatus(target, asJson) {
+  const all = listAll();
+  const filtered = target && target !== '--json' ? all.filter((w) => w.slug === target) : all;
+  if (asJson) { console.log(JSON.stringify(filtered, null, 2)); return; }
+  if (filtered.length === 0) { console.log(target ? `  Workflow "${target}" not found.` : '  No workflows yet. Start one with `workflow.mjs new <slug>`.'); return; }
+  for (const w of filtered) {
+    console.log(`\n  ${w.slug} (started ${w.started.slice(0, 10)}) — current: ${w.currentPhase}`);
+    for (const p of PHASES) {
+      const s = w.phases[p];
+      const marker = s.status === 'done' ? '✓' : s.status === 'in-progress' ? '◐' : '·';
+      const refNote = s.ref ? ` → ${s.ref}` : '';
+      console.log(`    ${marker} ${p.padEnd(8)} ${s.status}${refNote}`);
+    }
+  }
+  console.log('');
+}
+
+const cmd = process.argv[2];
+if (cmd === 'new') cmdNew(process.argv[3]);
+else if (cmd === 'advance') cmdAdvance(process.argv[3], process.argv[4]);
+else if (cmd === 'status') cmdStatus(process.argv[3], process.argv.includes('--json'));
+else { console.error('Usage: workflow.mjs <new <slug> | advance <slug> [ref] | status [<slug> | --json]>'); process.exit(1); }

package/templates/contextkit/tools/scripts/workspace-sync.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * Aggregates active session claims into `contextkit/memory/WORKSPACE.md`.
+ *
+ * Each active session writes its own JSON under `.claude/.workspace/<sid>.json`
+ * (gitignored local state). This scans them, drops stale entries (no heartbeat
+ * for > 1h), and rebuilds the committed markdown summary.
+ *
+ * Since [ADR-0015 §B](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md),
+ * the summary also surfaces **task ownership across sessions** — which session
+ * owns which DevPipeline task right now, and any cross-session collision. A
+ * task whose owning session has been silent past `pipeline.workingStaleAfterMinutes`
+ * (default 90) is auto-evicted: the task file moves from `working/` back to
+ * `backlog/` and the owner detaches.
+ *
+ * Usage:  node contextkit/tools/scripts/workspace-sync.mjs
+ */
+import { existsSync, renameSync, readFileSync, readdirSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { loadConfigSync } from '../../runtime/config/load.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { writeFileAtomic, writeFileAtomicSync } from '../../runtime/hooks/safe-io.mjs';
+import { readState, writeState } from '../../runtime/state/state-io.mjs';
+
+const ROOT = process.cwd();
+const WORKSPACE_DIR = resolve(ROOT, '.claude/.workspace');
+const OUTPUT_PATH = pathsFor(ROOT).workspaceIndex;
+const PIPE_DIR = pathsFor(ROOT).pipeline;
+const STALE_AFTER_MS = 60 * 60 * 1000;
+const DEFAULT_TASK_STALE_MIN = 90;
+
+async function loadClaims() {
+  let files = [];
+  try {
+    files = await readdir(WORKSPACE_DIR);
+  } catch {
+    return [];
+  }
+  const claims = [];
+  for (const filename of files) {
+    if (!filename.endsWith('.json')) continue;
+    try {
+      claims.push(JSON.parse(await readFile(resolve(WORKSPACE_DIR, filename), 'utf-8')));
+    } catch {
+      /* skip malformed */
+    }
+  }
+  return claims;
+}
+
+function isStale(claim) {
+  if (typeof claim?.lastHeartbeat !== 'number') return true;
+  return Date.now() - claim.lastHeartbeat > STALE_AFTER_MS;
+}
+
+function relativeTime(ms) {
+  const s = Math.floor((Date.now() - ms) / 1000);
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+/**
+ * Walks every workspace record's `tasks[]` and evicts any whose heartbeat
+ * exceeds `workingStaleAfterMinutes`. Eviction moves the task file from
+ * `working/` back to `backlog/`, stamps an audit line in its body, and rewrites
+ * the workspace record without that task entry.
+ *
+ * Returns the set of evicted `{ sid, taskId }` so the caller (rendering) can
+ * surface the action. Best-effort I/O — failures don't throw, the workspace
+ * file is the source of truth either way.
+ *
+ * @param {Array<object>} claims — workspace records, in-place mutation allowed
+ * @param {number} maxMinutes
+ * @returns {Array<{ sid: string, taskId: string }>}
+ */
+function evictStaleTasks(claims, maxMinutes) {
+  const limit = maxMinutes * 60 * 1000;
+  const evicted = [];
+  for (const record of claims) {
+    if (!Array.isArray(record.tasks) || record.tasks.length === 0) continue;
+    const survivors = [];
+    for (const task of record.tasks) {
+      const ageMs = Date.now() - (task.lastHeartbeat || record.lastHeartbeat || 0);
+      if (ageMs <= limit) {
+        // Living task: mirror heartbeat into state.json (best-effort, ADR-0015 §C).
+        try {
+          if (readState(PIPE_DIR, task.id)) writeState(PIPE_DIR, task.id, { lastHeartbeat: task.lastHeartbeat || Date.now() });
+        } catch { /* */ }
+        survivors.push(task);
+        continue;
+      }
+      const moved = moveTaskFile(task.id, 'working', 'backlog', { sid: record.sessionId, ageMs });
+      if (moved) {
+        evicted.push({ sid: record.sessionId, taskId: task.id });
+        try {
+          if (readState(PIPE_DIR, task.id)) writeState(PIPE_DIR, task.id, { status: 'backlog', endedAt: Date.now() });
+        } catch { /* */ }
+      }
+    }
+    if (survivors.length !== record.tasks.length) {
+      record.tasks = survivors;
+      try {
+        const sid = (record.sessionId ?? 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+        const { ...body } = record;
+        writeFileAtomicSync(resolve(WORKSPACE_DIR, `${sid}.json`), JSON.stringify(body, null, 2));
+      } catch { /* best-effort */ }
+    }
+  }
+  return evicted;
+}
+
+function moveTaskFile(taskId, fromStage, toStage, { sid, ageMs }) {
+  try {
+    const fromDir = resolve(PIPE_DIR, fromStage);
+    if (!existsSync(fromDir)) return false;
+    const fileName = readdirSync(fromDir).find((f) => f.startsWith(String(taskId).padStart(3, '0') + '-') && f.endsWith('.md'));
+    if (!fileName) return false;
+    const fromPath = resolve(fromDir, fileName);
+    const toPath = resolve(PIPE_DIR, toStage, fileName);
+    let text = readFileSync(fromPath, 'utf-8').replace(/^(status:).*$/m, `status: ${toStage}`);
+    const note = `\n> auto-evicted from working/ at ${new Date().toISOString()} — session ${(sid || 'unknown').slice(0, 8)} idle for ${Math.floor(ageMs / 60000)}m\n`;
+    if (!text.endsWith('\n')) text += '\n';
+    text += note;
+    writeFileAtomicSync(fromPath, text);
+    renameSync(fromPath, toPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function renderTasksTable(active) {
+  const rows = [];
+  const seen = new Map();
+  for (const record of active) {
+    if (!Array.isArray(record.tasks)) continue;
+    for (const task of record.tasks) {
+      const collision = seen.has(task.id);
+      seen.set(task.id, (seen.get(task.id) || 0) + 1);
+      rows.push({ id: task.id, sid: (record.sessionId ?? '?').slice(0, 8), user: record.user ?? '_unknown_', branch: record.branch ?? '_detached_', started: relativeTime(task.startedAt || Date.now()), heartbeat: relativeTime(task.lastHeartbeat || Date.now()), collision });
+    }
+  }
+  if (rows.length === 0) return [];
+  const out = [`## 🔵 Working tasks (${rows.length})`, '', '| Task | Session | User | Branch | Started | Heartbeat |', '| --- | --- | --- | --- | --- | --- |'];
+  for (const r of rows) {
+    const id = r.collision || (seen.get(r.id) || 0) > 1 ? `⚠️ ${r.id}` : r.id;
+    out.push(`| ${id} | \`${r.sid}\` | ${r.user} | \`${r.branch}\` | ${r.started} | ${r.heartbeat} |`);
+  }
+  out.push('');
+  return out;
+}
+
+function buildMarkdown(active, stale, evicted) {
+  const out = [];
+  out.push('# Workspace — Active Sessions');
+  out.push('');
+  out.push('> ⚠️  **AUTO-GENERATED FILE — DO NOT EDIT BY HAND**.');
+  out.push('> Regenerated by `workspace-sync` (runs on pre-commit) from');
+  out.push('> `.claude/.workspace/<sid>.json` files maintained by hooks and slash commands.');
+  out.push('');
+  const tasksSection = renderTasksTable(active);
+  if (active.length === 0 && stale.length === 0 && tasksSection.length === 0) {
+    out.push('_(No active sessions. The workspace is idle.)_');
+    out.push('');
+    return out.join('\n');
+  }
+  out.push(...tasksSection);
+  if (active.length > 0) {
+    out.push(`## 🟢 Active sessions (${active.length})`);
+    out.push('');
+    out.push('| Session | User | Branch | Started | Last activity | Claims |');
+    out.push('| --- | --- | --- | --- | --- | --- |');
+    for (const c of active) {
+      const sid = (c.sessionId ?? '?').slice(0, 8);
+      const claims = Array.isArray(c.claims) && c.claims.length > 0 ? c.claims.map((cl) => `\`${cl.path}\``).join(', ') : '_(none)_';
+      out.push(`| \`${sid}\` | ${c.user ?? '_unknown_'} | \`${c.branch ?? '_detached_'}\` | ${c.startedAt ? relativeTime(c.startedAt) : '?'} | ${c.lastHeartbeat ? relativeTime(c.lastHeartbeat) : '?'} | ${claims} |`);
+    }
+    out.push('');
+  }
+  if (stale.length > 0) {
+    out.push(`## 🟡 Stale (${stale.length}) — no heartbeat for > 1h`);
+    out.push('');
+    out.push('| Session | User | Branch | Last activity |');
+    out.push('| --- | --- | --- | --- |');
+    for (const c of stale) {
+      out.push(`| \`${(c.sessionId ?? '?').slice(0, 8)}\` | ${c.user ?? '_unknown_'} | \`${c.branch ?? '_detached_'}\` | ${c.lastHeartbeat ? relativeTime(c.lastHeartbeat) : '?'} |`);
+    }
+    out.push('');
+  }
+  if (evicted.length > 0) {
+    out.push(`## ♻️ Recently auto-evicted (this run): ${evicted.length}`);
+    out.push('');
+    for (const ev of evicted) out.push(`- task **${ev.taskId}** (was owned by session \`${ev.sid?.slice(0, 8) ?? '?'}\`) → moved back to \`backlog/\``);
+    out.push('');
+  }
+  out.push('---');
+  out.push('');
+  out.push('Slash commands: `/claim <path>` to reserve a path · `/pipeline start <id>` to attach a task · `/release` / `/pipeline stop <id>` to free · `/worktree-new <feature>` for parallel work.');
+  return out.join('\n');
+}
+
+async function main() {
+  const claims = await loadClaims();
+  const cfg = loadConfigSync(ROOT).pipeline || {};
+  const evicted = evictStaleTasks(claims, cfg.workingStaleAfterMinutes || DEFAULT_TASK_STALE_MIN);
+  const active = claims.filter((c) => !isStale(c));
+  const stale = claims.filter(isStale);
+  await writeFileAtomic(OUTPUT_PATH, buildMarkdown(active, stale, evicted));
+  console.log(`✅ WORKSPACE.md regenerated — ${active.length} active, ${stale.length} stale, ${evicted.length} task(s) auto-evicted.`);
+}
+
+main().catch((err) => {
+  console.error('❌ Failed to sync workspace:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/worktree-new.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * Creates a git worktree + branch for a parallel session on the same machine.
+ *
+ * Each worktree gets its own `.claude/.sessions/` (it lives outside `.git`),
+ * so parallel Claude chats never collide on the ledger or on live edits.
+ *
+ * Usage:  node contextkit/tools/scripts/worktree-new.mjs <feature> [base-branch]
+ *   Creates branch `feat/<feature>` and worktree `../<repo>-<feature>`.
+ */
+import { execFileSync } from 'node:child_process';
+import { basename, resolve } from 'node:path';
+
+const ROOT = process.cwd();
+
+// execFileSync (argv array, NO shell) so a crafted base-branch arg can never
+// inject — e.g. `worktree-new.mjs feat "HEAD; rm -rf ~"` is passed to git as a
+// single literal revision and simply fails, instead of running the `rm`.
+function git(args) {
+  return execFileSync('git', args, { cwd: ROOT, encoding: 'utf-8' }).trim();
+}
+
+function main() {
+  const feature = process.argv[2];
+  const base = process.argv[3] || 'HEAD';
+  if (!feature) {
+    console.error('Usage: worktree-new.mjs <feature> [base-branch]');
+    process.exit(1);
+  }
+  const slug = feature.replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+  const branch = `feat/${slug}`;
+  const repoName = basename(ROOT);
+  const dest = resolve(ROOT, '..', `${repoName}-${slug}`);
+
+  try {
+    git(['worktree', 'add', '-b', branch, dest, base]);
+  } catch (err) {
+    console.error(`❌ Could not create worktree: ${err?.message ?? err}`);
+    process.exit(1);
+  }
+
+  console.log(`✅ Worktree created.`);
+  console.log(`   Branch:   ${branch}`);
+  console.log(`   Path:     ${dest}`);
+  console.log(`\nOpen it in a separate Claude Code window:`);
+  console.log(`   code "${dest}"`);
+  console.log(`\nWhen done:  git push -u origin ${branch}  (then open a PR).`);
+}
+
+main();

package/templates/contextkit/workflows/L1-static-loading.md

@@ -0,0 +1,59 @@
+# L1 — Static loading (auto-load at boot)
+
+> Level 1 of the context system. Solves: **"How does Claude start every session
+> already knowing the essentials, without the user explaining them?"**
+
+## How it works
+
+When Claude Code opens a session in this directory, it automatically loads:
+
+| File / folder | When | Content |
+| --- | --- | --- |
+| `CLAUDE.md` (root) | Always | Stack, immutable rules, the coding constitution, active level. |
+| `<module>/CLAUDE.md` | When editing that subtree | Local rules scoped to a module (see `/claude-md`). |
+| `.claude/agents/<name>.md` | Always (frontmatter) | Squad agents — auto-dispatched when the domain matches (L4+). |
+| `.claude/commands/<name>.md` | Always (frontmatter) | Slash commands available in the chat. |
+
+On top of that, the `SessionStart` hook (L2) injects **dynamic** boot context: the
+last registered session, `[Unreleased]` from the changelog, detected drift, active
+claims, and ahead/behind divergence vs `origin/<main>`.
+
+## Hard technical constraints
+
+- Claude Code reads from fixed paths: `.claude/settings.json`, `.claude/commands/`,
+  `.claude/agents/`. **Do not move** these folders.
+- `.claude/.sessions/` and `.claude/.workspace/` are runtime state (gitignored).
+  They persist between sessions but never reach the repo.
+- Everything the platform owns lives under `contextkit/` — the single `PLATFORM_DIR`
+  (`contextkit/runtime/config/paths.mjs`). Never hardcode the folder name elsewhere.
+
+## End-to-end flow when Claude opens
+
+1. Claude Code reads root `CLAUDE.md` (the whole system, described tersely).
+2. Reads `.claude/agents/*.md` — squad agents become available for delegation (L4+).
+3. Reads `.claude/commands/*.md` — slash commands become available in the input.
+4. The `SessionStart` hook (`contextkit/runtime/hooks/session-start.mjs`) runs via
+   `.claude/settings.json`:
+   - silent `git fetch origin` (short timeout, never blocks);
+   - drift analysis of previous sessions;
+   - a fresh ledger for this session;
+   - injection of the boot context.
+5. Editing a file under a module that has its own `CLAUDE.md` loads those local rules.
+
+## Maintenance rules
+
+- **Keep it lean.** Root `CLAUDE.md` is the overview; detail goes into ADRs or linked
+  docs. The file warns when it grows past ~200 lines.
+- **Don't duplicate** between root and scoped `CLAUDE.md` — the child complements,
+  never repeats.
+- **Don't inflate** `.claude/agents/<name>.md` — the frontmatter is executable; the
+  rich briefing lives in `contextkit/squads/<team>/<name>.md` (L4).
+- Slash commands stay in `.claude/commands/`; their narrative playbooks live in
+  `contextkit/workflows/playbooks/`.
+
+## When to update
+
+- Stack change (lib, framework, runtime) → root `CLAUDE.md` **and** an ADR.
+- New squad agent → `.claude/agents/<name>.md` + `contextkit/squads/<team>/<name>.md`.
+- New slash command → `.claude/commands/<name>.md` (+ a playbook here if it carries
+  judgment) + update the command list in root `CLAUDE.md`.

package/templates/contextkit/workflows/L2-session-ledger.md

@@ -0,0 +1,86 @@
+# L2 — Session ledger + drift detection
+
+> Level 2 of the context system. Solves: **"How do we detect that a session touched
+> important files but was never registered?"**
+
+## The problem
+
+L1 loads context, but without instrumentation it relies on the AI's **discipline** to:
+1. read the history at the start (SESSIONS, CHANGELOG, ADRs), and
+2. update SESSIONS + CHANGELOG at the end (`/log-session`).
+
+If step 2 is skipped, the next session starts blind — silent divergence between the
+real state and the documented one. L2 instruments the system with hooks that
+**detect drift** automatically.
+
+## Components
+
+### Per-session ledger
+
+`.claude/.sessions/<sessionId>.json` — gitignored, isolated between parallel chats.
+It records each modification (path, tool, timestamp), whether the session was
+registered, and anti-loop flags. Shared helpers live in
+[`contextkit/runtime/hooks/ledger.mjs`](../runtime/hooks/ledger.mjs).
+
+### Claude Code hooks
+
+Wired in `.claude/settings.json` — every script lives in `contextkit/runtime/hooks/`:
+
+| Hook | Matcher | Script | Job |
+| --- | --- | --- | --- |
+| `SessionStart` | (always) | `session-start.mjs` | Boot context + drift detection. |
+| `PostToolUse` | `Edit\|Write\|MultiEdit` | `track-edits.mjs` | Append to ledger + heartbeat + cross-claim check. |
+| `Stop` | (always) | `check-registration.mjs` | Nudge if there is unregistered drift. |
+
+### The Stop-hook nudge decision
+
+```
+if stop_hook_active === true        → silent (anti-loop)
+if important paths < 2              → silent (small session)
+if registered || SESSIONS touched   → silent (already registered)
+if already warned this session      → silent
+otherwise                           → decision: "block"
+                                      (instructs /log-session or justify)
+```
+
+## What counts as an "important path"
+
+Drift detection classifies paths via
+[`contextkit/runtime/hooks/path-classification.mjs`](../runtime/hooks/path-classification.mjs),
+driven by `contextkit/config.json` — **not hardcoded per stack**. By default, source
+code, the platform folder, and CI/config files trigger drift; generated output
+(`node_modules/`, `dist/`, build caches) and the platform's own runtime state
+(`.claude/.sessions/`, `.claude/.workspace/`) do not. Tune the lists with `/context-config`.
+
+## A full session flow
+
+```
+[open session]
+  → SessionStart: silent fetch · list prior drift (clear registered ledgers) ·
+    init fresh ledger · inject boot context
+[Claude edits]
+  → PostToolUse (each Edit/Write/MultiEdit): append paths · refresh heartbeat ·
+    warn on cross-claim with another session
+[Claude stops]
+  → Stop: check drift · if ≥ 2 unregistered important paths and not yet warned →
+    block with "run /log-session OR justify a discardable session"
+```
+
+## When something goes wrong
+
+- **Hook doesn't run** → check `.claude/settings.json` points to the
+  `contextkit/runtime/hooks/<name>.mjs` file and that it exists.
+- **False-positive drift** → a classification may be too broad; adjust via
+  `/context-config` (record an ADR if it's a real policy change).
+- **Stop hook re-nudging** → the anti-loop flag lives in the ledger; if it repeats,
+  the ledger may be getting recreated each Stop — investigate.
+- **Two chats in one worktree** → use a `git worktree` (L3); the ledger is
+  per-session but live file edits still collide on one filesystem.
+
+## Do not
+
+- Put business logic in a hook.
+- Add external deps to `runtime/hooks/` — Node built-ins only (immutable rule #1).
+- Block the user — hooks are defensive and exit 0 on error. The only intentional
+  block is the Stop nudge via `decision: "block"`.
+- Hand-edit `SESSIONS.md` / `WORKSPACE.md` — they are auto-generated indices.

package/templates/contextkit/workflows/L3-multi-session.md

@@ -0,0 +1,80 @@
+# L3 — Parallel multi-session (claims + worktrees)
+
+> Level 3. Solves: **"How do we allow multiple Claude sessions (one dev in many
+> chats, or many devs) without state corruption or merge conflicts on shared
+> files?"**
+
+## The problem
+
+A naive "one dev / one session" assumption breaks in three ways:
+1. **A single monolithic ledger** — two sessions overwrite each other.
+2. **A monolithic `SESSIONS.md`** — two parallel `/log-session` runs guarantee a
+   merge conflict.
+3. **No visible coordination** — nobody knows who is touching what.
+
+## The solution, in four parts
+
+### 1. Per-session ledger (gitignored)
+
+`.claude/.sessions/<sid>.json` — one file per session, zero collision. Built in L2;
+the foundation here.
+
+### 2. SESSIONS.md as a generated index
+
+`contextkit/memory/SESSIONS.md` is no longer hand-edited. Each session writes its **own
+file** at `contextkit/memory/sessions/<YYYY-MM-DD>-<NN>-<slug>.md`; the index is
+regenerated and refreshed by the `pre-commit` git hook. Two sessions can register in
+parallel — different files, recomposed index.
+
+### 3. WORKSPACE.md — aggregated claims
+
+A session reserves paths with `/claim <path…>`:
+- writes/updates `.claude/.workspace/<sid>.json` (gitignored) with session, branch,
+  claims, and heartbeat;
+- the aggregate is rendered into `contextkit/memory/WORKSPACE.md` (versioned) and
+  refreshed by the pre-commit hook;
+- the `PostToolUse` hook (L2, `concurrency-guard.mjs`) reads **other** sessions'
+  `.workspace/*.json` and emits a cross-claim warning if your edit lands inside
+  someone else's claim. Free a claim with `/release`.
+
+### 4. Git worktree for parallel chats on one machine
+
+```
+/worktree-new <feature> [base]
+# → ../<repo>-<feature> on branch feat/<feature>
+# each worktree has its own .claude/.sessions/ → zero filesystem collision
+```
+When the feature is done: `git push -u origin feat/<feature>`, then open a PR.
+
+## Slash commands of this level
+
+- `/claim <path…>` — reserve paths for this session.
+- `/release [path]` — free a specific claim, or all of them.
+- `/worktree-new <feature> [base]` — create a worktree + branch for a parallel session.
+
+## Scenarios
+
+**You alone, several chats on one machine** → use worktrees. Each chat gets its own
+directory, branch, and isolated `.claude/.sessions/`.
+
+**Multiple devs on different machines** → SESSIONS and WORKSPACE are generated (no
+conflict). The CHANGELOG stays single; the "one bullet per line, grouped
+sub-sections" format keeps conflicts small. Before starting: `git fetch && git
+status` (the SessionStart hook does this). Use `/claim` to reserve, and a `feat/<x>`
+branch for large changes.
+
+**Two chats in one worktree (not recommended)** → `/log-session` resolves the active
+session via a last-touched pointer; in one shared tree, "last editor wins" can pick
+the wrong session. Worktrees remove the problem at the root (~30s of setup).
+
+## Branch & commit conventions
+
+- Branch: `feat/` · `fix/` · `chore/` · `docs/` · `refactor/` · `test/` · `ci/` ·
+  `build/` · `perf/` · `style/` · `revert/`.
+- Commit: `<type>(<scope>)?: <subject>` (Conventional Commits) — validated by the
+  `commit-msg` git hook.
+
+## Do not
+
+- Hand-edit `SESSIONS.md` / `WORKSPACE.md` — regenerated by the pre-commit hook.
+- Run two heavy sessions in one worktree when a worktree would isolate them.