@ikon85/agent-workflow-kit 0.10.0

package/src/cli.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { init } from './commands/init.mjs';
+import { update } from './commands/update.mjs';
+import { diff } from './commands/diff.mjs';
+import { uninstall } from './commands/uninstall.mjs';
+
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const consumerRoot = process.cwd();
+
+function stamp() {
+  // backup suffix: YYYYMMDDTHHMMSS (no separators that collide with shells)
+  return new Date().toISOString().replace(/[-:]/g, '').replace(/\..+/, '');
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const force = args.includes('--force');
+const yes = args.includes('--yes') || args.includes('-y');
+
+p.intro('agent-workflow-kit');
+
+try {
+  if (cmd === 'init') {
+    const r = await init({ kitRoot: KIT_ROOT, consumerRoot, force });
+    p.note(
+      `copied ${r.copied.length} · seeded ${r.seeded.length} stub(s)` +
+        (r.skipped.length ? `\nskipped (pre-existing, use --force): ${r.skipped.join(', ')}` : ''),
+      'init'
+    );
+    p.outro('Next: run /setup-workflow to fill the project layer + board profile. ' +
+      'To enable the drift-guard hook, add .claude/hooks/drift-guard.py to your settings.json hooks.');
+  } else if (cmd === 'diff') {
+    const r = await diff({ kitRoot: KIT_ROOT, consumerRoot });
+    printPlan(r);
+    p.outro('Dry run — nothing written. Run `update` to apply.');
+  } else if (cmd === 'update') {
+    const decide = async (_action, path) => {
+      if (yes) return true;
+      const ok = await p.confirm({ message: `Upstream removed ${path} — delete it locally?` });
+      return ok === true;
+    };
+    const r = await update({ kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide });
+    printPlan(r);
+    for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (backed up): ${c.path}`);
+    p.outro(`updated ${r.updated.length} · added ${r.added.length} · ` +
+      `conflicts ${r.conflicts.length} · deleted ${r.deleted.length}`);
+  } else if (cmd === 'uninstall') {
+    const ok = yes || (await p.confirm({ message: 'Remove kit-installed files?' })) === true;
+    if (!ok) { p.cancel('Aborted.'); process.exit(0); }
+    const r = await uninstall({ consumerRoot });
+    p.outro(`removed ${r.removed.length} · retained (edited/referenced) ${r.retained.length}`);
+  } else {
+    p.note('Usage: agent-workflow-kit <init|update|diff|uninstall> [--force] [--yes]');
+    p.outro('');
+  }
+} catch (err) {
+  p.cancel(`Error: ${err.message}`);
+  process.exit(1);
+}
+
+function printPlan(r) {
+  const lines = [];
+  for (const k of ['added', 'updated', 'userModified', 'unchanged', 'deleted', 'keptDeleted'])
+    if (r[k]?.length) lines.push(`${k}: ${r[k].length}`);
+  if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
+  p.note(lines.join('\n') || 'no changes', 'plan');
+}

package/src/commands/diff.mjs

@@ -0,0 +1,6 @@
+import { update } from './update.mjs';
+
+/** Dry-run of `update`: classifies what an update would do, writes nothing. */
+export async function diff({ kitRoot, consumerRoot }) {
+  return update({ kitRoot, consumerRoot, now: 'dry', dryRun: true });
+}

package/src/commands/init.mjs

@@ -0,0 +1,59 @@
+import { readFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256File } from '../lib/hash.mjs';
+import { writeAtomic } from '../lib/atomicWrite.mjs';
+import { stubSentinel } from '../lib/sentinel.mjs';
+import { STUB_TARGETS } from '../lib/bundle.mjs';
+import {
+  readManifest, writeManifest, emptyConsumerManifest,
+  PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME,
+} from '../lib/manifest.mjs';
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+/**
+ * Install the kit into a consumer repo.
+ *  - copies every package-manifest file (never-clobbering a pre-existing UNTRACKED
+ *    file unless `force`),
+ *  - writes the consumer manifest,
+ *  - seeds the doc-layer stubs with the setup-workflow sentinel (skips any that
+ *    already exist — idempotent),
+ *  - never touches board-sync.md / CLAUDE.md / AGENTS.md.
+ */
+export async function init({ kitRoot, consumerRoot, force = false }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  const prior = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const tracked = new Set((prior?.installed ?? []).map((e) => e.path));
+
+  const result = { copied: [], skipped: [], seeded: [] };
+  const installed = [];
+
+  for (const f of pkg.files) {
+    const dest = join(consumerRoot, f.path);
+    if (await exists(dest) && !tracked.has(f.path) && !force) {
+      result.skipped.push(f.path); // pre-existing untracked → never-clobber
+      continue;
+    }
+    await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
+    installed.push({
+      path: f.path, kind: f.kind, ownerSkill: f.ownerSkill, surface: f.surface,
+      installedSha256: await sha256File(dest), origin: 'kit',
+    });
+    result.copied.push(f.path);
+  }
+
+  await writeManifest(
+    join(consumerRoot, CONSUMER_MANIFEST_NAME),
+    { ...emptyConsumerManifest(pkg.kitVersion), installed }
+  );
+
+  for (const stub of STUB_TARGETS) {
+    const dest = join(consumerRoot, stub);
+    if (await exists(dest)) continue; // already present (stub or filled) → leave it
+    await writeAtomic(dest, stubSentinel() + '\n');
+    result.seeded.push(stub);
+  }
+
+  return result;
+}

package/src/commands/uninstall.mjs

@@ -0,0 +1,43 @@
+import { access, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256File } from '../lib/hash.mjs';
+import { hookReferenced } from '../lib/settings.mjs';
+import { writeManifest, readManifest, emptyConsumerManifest, CONSUMER_MANIFEST_NAME } from '../lib/manifest.mjs';
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+/**
+ * Remove kit-installed files. User-edited files and hook files still referenced
+ * by settings are retained (Codex R1#11 / R3#7). If anything is retained, the
+ * manifest is kept with those entries marked `orphanedByUninstall`; on a fully
+ * clean uninstall the manifest is removed.
+ */
+export async function uninstall({ consumerRoot }) {
+  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!consumer) throw new Error('not initialised — nothing to uninstall');
+
+  const res = { removed: [], retained: [] };
+  const retainedEntries = [];
+
+  for (const e of consumer.installed) {
+    const dest = join(consumerRoot, e.path);
+    if (!(await exists(dest))) continue; // already gone
+    const userEdited = (await sha256File(dest)) !== e.installedSha256;
+    const referenced = e.kind === 'hook' && (await hookReferenced(consumerRoot, e.path));
+    if (userEdited || referenced) {
+      retainedEntries.push({ ...e, orphanedByUninstall: true });
+      res.retained.push(e.path);
+    } else {
+      await rm(dest);
+      res.removed.push(e.path);
+    }
+  }
+
+  const manifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
+  if (retainedEntries.length) {
+    await writeManifest(manifestPath, { ...emptyConsumerManifest(consumer.kitVersion), installed: retainedEntries });
+  } else {
+    await rm(manifestPath, { force: true });
+  }
+  return res;
+}

package/src/commands/update.mjs

@@ -0,0 +1,95 @@
+import { readFile, access, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256File } from '../lib/hash.mjs';
+import { writeAtomic, backupFile, lineDiff } from '../lib/atomicWrite.mjs';
+import { hookReferenced } from '../lib/settings.mjs';
+import {
+  readManifest, writeManifest, emptyConsumerManifest,
+  PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME, indexByPath,
+} from '../lib/manifest.mjs';
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+/**
+ * Reconcile an installed consumer against the current kit (three-way: installed
+ * hash vs current file = user edit?, vs package desired = upstream change?).
+ *  - unmodified + upstream changed → atomic overwrite (`updated`)
+ *  - user-edited + upstream changed → timestamped backup + diff, NOT clobbered (`conflicts`)
+ *  - user-edited + upstream same → left as-is (`userModified`)
+ *  - new upstream file → installed (`added`)
+ *  - upstream-removed + unmodified → offered for deletion via `decide` (`deleted`/`keptDeleted`)
+ *  - a hook file referenced by the consumer's settings is never auto-deleted (R3#7)
+ * `dryRun` classifies without writing (powers `diff`). `now` = backup stamp.
+ */
+export async function update({ kitRoot, consumerRoot, now, decide = () => false, dryRun = false }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!consumer) throw new Error('not initialised — run `init` first');
+
+  const installedIdx = indexByPath(consumer, 'installed');
+  const pkgIdx = indexByPath(pkg, 'files');
+  const res = { unchanged: [], updated: [], conflicts: [], userModified: [], added: [], deleted: [], keptDeleted: [] };
+  const nextInstalled = [];
+
+  for (const f of pkg.files) {
+    const dest = join(consumerRoot, f.path);
+    const prior = installedIdx.get(f.path);
+    const cur = (await exists(dest)) ? await sha256File(dest) : null;
+
+    if (!prior || cur === null) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
+      nextInstalled.push(entry(f, f.sha256));
+      res.added.push(f.path);
+      continue;
+    }
+    const userEdited = cur !== prior.installedSha256;
+    const upstreamChanged = f.sha256 !== prior.installedSha256;
+
+    if (!userEdited && upstreamChanged) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
+      nextInstalled.push(entry(f, f.sha256));
+      res.updated.push(f.path);
+    } else if (userEdited && upstreamChanged) {
+      const incoming = await readFile(join(kitRoot, f.path), 'utf8');
+      const diff = lineDiff(await readFile(dest, 'utf8'), incoming);
+      if (!dryRun) await backupFile(dest, now);
+      nextInstalled.push(prior); // keep installed-hash baseline; file stays user's
+      res.conflicts.push({ path: f.path, diff });
+    } else if (userEdited) {
+      nextInstalled.push(prior);
+      res.userModified.push(f.path);
+    } else {
+      nextInstalled.push(prior);
+      res.unchanged.push(f.path);
+    }
+  }
+
+  // upstream-removed files (in consumer manifest, gone from package)
+  for (const prior of consumer.installed) {
+    if (pkgIdx.has(prior.path)) continue;
+    const dest = join(consumerRoot, prior.path);
+    const cur = (await exists(dest)) ? await sha256File(dest) : null;
+    const userEdited = cur !== null && cur !== prior.installedSha256;
+    const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
+    if (userEdited || referenced || !(await decide('delete', prior.path))) {
+      nextInstalled.push(prior);
+      res.keptDeleted.push(prior.path);
+    } else {
+      if (!dryRun && cur !== null) await rm(dest);
+      res.deleted.push(prior.path);
+    }
+  }
+
+  if (!dryRun) {
+    await writeManifest(
+      join(consumerRoot, CONSUMER_MANIFEST_NAME),
+      { ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled }
+    );
+  }
+  return res;
+}
+
+function entry(f, sha) {
+  return { path: f.path, kind: f.kind, ownerSkill: f.ownerSkill, surface: f.surface, installedSha256: sha, origin: 'kit' };
+}

package/src/lib/atomicWrite.mjs

@@ -0,0 +1,49 @@
+import { writeFile, rename, mkdir, copyFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/**
+ * Write `content` to `path` atomically: write a sibling temp file, then rename
+ * (atomic on the same filesystem). Creates parent dirs. Preserves `mode` if given.
+ */
+export async function writeAtomic(path, content, mode) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${process.pid}`;
+  const opts = mode === undefined ? 'utf8' : { encoding: 'utf8', mode };
+  await writeFile(tmp, content, opts);
+  await rename(tmp, path);
+}
+
+/**
+ * Copy an existing file to `path.<stamp>.bak` (caller supplies the stamp so the
+ * name never collides and tests stay deterministic). Returns the backup path.
+ */
+export async function backupFile(path, stamp) {
+  const bak = `${path}.${stamp}.bak`;
+  await copyFile(path, bak);
+  return bak;
+}
+
+/**
+ * Minimal LCS-based line diff → unified-ish text. Context lines prefixed ' ',
+ * removals '-', additions '+'. Empty string when the inputs are identical.
+ */
+export function lineDiff(oldText, newText) {
+  const a = oldText.split('\n');
+  const b = newText.split('\n');
+  // LCS table
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--)
+    for (let j = n - 1; j >= 0; j--)
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+  const out = [];
+  let i = 0, j = 0;
+  while (i < m && j < n) {
+    if (a[i] === b[j]) { out.push(' ' + a[i]); i++; j++; }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { out.push('-' + a[i]); i++; }
+    else { out.push('+' + b[j]); j++; }
+  }
+  while (i < m) out.push('-' + a[i++]);
+  while (j < n) out.push('+' + b[j++]);
+  return out.some((l) => l[0] !== ' ') ? out.join('\n') : '';
+}

package/src/lib/bundle.mjs

@@ -0,0 +1,133 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+// The planning skills are not usable without their helper ecosystem (Codex R2#1).
+// These ship alongside the skills. Paths are relative to the bundle/consumer root.
+export const HELPER_FILES = [
+  // Shared profile loader imported by the three planning scripts — they read
+  // every board-specific value from docs/agents/board-sync.md through it, so it
+  // MUST ship or they are broken-on-arrival. Library (imported, not run) → 0o644.
+  { path: 'scripts/board_config.py', kind: 'script', mode: 0o644 },
+  // Pure Slices-table logic imported by board-sync.py for `anchor-sync` —
+  // library (imported, not run) → 0o644. MUST ship or board-sync.py ImportErrors.
+  { path: 'scripts/anchor_table.py', kind: 'script', mode: 0o644 },
+  // Programm-Graph module for `board-sync.py validate-graph` — split by
+  // concern (parse/validate) across three files, all libraries (imported, not
+  // run) → 0o644. MUST ship together or board-sync.py ImportErrors.
+  { path: 'scripts/program_graph.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/program_graph_parse.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/program_graph_validate.py', kind: 'script', mode: 0o644 },
+  // Pure node-kind classifier imported by execute-ready-check.py —
+  // library (imported, not run) → 0o644. MUST ship or execute-ready-check.py ImportErrors.
+  { path: 'scripts/node_kind.py', kind: 'script', mode: 0o644 },
+  // stamp-batch / field-value / promote-guard logic for board-sync.py —
+  // library (imported, not run) → 0o644. MUST ship or board-sync.py ImportErrors.
+  { path: 'scripts/board_fields.py', kind: 'script', mode: 0o644 },
+  // Wellenplan Status-resync for board-sync.py's `program-sync` —
+  // library (imported, not run) → 0o644. MUST ship or board-sync.py ImportErrors.
+  { path: 'scripts/program_sync.py', kind: 'script', mode: 0o644 },
+  // Blocked-by body-mirror logic for the native issue-dependency commands
+  // — imported by BOTH board-sync.py (dep-add/dep-remove) and
+  // execute-ready-check.py (drift check). Library (imported, not run) → 0o644.
+  // MUST ship or both ImportError on arrival.
+  { path: 'scripts/issue_deps.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/board-sync.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/execute-ready-check.py', kind: 'script', mode: 0o755 },
+  { path: 'scripts/pr-body-check.py', kind: 'script', mode: 0o755 },
+  // Mechanical executor for /wrapup (preflight/commit/land) — replaced the
+  // Sonnet phase-2 subagent. Imports board_config + anchor_table
+  // (both shipped above). Invokable CLI → 0o755.
+  { path: 'scripts/wrapup-land.py', kind: 'script', mode: 0o755 },
+  // Deterministic release preparation and its manifest-derived local/CI guard.
+  // Both are invoked through package scripts by /kit-release.
+  { path: 'scripts/kit-release.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/release-delta-guard.mjs', kind: 'script', mode: 0o644 },
+  // Shared hook utility imported by the shipped hooks (drift-guard,
+  // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
+  // hooks ImportError on arrival.
+  { path: '.claude/hooks/_hook_utils.py', kind: 'hook', mode: 0o644 },
+  { path: '.claude/hooks/drift-guard.py', kind: 'hook', mode: 0o755 },
+  // SessionStart skill-freshness drift-hint (audit-skills names it). For each
+  // <skill>/SOURCES.txt it flags sources newer in git than the SKILL.md. Imports
+  // _hook_utils (shipped above); stdlib-only otherwise. Executable hook → 0o755.
+  { path: '.claude/hooks/skill-drift-hint.py', kind: 'hook', mode: 0o755 },
+  // Board-status pickup hook — profile-driven (reads project/field/status ids
+  // from the consumer-seeded board profile), so it ships portably. /tdd names it.
+  { path: '.claude/hooks/sync-board-status.py', kind: 'hook', mode: 0o755 },
+  { path: 'docs/agents/wave-anchor-template.md', kind: 'template', mode: 0o644 },
+  // Part-0–5 security-audit runbook skeleton (the security-audit skill names it).
+  // The stack-coupled checklist is deliberately NOT shipped — this template is the
+  // generic structure a consumer copies + fills stack-specifically. Prose → 0o644.
+  { path: 'docs/agents/security-audit-runbook-template.md', kind: 'template', mode: 0o644 },
+  // Opt-in LoC-offender drive gate (setup-workflow §7b names it). Both are
+  // stdlib-only and profile-driven (threshold + offenders read from the
+  // consumer-seeded max-lines-allowlist.json), so they ship portably. The gate
+  // imports the core, so the core MUST ship too. core = library → 0o644;
+  // gate = invokable CLI (pre-push / manual) → 0o755.
+  { path: 'scripts/loc_offender_core.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/loc_offender_gate.py', kind: 'script', mode: 0o755 },
+];
+
+// Project-layer docs `init` seeds as empty stubs (sentinel first line). NOT
+// board-sync.md — that is discovery-dependent, /setup-workflow classifies+fills it
+// (Codex R1#8).
+export const STUB_TARGETS = [
+  'docs/agents/issue-tracker.md',
+  'docs/agents/triage-labels.md',
+  'docs/agents/domain.md',
+  'docs/agents/skills/spec-self-critique.md',
+  'docs/agents/skills/orchestrate-wave.md',
+  'docs/agents/skills/local-ci.md',
+  'docs/agents/skills/git-worktree-recover.md',
+  'docs/agents/skills/audit-skills.md',
+  'docs/agents/skills/security-audit.md',
+  'docs/conventions/spec-completeness.md',
+];
+
+const SURFACE_DIR = { claude: '.claude/skills', codex: '.agents/skills' };
+
+/** Skills with publish:true, each with the surfaces it installs into. */
+export function publishableSkills(manifest) {
+  return Object.entries(manifest.skills)
+    .filter(([, e]) => e.publish)
+    .map(([name, e]) => ({ name, surfaces: e.surfaces }));
+}
+
+async function walk(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return out;
+    throw err;
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(p)));
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Every file to copy from the kit into a consumer, plus the doc stubs to seed.
+ * Returns { files: [{ src, dest, kind, ownerSkill?, surface?, mode }], stubs: [paths] }.
+ * `src`/`dest` are repo-root-relative (same layout in kit and consumer).
+ */
+export async function collectBundle(repoRoot, manifest) {
+  const files = [];
+  for (const { name, surfaces } of publishableSkills(manifest)) {
+    for (const surface of surfaces) {
+      const base = join(SURFACE_DIR[surface], name);
+      for (const abs of await walk(join(repoRoot, base))) {
+        const rel = relative(repoRoot, abs);
+        files.push({ src: rel, dest: rel, kind: 'skill', ownerSkill: name, surface, mode: 0o644 });
+      }
+    }
+  }
+  for (const h of HELPER_FILES) {
+    files.push({ src: h.path, dest: h.path, kind: h.kind, mode: h.mode });
+  }
+  return { files, stubs: STUB_TARGETS };
+}

