@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/skills/_shared/scripts/skills-check.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Skills drift governance — detects when a template static skill under
+ * `.claude/skills/<name>/` has drifted from the `@playcraft/skills` package copy
+ * it shadows.
+ *
+ * The template intentionally ships static copies of a few platform skills
+ * (e.g. image/audio/sprite generation) that take precedence over the package
+ * version. That is a deliberate fork — but without a check it silently rots when
+ * the package moves on. This compares the shadowing static copies against the
+ * package and flags content drift so the fork stays intentional.
+ *
+ * `sync-template-skills.mjs` is the single authoritative sync source for the
+ * local playable skills under `skills/`; this tool only governs the `.claude/skills`
+ * platform-skill shadows.
+ *
+ * Advisory by default (exit 0). With --strict, exits 2 when any shadow has drifted.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/skills-check.mjs --root=.
+ *   node skills/_shared/scripts/skills-check.mjs --root=. --json
+ *   node skills/_shared/scripts/skills-check.mjs --root=. --package-dir=/path/to/playcraft-skills
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false, packageDir: null };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg === '--json') opts.json = true;
+    else if (arg === '--strict') opts.strict = true;
+    else if (arg.startsWith('--package-dir=')) {
+      const v = arg.slice('--package-dir='.length);
+      opts.packageDir = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    }
+  }
+  return opts;
+}
+
+/** Locate the @playcraft/skills platform-skill directory (playcraft-skills/). */
+export function resolvePackageSkillsDir(projectRoot, override) {
+  const candidates = [];
+  if (override) candidates.push(override);
+  const root = resolve(projectRoot);
+  candidates.push(join(root, 'node_modules/@playcraft/skills/playcraft-skills'));
+  // monorepo dev: packages/cli/project-template/skills/_shared/scripts → packages/skills/playcraft-skills
+  candidates.push(resolve(__dirname, '../../../../../skills/playcraft-skills'));
+  for (const c of candidates) {
+    if (existsSync(c) && statSync(c).isDirectory()) return c;
+  }
+  return null;
+}
+
+/** Recursively list files (relative paths) under a directory, skipping noise. */
+function listFiles(dir, base = dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === '.DS_Store' || entry.name === 'node_modules' || entry.name === '__pycache__') continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) listFiles(abs, base, out);
+    else if (entry.isFile()) out.push(relative(base, abs).split('\\').join('/'));
+  }
+  return out;
+}
+
+function hashFile(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+/** Compare one skill dir in the template against the package copy. */
+function diffSkill(templateDir, packageDir) {
+  const tFiles = new Set(listFiles(templateDir));
+  const pFiles = new Set(listFiles(packageDir));
+  const onlyInTemplate = [...tFiles].filter((f) => !pFiles.has(f)).sort();
+  const onlyInPackage = [...pFiles].filter((f) => !tFiles.has(f)).sort();
+  const changed = [];
+  for (const f of tFiles) {
+    if (!pFiles.has(f)) continue;
+    if (hashFile(join(templateDir, f)) !== hashFile(join(packageDir, f))) changed.push(f);
+  }
+  changed.sort();
+  const drifted = onlyInTemplate.length > 0 || onlyInPackage.length > 0 || changed.length > 0;
+  return { drifted, onlyInTemplate, onlyInPackage, changed };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ packageDir?: string }} [opts]
+ */
+export function analyzeSkillsDrift(projectRoot, opts = {}) {
+  const root = resolve(projectRoot);
+  const claudeSkills = join(root, '.claude/skills');
+  const packageDir = resolvePackageSkillsDir(root, opts.packageDir);
+
+  if (!packageDir) {
+    return {
+      ok: true,
+      root,
+      packageDir: null,
+      note: '@playcraft/skills not found (run `npm install` or pass --package-dir) — skipping drift check',
+      shadowed: [],
+    };
+  }
+
+  if (!existsSync(claudeSkills)) {
+    return { ok: true, root, packageDir, note: 'no .claude/skills directory', shadowed: [] };
+  }
+
+  const templateNames = readdirSync(claudeSkills, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+
+  const shadowed = [];
+  for (const name of templateNames) {
+    const pkgSkillDir = join(packageDir, name);
+    if (!existsSync(pkgSkillDir) || !statSync(pkgSkillDir).isDirectory()) continue;
+    const diff = diffSkill(join(claudeSkills, name), pkgSkillDir);
+    shadowed.push({ name, status: diff.drifted ? 'drift' : 'in-sync', ...diff });
+  }
+  shadowed.sort((a, b) => a.name.localeCompare(b.name));
+
+  const ok = !shadowed.some((s) => s.status === 'drift');
+  return { ok, root, packageDir, shadowed };
+}
+
+function printHuman(result) {
+  console.log(`[skills:check] ${result.ok ? 'IN SYNC' : 'DRIFT'} — ${result.root}`);
+  if (result.note) {
+    console.log(`  · ${result.note}`);
+    return;
+  }
+  console.log(`  package: ${result.packageDir}`);
+  if (result.shadowed.length === 0) {
+    console.log('  no template static skills shadow the @playcraft/skills package');
+    return;
+  }
+  for (const s of result.shadowed) {
+    const mark = s.status === 'drift' ? '✗' : '✓';
+    console.log(`  [${mark}] ${s.name}: ${s.status}`);
+    for (const f of s.changed) console.log(`        ~ ${f} (content differs)`);
+    for (const f of s.onlyInTemplate) console.log(`        + ${f} (template only)`);
+    for (const f of s.onlyInPackage) console.log(`        - ${f} (package only)`);
+  }
+  if (!result.ok) {
+    console.log('\n  Static shadows have diverged from the package. Reconcile intentionally,');
+    console.log('  or update the static copy from @playcraft/skills if the fork is no longer wanted.');
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = analyzeSkillsDrift(opts.root, { packageDir: opts.packageDir });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(opts.strict && !result.ok ? 2 : 0);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`[skills:check] ${err.message}`);
+    process.exit(1);
+  }
+}