package/src/lib/hash.mjs

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+
+/** sha256 hex digest of a file's raw bytes. */
+export async function sha256File(path) {
+  const buf = await readFile(path);
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/** sha256 hex digest of an in-memory string/buffer. */
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex');
+}

package/src/lib/manifest.mjs

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+import { writeAtomic } from './atomicWrite.mjs';
+
+// Two manifests (Codex R1#9 / R3#1):
+//  - package manifest (shipped with the kit): the desired-state file list.
+//  - consumer manifest (agent-workflow-kit.json in the target repo root): installed state.
+// Both model every file kind:
+//   { path, kind: 'skill'|'script'|'hook'|'template'|'doc', ownerSkill?, surface?,
+//     sha256, mode, origin: 'kit' }
+
+export const CONSUMER_MANIFEST_NAME = 'agent-workflow-kit.json';
+export const PACKAGE_MANIFEST_NAME = 'agent-workflow-kit.package.json';
+
+/**
+ * Parse a JSON manifest, or null if the file does not exist. A corrupt file
+ * (invalid JSON — e.g. from an aborted write before writeManifest went atomic)
+ * throws a clear, recovery-hinting error instead of a raw JSON.parse stack;
+ * every command reads this file on startup, so an unreadable manifest bricks
+ * init/update/diff/uninstall until the user is told how to recover.
+ */
+export async function readManifest(path) {
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${path} is corrupt (invalid JSON) and can't be read. ` +
+        'Restore it from a nearby ".bak" backup, or delete it and re-run `init` to re-track the kit files.',
+      { cause: err }
+    );
+  }
+}
+
+/**
+ * Write a manifest as pretty JSON with a trailing newline, atomically
+ * (temp file + rename via writeAtomic) — an abort mid-write must never leave a
+ * truncated/corrupt manifest, since every command reads it on startup.
+ */
+export async function writeManifest(path, obj) {
+  await writeAtomic(path, JSON.stringify(obj, null, 2) + '\n');
+}
+
+export function emptyConsumerManifest(kitVersion) {
+  return { kitVersion, installed: [] };
+}
+
+/** Map a manifest's file list (under `key`) by `path` for quick lookup. */
+export function indexByPath(manifest, key) {
+  const idx = new Map();
+  for (const entry of (manifest?.[key] ?? [])) idx.set(entry.path, entry);
+  return idx;
+}