package/project-templates/phaser/skills/_shared/scripts/slice-set.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * slice-axis-v1 — update the active slice's status in the slice state machine
+ * (docs/project-state.json → sliceState). On `status=verified` the next slice
+ * blocked on it (or the next pending slice) is auto-activated.
+ *
+ * Knife 12B: status=verified requires a passing validate/build.json for the active slice.
+ *
+ * Usage:
+ *   npm run slice:set -- status=verified verification="build.json ok"
+ *   npm run slice:set -- status=failed route=developer reason="feedback missing"
+ *   npm run slice:set -- status=in_progress
+ *
+ * See docs/harness/slice-axis-design.md.
+ */
+import { resolve } from 'node:path';
+import { getActiveSlice, readState, updateActiveSlice } from './state-store.mjs';
+import { validateBuildArtifactForSlice } from '../../playable-record/scripts/lib/build-artifact.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), kv: {} };
+  for (const arg of argv) {
+    if (arg === '--') continue;
+    if (arg.startsWith('--root=')) { opts.root = arg.slice('--root='.length); continue; }
+    if (arg === '--help' || arg === '-h') {
+      console.log('Usage: slice-set.mjs [--root=.] status=<pending|in_progress|verified|failed|blocked> [verification="..."] [route=<role>] [reason="..."]');
+      process.exit(0);
+    }
+    const m = arg.match(/^([a-zA-Z0-9_]+)=([\s\S]*)$/);
+    if (m) opts.kv[m[1]] = m[2];
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const root = resolve(opts.root);
+  const before = getActiveSlice(readState(root));
+  if (!before) {
+    console.error('[slice:set] no active slice — seed docs/project-state.json sliceState first (state:set -- sliceStatePatch=...)');
+    process.exit(1);
+  }
+
+  if (opts.kv.status === 'verified') {
+    const buildErrors = validateBuildArtifactForSlice(root, before);
+    if (buildErrors.length) {
+      for (const err of buildErrors) console.error(`[slice:set] ${err}`);
+      console.error('[slice:set] run npm run build and fix validate/build.json before status=verified');
+      process.exit(1);
+    }
+  }
+
+  // A `failed` slice MUST be precisely routable — otherwise the orchestrator has no
+  // recovery target and STOP would let an unactionable failure through.
+  if (opts.kv.status === 'failed' && !(opts.kv.route && opts.kv.reason)) {
+    console.error('[slice:set] status=failed requires both route=<role> and reason="..." (no route target = unresolved). Example: slice:set -- status=failed route=developer reason=feedbackMissing');
+    process.exit(1);
+  }
+
+  const routeTo = (opts.kv.route || opts.kv.reason)
+    ? { role: opts.kv.route || 'developer', reason: opts.kv.reason || '' }
+    : undefined;
+
+  const { slice, promotedTo } = updateActiveSlice(root, {
+    status: opts.kv.status,
+    verification: opts.kv.verification,
+    routeTo,
+  });
+
+  console.log(`[slice:set] ${slice.sliceId} → status=${slice.status}`);
+  if (slice.verification.length) console.log(`  verification: ${slice.verification[slice.verification.length - 1]}`);
+  if (slice.routeTo) console.log(`  routeTo: ${slice.routeTo.role} — ${slice.routeTo.reason}`);
+  if (promotedTo) console.log(`  ✓ auto-promoted: activeSliceId now ${promotedTo}`);
+  else if (slice.status === 'verified') console.log('  (no further slice to promote — queue drained)');
+}
+
+main();

package/project-templates/phaser/skills/_shared/scripts/state-advance-ring.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Advance the growth-ring state after the orchestrator-only Ring Gate is accepted.
+ *
+ * Usage:
+ *   npm run state:advance-ring -- --iteration 1 --accepted
+ */
+
+import { resolve } from 'node:path';
+import { advanceRing } from './state-store.mjs';
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), iteration: null, accepted: false, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--root=')) {
+      const value = arg.slice('--root='.length);
+      opts.root = value.startsWith('/') ? value : resolve(process.cwd(), value);
+    } else if (arg === '--iteration' || arg === '--ring') {
+      opts.iteration = argv[++i] ?? null;
+    } else if (arg.startsWith('--iteration=')) {
+      opts.iteration = arg.slice('--iteration='.length);
+    } else if (arg === '--accepted') {
+      opts.accepted = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: state-advance-ring.mjs [--root=.] --iteration 1..4 --accepted [--json]');
+      process.exit(0);
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  try {
+    const state = advanceRing(opts.root, {
+      iteration: opts.iteration,
+      accepted: opts.accepted,
+    });
+    const summary = {
+      iteration: state.handoff.iteration,
+      loop: state.handoff.loop,
+      ringGate: state.handoff.ringGate,
+      archivedRings: state.archivedRings,
+      assetMappingLocked: state.assetMappingLocked,
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(summary, null, 2));
+    } else {
+      console.log(`iteration: ${summary.iteration}`);
+      console.log(`loop: ${summary.loop}`);
+      console.log(`ringGate: ${summary.ringGate}`);
+      console.log(`assetMappingLocked: ${summary.assetMappingLocked}`);
+    }
+  } catch (error) {
+    console.error(`[state:advance-ring] ${error.message}`);
+    process.exit(2);
+  }
+}
+
+main();