package/src/lib/sentinel.mjs

@@ -0,0 +1,20 @@
+// setup-workflow idempotency sentinel (contract). npx init seeds project-layer
+// stub files with this exact first line so /setup-workflow's stub→fill detection works.
+
+const RE = /^<!--\s*setup-workflow:\s*state=([a-z-]+)(?:;[^>]*)?\s*-->\s*$/;
+
+/** The first line npx init writes onto every seeded project-layer file. */
+export function stubSentinel() {
+  return '<!-- setup-workflow: state=stub -->';
+}
+
+/**
+ * State declared by the FIRST line only (a later mention does not count, per).
+ * Returns 'stub' | 'filled' | 'not-applicable' | ... or null if the first line
+ * is not a sentinel.
+ */
+export function firstLineState(text) {
+  const first = String(text).split('\n', 1)[0];
+  const m = RE.exec(first);
+  return m ? m[1] : null;
+}

package/src/lib/settings.mjs

@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+const SETTINGS = ['.claude/settings.json', '.claude/settings.local.json'];
+
+/**
+ * True if any consumer settings file references the hook (by path or basename).
+ * Used so update/uninstall never silently removes a hook that is still wired in
+ * (Codex R3#7). Substring match on the raw text — robust to JSON shape.
+ */
+export async function hookReferenced(consumerRoot, hookPath) {
+  const needle = basename(hookPath);
+  for (const s of SETTINGS) {
+    let raw;
+    try {
+      raw = await readFile(join(consumerRoot, s), 'utf8');
+    } catch {
+      continue;
+    }
+    if (raw.includes(hookPath) || raw.includes(needle)) return true;
+  }
+  return false;
+}