package/project-templates/phaser/skills/_shared/scripts/state-get.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Read project state from docs/project-state.json (the machine source of truth;
+ * falls back to importing a legacy docs/project-state.md). This is the agent's
+ * handoff summary — agents read state via this command instead of opening the
+ * generated markdown.
+ *
+ * Usage:
+ *   npm run state:get -- iteration loop waiting_for
+ *   node skills/_shared/scripts/state-get.mjs --root=. --json iteration loop
+ */
+
+import { DOD_LABELS, parseRingDoDFlow, ringDoDKeysForIteration } from './ring-config.mjs';
+import {
+  disclosureForProjectState,
+  recommendedActionForDispatch,
+} from './disclosure-config.mjs';
+import { flatHandoff, getActiveSlice, readState, serializeRingDoD, serializeArchivedRings, stateExists } from './state-store.mjs';
+
+function nullishValue(value) {
+  if (value == null) return null;
+  const s = String(value).trim().toLowerCase();
+  return s === '' || s === 'null' || s === 'none' ? null : value;
+}
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), keys: [], json: false };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      opts.root = arg.slice('--root='.length);
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: state-get.mjs [--root=.] [--json] [key ...]');
+      process.exit(0);
+    } else if (!arg.startsWith('-')) {
+      opts.keys.push(arg);
+    }
+  }
+  return opts;
+}
+
+function recommendedNextAction({ handoff, state, disclosure, iteration, dispatchPacket }) {
+  if (dispatchPacket) {
+    return recommendedActionForDispatch(dispatchPacket);
+  }
+  const explicit = nullishValue(handoff.next_orchestrator_action);
+  const runner = state.ringGateRunner || {};
+  const routeTo = nullishValue(runner.ringGateRouteTo);
+  const canAsk = String(runner.ringGateCanAskUser || '').toLowerCase() === 'yes';
+  const verdict = String(runner.ringGateVerdict || '').toLowerCase();
+
+  if (canAsk) return `Run Ring Gate AskUserQuestion for iteration ${iteration}`;
+  if (verdict === 'fail' && routeTo) {
+    return `Route ring gate failure to ${routeTo}: ${runner.ringGateFailReason || 'see ring:gate output'}`;
+  }
+  if (explicit) return explicit;
+  return disclosure.nextCommands?.[0] ?? null;
+}
+
+function buildContextPacket({ state, disclosure, iteration, loop, dispatchPacket }) {
+  const context = state.handoffContext || {};
+  const nextRole = context.nextRole || {};
+  const dispatchRequired = dispatchPacket
+    ? [
+        ...(Array.isArray(dispatchPacket.requiredContext) ? dispatchPacket.requiredContext : []),
+        ...(Array.isArray(dispatchPacket.allowedFiles) ? dispatchPacket.allowedFiles : []),
+      ]
+    : [];
+  const requiredFiles = [
+    ...new Set([
+      ...(disclosure.currentRingRequiredFiles || []),
+      ...dispatchRequired,
+      ...(Array.isArray(nextRole.requiredFiles) ? nextRole.requiredFiles : []),
+    ]),
+  ];
+  const forbiddenFullReadFiles = [
+    ...new Set([
+      ...(disclosure.deferredFiles || []),
+      ...(Array.isArray(nextRole.forbiddenFiles) ? nextRole.forbiddenFiles : []),
+    ]),
+  ];
+  return {
+    iteration,
+    loop,
+    dispatchMode: disclosure.dispatchMode === true,
+    ring: context.ring || null,
+    lastRole: context.lastRole || null,
+    nextRole: {
+      role: nextRole.role || null,
+      mustKnow: Array.isArray(nextRole.mustKnow) ? nextRole.mustKnow : [],
+      requiredFiles,
+      forbiddenFullReadFiles,
+      artifactRefs: Array.isArray(nextRole.artifactRefs) ? nextRole.artifactRefs : [],
+    },
+    sharedDecisions: context.sharedDecisions || {},
+    openQuestions: Array.isArray(context.openQuestions) ? context.openQuestions : [],
+    requiredContextFields: disclosure.requiredContextFields || [],
+    artifactRefs: [
+      ...new Set([
+        ...((Array.isArray(context.lastRole?.artifactRefs) && context.lastRole.artifactRefs) || []),
+        ...((Array.isArray(nextRole.artifactRefs) && nextRole.artifactRefs) || []),
+        ...((disclosure.artifactRefs && disclosure.artifactRefs) || []),
+      ]),
+    ],
+  };
+}
+
+/**
+ * slice-axis-v1: compose the dispatchPacket from the active slice. This is the
+ * single dispatch entry — agents read this instead of inferring ring/loop scope.
+ * Returns null when no slice is active (harness falls back to ring:loop disclosure).
+ */
+function buildDispatchPacket(state) {
+  const active = getActiveSlice(state);
+  if (!active) return null;
+  const queue = (state.sliceState.slices || []).map((s) => ({
+    sliceId: s.sliceId,
+    status: s.status,
+    ...(s.blockedBy ? { blockedBy: s.blockedBy } : {}),
+  }));
+  return {
+    sliceId: active.sliceId,
+    role: active.role,
+    doWhat: active.doWhat,
+    flow: active.flow,
+    hypothesis: active.hypothesis,
+    requiredContext: active.requiredContext,
+    allowedFiles: active.allowedFiles,
+    forbiddenTasks: active.forbiddenTasks,
+    acceptance: active.acceptance,
+    evidenceTier: active.evidenceTier,
+    verifier: active.verifier,
+    fallbackRoute: active.fallbackRoute,
+    status: active.status,
+    verification: active.verification,
+    routeTo: active.routeTo,
+    queue,
+  };
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!stateExists(opts.root)) {
+    console.error('Missing docs/project-state.json (run npm run ensure:project)');
+    process.exit(1);
+  }
+  const state = readState(opts.root);
+  const handoff = flatHandoff(state);
+  const iteration = Number.parseInt(String(handoff.iteration || '1'), 10) || 1;
+  const loop = nullishValue(handoff.loop);
+  const dispatchPacket = buildDispatchPacket(state);
+  const disclosure = disclosureForProjectState({ iteration, loop, handoff, dispatchPacket });
+  const ringDoD = parseRingDoDFlow(serializeRingDoD(state.ringDoD));
+  const contextPacket = buildContextPacket({ state, disclosure, iteration, loop, dispatchPacket });
+  const dev = state.devPreview || {};
+  const checkpoints = state.progressCheckpoint || [];
+  const summary = {
+    iteration,
+    loop,
+    dispatchMode: disclosure.dispatchMode === true,
+    dispatchPacket,
+    sliceState: state.sliceState,
+    next_orchestrator_action: nullishValue(handoff.next_orchestrator_action),
+    currentAction: disclosure.currentAction,
+    currentRingRequiredFiles: disclosure.currentRingRequiredFiles,
+    deferredFiles: disclosure.deferredFiles,
+    allowedTasks: disclosure.allowedTasks,
+    forbiddenTasks: disclosure.forbiddenTasks,
+    nextRole: disclosure.nextRole,
+    artifactRefs: disclosure.artifactRefs,
+    requiredContextFields: disclosure.requiredContextFields,
+    evidencePaths: disclosure.evidencePaths,
+    contextPacket,
+    currentRingVerifiers: ringDoDKeysForIteration(iteration, opts.root).map((key) => ({
+      key,
+      label: DOD_LABELS[key] ?? key,
+      status: ringDoD[key] ?? null,
+    })),
+    nextCommands: disclosure.nextCommands,
+    devStatus: nullishValue(dev.devStatus),
+    devUrl: nullishValue(dev.devUrl),
+    loadCheck: nullishValue(dev.loadCheck),
+    uiReviewStatus: nullishValue(dev.uiReviewStatus),
+    ringGate: nullishValue(handoff.ringGate),
+    ringGateCanAskUser: nullishValue(state.ringGateRunner?.ringGateCanAskUser),
+    ringGateRouteTo: nullishValue(state.ringGateRunner?.ringGateRouteTo),
+    ringGateFailReason: nullishValue(state.ringGateRunner?.ringGateFailReason),
+    recommendedNextAction: recommendedNextAction({ handoff, state, disclosure, iteration, dispatchPacket }),
+    devBlockers: Array.isArray(dev.devBlockers) ? dev.devBlockers : [],
+    progressCheckpointCount: checkpoints.length,
+    lastCheckpoint: checkpoints.length > 0 ? checkpoints[checkpoints.length - 1] : null,
+    productionWaves: state.productionPipeline?.waves ?? [],
+    archivedRings: serializeArchivedRings(state.archivedRings),
+    archivedRingContexts: state.archivedRingContexts || {},
+  };
+  const source = { ...handoff, ...summary, ...dev };
+  const keys = opts.keys.length > 0 ? opts.keys : Object.keys(summary);
+
+  if (opts.json) {
+    const out = {};
+    for (const key of keys) {
+      out[key] = source[key] ?? null;
+    }
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
+
+  for (const key of keys) {
+    const value = source[key] ?? '';
+    console.log(`${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
+  }
+}
+
+main();

package/project-templates/phaser/skills/_shared/scripts/state-handoff.mjs

@@ -0,0 +1,120 @@
+/**
+ * Shared helpers for reading the Agent handoff YAML block in docs/project-state.md.
+ *
+ * Writes now flow through state-store.mjs (docs/project-state.json source of
+ * truth + rendered md). The parse helpers below remain the way read-only hooks
+ * (user-prompt, block-ring1-tasklist, block-developer-preflight) consume the
+ * rendered handoff block. `applyHandoffUpdates` is kept as a stable façade that
+ * delegates to the store, so callers (state-set, dev-start) don't change.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyStateUpdates, flatHandoff, readState } from './state-store.mjs';
+
+export const HANDOFF_HEADING = '## Agent handoff';
+
+export function resolveProjectStatePath(root) {
+  return path.join(path.resolve(root), 'docs/project-state.md');
+}
+
+export function parseHandoffBlock(content) {
+  const match = content.match(/(## Agent handoff[\s\S]*?```yaml\s*)([\s\S]*?)(```)/i);
+  if (!match) return null;
+  return {
+    prefix: match[1],
+    yaml: match[2],
+    suffix: match[3],
+    start: match.index,
+    end: match.index + match[0].length,
+  };
+}
+
+export function parseHandoffYaml(yamlText) {
+  /** @type {Record<string, string>} */
+  const handoff = {};
+  for (const line of yamlText.split('\n')) {
+    const kv = line.match(/^\s*([A-Za-z0-9_]+):\s*(.*?)\s*$/);
+    if (!kv) continue;
+    handoff[kv[1]] = kv[2].replace(/^['"]|['"]$/g, '').trim();
+  }
+  return handoff;
+}
+
+export function serializeHandoffYaml(handoff, originalYaml) {
+  const order = [];
+  for (const line of originalYaml.split('\n')) {
+    const kv = line.match(/^\s*([A-Za-z0-9_]+):/);
+    if (kv && !order.includes(kv[1])) order.push(kv[1]);
+  }
+  for (const key of Object.keys(handoff)) {
+    if (!order.includes(key)) order.push(key);
+  }
+  return `${order.map((key) => `${key}: ${handoff[key] ?? ''}`).join('\n')}\n`;
+}
+
+/** Sync a few human-readable table cells when handoff keys change. */
+export function syncHumanTables(content, updates) {
+  let next = content;
+  const tableSync = {
+    iteration: 'iteration',
+    ringGate: 'ringGate',
+  };
+  for (const [key, tableField] of Object.entries(tableSync)) {
+    if (!(key in updates)) continue;
+    const value = String(updates[key]);
+    const rowRe = new RegExp(`(\\|\\s*${tableField}\\s*\\|\\s*)([^|]*)(\\s*\\|)`, 'i');
+    if (rowRe.test(next)) {
+      next = next.replace(rowRe, `$1${value}$3`);
+    }
+  }
+  if ('devStatus' in updates) {
+    const rowRe = /(\|\s*devStatus\s*\|\s*)([^|]*)(\s*\|)/i;
+    if (rowRe.test(next)) {
+      next = next.replace(rowRe, `$1${updates.devStatus}$3`);
+    }
+  }
+  if ('devUrl' in updates) {
+    const rowRe = /(\|\s*devUrl\s*\|\s*)([^|]*)(\s*\|)/i;
+    if (rowRe.test(next)) {
+      next = next.replace(rowRe, `$1${updates.devUrl}$3`);
+    }
+  }
+  return next;
+}
+
+export function readHandoffFromFile(statePath) {
+  if (!fs.existsSync(statePath)) {
+    throw new Error(`Missing ${statePath}`);
+  }
+  const content = fs.readFileSync(statePath, 'utf8');
+  const block = parseHandoffBlock(content);
+  if (!block) {
+    throw new Error('Missing ## Agent handoff ```yaml block in docs/project-state.md');
+  }
+  return { content, block, handoff: parseHandoffYaml(block.yaml) };
+}
+
+/** Derive the project root from a docs/project-state.md path. */
+function rootFromStatePath(statePath) {
+  // statePath = <root>/docs/project-state.md
+  return path.dirname(path.dirname(path.resolve(statePath)));
+}
+
+/**
+ * Apply flat key/value handoff updates through the state store (JSON source of
+ * truth + rendered md). Signature preserved for backward compatibility.
+ * @param {string} statePath path to docs/project-state.md
+ * @param {Record<string, string>} updates
+ * @returns {Record<string, string>} flattened handoff (string map)
+ */
+export function applyHandoffUpdates(statePath, updates) {
+  const root = rootFromStatePath(statePath);
+  const state = applyStateUpdates(root, updates);
+  return flatHandoff(state);
+}
+
+/** Read the flattened handoff (string map) for a project root. */
+export function readHandoffForRoot(root) {
+  return flatHandoff(readState(root));
+}