@playcraft/cli 0.0.44 → 0.0.47

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

@@ -0,0 +1,893 @@
+/**
+ * Single read/write layer over docs/project-state.json — the machine source of
+ * truth for project state. The human-readable docs/project-state.md is a
+ * GENERATED view rendered from this JSON after every write (see
+ * render-project-state.mjs). Agents read via `npm run state:get` and write via
+ * `npm run state:set` / `npm run ring:gate` / STOP hooks — they never hand-edit
+ * the markdown.
+ *
+ * Dual-path read: if docs/project-state.json is absent but a legacy
+ * docs/project-state.md exists, it is imported on read (best-effort) so old
+ * projects and md-only test fixtures keep working. Writes always persist JSON
+ * and re-render the md.
+ *
+ * See docs/harness/experiment-lessons.md §9.1.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  RING_GOALS,
+  allDoDPassed,
+  normalizeIteration,
+  parseRingDoDFlow,
+  parseArchivedRingsFlow,
+  ringDoDKeysForIteration,
+} from './ring-config.mjs';
+import { renderProjectState } from './render-project-state.mjs';
+
+export const STATE_JSON_REL = 'docs/project-state.json';
+export const STATE_MD_REL = 'docs/project-state.md';
+export const STATE_SCHEMA_VERSION = 1;
+
+export function resolveStateJsonPath(root) {
+  return path.join(path.resolve(root), STATE_JSON_REL);
+}
+
+export function resolveStateMdPath(root) {
+  return path.join(path.resolve(root), STATE_MD_REL);
+}
+
+/** Keys that live under devPreview (set via state:set or rendered to Dev Preview). */
+export const DEV_PREVIEW_KEYS = new Set([
+  'devStatus',
+  'devUrl',
+  'devStartedBy',
+  'devLastChecked',
+  'loadCheck',
+  'loadCheckNotes',
+  'uiReviewStatus',
+  'uiDiffNotes',
+  'uiReworkRound',
+  'devBlockers',
+]);
+
+/** Keys written by the ring:gate runner. */
+export const RING_GATE_RUNNER_KEYS = new Set([
+  'ringGateCurrent',
+  'ringGateVerdict',
+  'ringGateCheckedAt',
+  'ringGateBlockingIssues',
+  'ringGateCanAskUser',
+  'ringGateRouteTo',
+  'ringGateFailReason',
+  'ringGateNonRegression',
+]);
+
+/** Top-level scalar keys (not part of the handoff routing block). */
+export const TOP_LEVEL_KEYS = new Set([
+  'userIntent',
+  'selectedMcOption',
+  'assetMappingLocked',
+  'designerAutoDecide',
+]);
+
+/** Ordered handoff scalar keys for stable YAML rendering. */
+export const HANDOFF_KEY_ORDER = [
+  'iteration',
+  'ringGoal',
+  'loop',
+  'subagent',
+  'subagent_stop',
+  'waiting_for',
+  'ringGate',
+  'next_orchestrator_action',
+  'last_completed_by',
+  'block_reason',
+];
+
+export function defaultState() {
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    templateVersion: '0.3.2-alpha.0',
+    workflowSpecVersion: 'growth-rings-v1',
+    userIntent: '',
+    settings: { designerAutoDecide: false },
+    selectedMcOption: 'unset',
+    assetMappingLocked: false,
+    handoff: {
+      iteration: '1',
+      ringGoal: 'engine-root + core gameplay (placeholder art)',
+      loop: 'clarify',
+      subagent: 'none',
+      subagent_stop: 'false',
+      waiting_for: 'orchestrator',
+      ringGate: 'pending',
+      next_orchestrator_action: 'null',
+      last_completed_by: 'null',
+      block_reason: 'null',
+    },
+    ringDoD: {
+      contract: 'pending',
+      lifecycle: 'pending',
+      firstLevelWin: 'pending',
+      placeholders: 'pending',
+      ring2Visual: 'pending',
+      ring3Visual: 'pending',
+    },
+    handoffContext: {
+      ring: {
+        summary: 'Ring 1 starts as a semantic placeholder playable demo.',
+        goal: 'engine-root + core gameplay (placeholder art)',
+        passedDoD: [],
+      },
+      lastRole: {
+        role: 'none',
+        summary: 'No sub-agent has completed work yet.',
+        decisions: [],
+        artifactRefs: [],
+        validation: [],
+        blockers: [],
+      },
+      nextRole: {
+        role: 'orchestrator',
+        mustKnow: ['Run state:get and follow currentAction / nextCommands.'],
+        requiredFiles: ['CLAUDE.md'],
+        forbiddenFiles: [],
+        artifactRefs: [],
+      },
+      sharedDecisions: {
+        engine: 'unset',
+        coreAction: 'unset',
+        semanticPlaceholders: [],
+        assetContractRefs: [],
+      },
+      openQuestions: [],
+    },
+    ringArtifacts: {},
+    archivedRings: {},
+    archivedRingContexts: {},
+    ringGateRunner: {
+      ringGateCurrent: 'none',
+      ringGateVerdict: 'not_run',
+      ringGateCheckedAt: 'unset',
+      ringGateBlockingIssues: '0',
+      ringGateCanAskUser: 'no',
+      ringGateRouteTo: 'none',
+      ringGateFailReason: 'none',
+      ringGateNonRegression: 'n-a',
+    },
+    devPreview: {
+      devStatus: 'pending',
+      devUrl: 'unset',
+      devStartedBy: 'none',
+      devLastChecked: 'unset',
+      loadCheck: 'pending',
+      loadCheckNotes: 'unset',
+      uiReviewStatus: 'deferred',
+      uiDiffNotes: 'deferred',
+      uiReworkRound: '0',
+      devBlockers: [],
+    },
+    progressCheckpoint: [],
+    productionPipeline: { waves: [] },
+    fileIndex: [],
+    // slice-axis-v1 (see docs/harness/slice-axis-design.md): the slice state
+    // machine. Additive — when activeSliceId is 'none' the harness falls back to
+    // the existing ring:loop behavior, so existing projects/tests are unaffected.
+    sliceState: {
+      schemaVersion: 1,
+      activeSliceId: 'none',
+      slices: [],
+    },
+  };
+}
+
+/** A single slice's full default shape (dispatchPacket fields + runtime state). */
+export function defaultSlice() {
+  return {
+    sliceId: '',
+    role: 'developer',
+    doWhat: '',
+    flow: 'implement',
+    hypothesis: '',
+    requiredContext: [],
+    allowedFiles: [],
+    forbiddenTasks: [],
+    acceptance: [],
+    evidenceTier: 'probe',
+    skillRefs: [],
+    skillUse: '',
+    fromScratchReason: '',
+    verifier: 'verify:build',
+    fallbackRoute: {},
+    status: 'pending',
+    verification: [],
+    routeTo: null,
+    blockedBy: null,
+  };
+}
+
+const SLICE_STATUSES = new Set(['pending', 'in_progress', 'verified', 'failed', 'blocked']);
+
+/** Mirror validate-workflow-stop isSliceResolved — shared by STOP hook and ring:gate. */
+export function isSliceResolved(slice) {
+  if (!slice) return true;
+  if (slice.status === 'verified') return true;
+  if (slice.status === 'failed') {
+    return !!(slice.routeTo && slice.routeTo.role && slice.routeTo.reason);
+  }
+  return false;
+}
+
+/**
+ * slice-axis-v1 (Knife 9): ring gate outer boundary — aggregates slice queue terminal
+ * state. Does NOT run per-slice verifiers (verify:slice / verify:slice-artist / …).
+ * Legacy projects with empty slices[] → applicable:false (ring DoD only).
+ */
+export function evaluateSliceQueueForRingGate(sliceState) {
+  const ss = normalizeSliceState(sliceState || {});
+  if (!ss.slices.length) {
+    return {
+      applicable: false,
+      ok: true,
+      blockingIssues: [],
+      routeTo: 'none',
+      nextAction: 'No slice queue — ring gate uses ring DoD verifiers only',
+      summary: null,
+    };
+  }
+
+  const blockingIssues = [];
+  const pending = [];
+
+  for (const slice of ss.slices) {
+    if (isSliceResolved(slice)) continue;
+    pending.push(slice);
+    if (slice.status === 'failed') {
+      blockingIssues.push(
+        `slice "${slice.sliceId}" is failed without route — run slice:set with route=<role> reason="..." before ring gate`,
+      );
+    } else {
+      blockingIssues.push(
+        `slice "${slice.sliceId}" (${slice.role}) is ${slice.status} — resolve via ${slice.verifier || 'verify:slice'} + slice:set; ring:gate does not substitute per-slice verification`,
+      );
+    }
+  }
+
+  const first = pending[0];
+  const routeTo = first?.routeTo?.role || first?.role || 'developer';
+  const ok = pending.length === 0;
+
+  return {
+    applicable: true,
+    ok,
+    blockingIssues,
+    routeTo,
+    nextAction: ok
+      ? 'Slice queue acceptably terminal — ring gate may proceed to user acceptance if ring DoD passes'
+      : `Dispatch @${routeTo} to resolve slice "${first?.sliceId}" before ring gate (per-slice verify:slice runs at STOP, not here)`,
+    summary: {
+      total: ss.slices.length,
+      verified: ss.slices.filter((s) => s.status === 'verified').length,
+      failedRouted: ss.slices.filter((s) => s.status === 'failed' && isSliceResolved(s)).length,
+      pending: pending.map((s) => s.sliceId),
+      activeSliceId: ss.activeSliceId,
+    },
+  };
+}
+
+/** @deprecated use isSliceResolved */
+function isSliceResolvedForStore(slice) {
+  return isSliceResolved(slice);
+}
+
+/** Normalize the sliceState block: coerce arrays, fill slice defaults, dedupe. */
+export function normalizeSliceState(sliceState) {
+  const base = { schemaVersion: 1, activeSliceId: 'none', slices: [], lastResolvedForStop: null };
+  const merged = isPlainObject(sliceState) ? { ...base, ...sliceState } : base;
+  const rawSlices = Array.isArray(merged.slices) ? merged.slices : [];
+  const slices = rawSlices
+    .filter((s) => isPlainObject(s) && String(s.sliceId || '').trim())
+    .map((s) => {
+      const slice = { ...defaultSlice(), ...s };
+      slice.requiredContext = parseStringList(slice.requiredContext);
+      slice.allowedFiles = parseStringList(slice.allowedFiles);
+      slice.forbiddenTasks = parseStringList(slice.forbiddenTasks);
+      slice.acceptance = parseStringList(slice.acceptance);
+      if (slice.acceptance.length === 0 && Array.isArray(s.dod) && s.dod.length) {
+        slice.acceptance = parseStringList(s.dod);
+      }
+      slice.verification = parseStringList(slice.verification);
+      slice.skillRefs = parseStringList(slice.skillRefs);
+      slice.skillUse = String(slice.skillUse || '').trim();
+      slice.fromScratchReason = String(slice.fromScratchReason || '').trim();
+      if (!slice.evidenceTier) slice.evidenceTier = 'probe';
+      if (!slice.verifier) slice.verifier = 'verify:build';
+      if (!SLICE_STATUSES.has(String(slice.status))) slice.status = 'pending';
+      if (!isPlainObject(slice.fallbackRoute)) slice.fallbackRoute = {};
+      if (slice.routeTo != null && !isPlainObject(slice.routeTo)) slice.routeTo = null;
+      return slice;
+    });
+  const ids = new Set(slices.map((s) => s.sliceId));
+  // 'none' is an explicit sentinel (e.g. queue drained after the last slice is
+  // verified) and must survive normalization even when slices still exist —
+  // otherwise a completed queue would silently re-point to slices[0] and re-dispatch.
+  const activeSliceId = merged.activeSliceId === 'none'
+    ? 'none'
+    : (ids.has(merged.activeSliceId) ? merged.activeSliceId : (slices[0]?.sliceId ?? 'none'));
+  let lastResolvedForStop = null;
+  if (
+    isPlainObject(merged.lastResolvedForStop)
+    && merged.lastResolvedForStop.sliceId
+    && merged.lastResolvedForStop.role
+  ) {
+    lastResolvedForStop = {
+      sliceId: String(merged.lastResolvedForStop.sliceId),
+      role: String(merged.lastResolvedForStop.role),
+    };
+  }
+  // A newly active unresolved slice supersedes the drain marker (next dispatch cycle).
+  if (activeSliceId !== 'none') {
+    const activeSlice = slices.find((s) => s.sliceId === activeSliceId);
+    if (activeSlice && !isSliceResolvedForStore(activeSlice)) {
+      lastResolvedForStop = null;
+    }
+  }
+  return {
+    schemaVersion: 1,
+    activeSliceId: slices.length ? activeSliceId : 'none',
+    slices,
+    lastResolvedForStop,
+  };
+}
+
+function isPlainObject(v) {
+  return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function normalizeDevBlockers(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+  const raw = String(value ?? '').trim();
+  if (!raw || raw === 'none' || raw === '[]' || raw === 'null') return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed.map((v) => String(v).trim()).filter(Boolean);
+  } catch {
+    // Keep supporting concise CLI input such as "asset missing;route to TA".
+  }
+  return raw
+    .split(';')
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+export function parseStringList(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+  const raw = String(value ?? '').trim();
+  if (!raw || raw === 'none' || raw === '[]' || raw === 'null') return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed.map((v) => String(v).trim()).filter(Boolean);
+  } catch {
+    // Support terse CLI input such as "a;b,c".
+  }
+  return raw
+    .split(/[;,]/)
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+function parseJsonObject(value, key) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isPlainObject(parsed)) throw new Error('not object');
+    return parsed;
+  } catch {
+    throw new Error(`${key} must be a JSON object`);
+  }
+}
+
+function normalizeHandoffContext(context) {
+  const base = defaultState().handoffContext;
+  const merged = mergeState(base, isPlainObject(context) ? context : {});
+  merged.ring.passedDoD = parseStringList(merged.ring.passedDoD);
+  merged.lastRole.decisions = parseStringList(merged.lastRole.decisions);
+  merged.lastRole.artifactRefs = parseStringList(merged.lastRole.artifactRefs);
+  merged.lastRole.validation = parseStringList(merged.lastRole.validation);
+  merged.lastRole.blockers = parseStringList(merged.lastRole.blockers);
+  merged.nextRole.mustKnow = parseStringList(merged.nextRole.mustKnow);
+  merged.nextRole.requiredFiles = parseStringList(merged.nextRole.requiredFiles);
+  merged.nextRole.forbiddenFiles = parseStringList(merged.nextRole.forbiddenFiles);
+  merged.nextRole.artifactRefs = parseStringList(merged.nextRole.artifactRefs);
+  merged.sharedDecisions.semanticPlaceholders = parseStringList(
+    merged.sharedDecisions.semanticPlaceholders,
+  );
+  merged.sharedDecisions.assetContractRefs = parseStringList(
+    merged.sharedDecisions.assetContractRefs,
+  );
+  merged.openQuestions = parseStringList(merged.openQuestions);
+  return merged;
+}
+
+/** Deep-merge `patch` into `base`: nested plain objects merge, arrays/scalars replace. */
+export function mergeState(base, patch) {
+  const out = Array.isArray(base) ? [...base] : { ...base };
+  for (const [key, value] of Object.entries(patch || {})) {
+    if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergeState(out[key], value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/** Normalize a freshly-parsed JSON state to the full default shape. */
+export function normalizeState(raw) {
+  const state = mergeState(defaultState(), raw || {});
+  state.handoffContext = normalizeHandoffContext(state.handoffContext);
+  state.sliceState = normalizeSliceState(state.sliceState);
+  return state;
+}
+
+// ── Markdown importer (legacy md → JSON) ───────────────────────────────────
+
+function parseHandoffBlock(content) {
+  const match = content.match(/## Agent handoff[\s\S]*?```yaml\s*([\s\S]*?)```/i);
+  if (!match) return {};
+  const handoff = {};
+  for (const line of match[1].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;
+}
+
+/** Parse `| key | value |` style rows in a `## Heading` section into a Map. */
+function parseSectionKeyValues(content, heading) {
+  const map = new Map();
+  const start = content.indexOf(heading);
+  if (start === -1) return map;
+  const after = content.slice(start + heading.length);
+  const next = after.search(/\n##\s+/);
+  const section = next === -1 ? after : after.slice(0, next);
+  for (const line of section.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|')) continue;
+    if (/^\|[\s|:-]+\|?$/.test(trimmed)) continue;
+    const parts = trimmed
+      .split('|')
+      .map((p) => p.trim())
+      .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (parts.length < 2) continue;
+    const key = parts[0].replace(/\*\*/g, '').replace(/`/g, '').trim();
+    if (/^(field|owner|verifier)$/i.test(key)) continue;
+    const value = parts.length >= 3 ? parts[parts.length - 1] : parts[1];
+    if (!map.has(key)) map.set(key, value);
+  }
+  return map;
+}
+
+/** Best-effort import of a legacy docs/project-state.md into a state object. */
+export function importStateFromMarkdown(content) {
+  const state = defaultState();
+  const handoff = parseHandoffBlock(content);
+
+  for (const key of HANDOFF_KEY_ORDER) {
+    if (handoff[key] != null && handoff[key] !== '') state.handoff[key] = handoff[key];
+  }
+  if (handoff.ringDoD) state.ringDoD = parseRingDoDFlow(handoff.ringDoD);
+  if (handoff.archivedRings) state.archivedRings = parseArchivedRingsFlow(handoff.archivedRings);
+
+  // Human-table views (present in older / hand-authored md only).
+  const devPreview = parseSectionKeyValues(content, '## Dev Preview');
+  for (const key of DEV_PREVIEW_KEYS) {
+    if (devPreview.has(key)) state.devPreview[key] = devPreview.get(key);
+  }
+  const runner = parseSectionKeyValues(content, '## Ring Gate Runner');
+  for (const key of RING_GATE_RUNNER_KEYS) {
+    if (runner.has(key)) state.ringGateRunner[key] = runner.get(key);
+  }
+  // Some fixtures keep loadCheck / ringGateCanAskUser in ad-hoc tables anywhere.
+  const looseDev = parseSectionKeyValues(content, '## Dev Preview');
+  if (looseDev.has('devBlockers')) {
+    const raw = looseDev.get('devBlockers');
+    state.devPreview.devBlockers = !raw || raw === 'none' ? [] : [raw];
+  }
+
+  const intent = content.match(/##\s*User Intent\s*\n+>?\s*(.+)/i);
+  if (intent && !/\{\{/.test(intent[1])) state.userIntent = intent[1].trim();
+
+  const settings = parseSectionKeyValues(content, '## Settings');
+  if (settings.has('designerAutoDecide')) {
+    state.settings.designerAutoDecide = /true/i.test(settings.get('designerAutoDecide'));
+  }
+  return state;
+}
+
+// ── Read / write ────────────────────────────────────────────────────────────
+
+/**
+ * Read the project state. Prefers docs/project-state.json; falls back to
+ * importing a legacy docs/project-state.md; otherwise returns defaults.
+ * @param {string} root
+ */
+export function readState(root) {
+  const jsonPath = resolveStateJsonPath(root);
+  if (fs.existsSync(jsonPath)) {
+    try {
+      return normalizeState(JSON.parse(fs.readFileSync(jsonPath, 'utf8')));
+    } catch {
+      /* fall through to md import */
+    }
+  }
+  const mdPath = resolveStateMdPath(root);
+  if (fs.existsSync(mdPath)) {
+    return importStateFromMarkdown(fs.readFileSync(mdPath, 'utf8'));
+  }
+  return defaultState();
+}
+
+/** True when a JSON or md state file exists for `root`. */
+export function stateExists(root) {
+  return fs.existsSync(resolveStateJsonPath(root)) || fs.existsSync(resolveStateMdPath(root));
+}
+
+/**
+ * Persist `state` to JSON and re-render the markdown view.
+ * @param {string} root
+ * @param {object} state full state object
+ */
+export function persistState(root, state) {
+  const jsonPath = resolveStateJsonPath(root);
+  fs.mkdirSync(path.dirname(jsonPath), { recursive: true });
+  fs.writeFileSync(jsonPath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  try {
+    fs.writeFileSync(resolveStateMdPath(root), renderProjectState(state), 'utf8');
+  } catch {
+    /* rendering must never block a state write */
+  }
+  return state;
+}
+
+/**
+ * Merge `patch` into the current state and persist. Returns the new state.
+ * @param {string} root
+ * @param {object} patch
+ */
+export function writeState(root, patch) {
+  const next = mergeState(readState(root), patch || {});
+  return persistState(root, next);
+}
+
+// ── Structured mutators ───────────────────────────────────────────────────
+
+/** Apply flat handoff key/value updates (string values), routing by key. */
+export function applyStateUpdates(root, updates) {
+  const state = readState(root);
+  for (const [key, rawValue] of Object.entries(updates || {})) {
+    const value = String(rawValue);
+    if (DEV_PREVIEW_KEYS.has(key)) {
+      state.devPreview[key] = key === 'devBlockers' ? normalizeDevBlockers(value) : value;
+    } else if (RING_GATE_RUNNER_KEYS.has(key)) {
+      state.ringGateRunner[key] = value;
+    } else if (key === 'designerAutoDecide') {
+      state.settings.designerAutoDecide = /true/i.test(value);
+    } else if (key === 'userIntent') {
+      state.userIntent = value;
+    } else if (key === 'selectedMcOption') {
+      state.selectedMcOption = value;
+    } else if (key === 'assetMappingLocked') {
+      state.assetMappingLocked = /true/i.test(value);
+    } else if (key === 'handoffContext') {
+      state.handoffContext = normalizeHandoffContext(parseJsonObject(value, key));
+    } else if (key === 'handoffContextPatch') {
+      state.handoffContext = normalizeHandoffContext(
+        mergeState(state.handoffContext, parseJsonObject(value, key)),
+      );
+    } else if (key === 'sliceState') {
+      state.sliceState = normalizeSliceState(parseJsonObject(value, key));
+    } else if (key === 'sliceStatePatch') {
+      state.sliceState = normalizeSliceState(
+        mergeState(state.sliceState, parseJsonObject(value, key)),
+      );
+    } else if (key === 'activeSliceId') {
+      state.sliceState = normalizeSliceState({ ...state.sliceState, activeSliceId: value });
+    } else if (key === 'contextSummary') {
+      state.handoffContext.lastRole.summary = value;
+    } else if (key === 'contextRole') {
+      state.handoffContext.lastRole.role = value;
+    } else if (key === 'contextNextRole') {
+      state.handoffContext.nextRole.role = value;
+    } else if (key === 'contextMustKnow') {
+      state.handoffContext.nextRole.mustKnow = parseStringList(value);
+    } else if (key === 'contextRequiredFiles') {
+      state.handoffContext.nextRole.requiredFiles = parseStringList(value);
+    } else if (key === 'contextForbiddenFiles') {
+      state.handoffContext.nextRole.forbiddenFiles = parseStringList(value);
+    } else if (key === 'contextArtifactRefs') {
+      state.handoffContext.lastRole.artifactRefs = parseStringList(value);
+    } else if (key === 'contextValidation') {
+      state.handoffContext.lastRole.validation = parseStringList(value);
+    } else if (key === 'contextBlockers') {
+      state.handoffContext.lastRole.blockers = parseStringList(value);
+    } else if (key === 'contextOpenQuestions') {
+      state.handoffContext.openQuestions = parseStringList(value);
+    } else if (key === 'contextEngine') {
+      state.handoffContext.sharedDecisions.engine = value;
+    } else if (key === 'contextCoreAction') {
+      state.handoffContext.sharedDecisions.coreAction = value;
+    } else if (key === 'contextSemanticPlaceholders') {
+      state.handoffContext.sharedDecisions.semanticPlaceholders = parseStringList(value);
+    } else if (key === 'contextAssetContractRefs') {
+      state.handoffContext.sharedDecisions.assetContractRefs = parseStringList(value);
+    } else {
+      state.handoff[key] = value;
+    }
+  }
+  state.handoffContext = normalizeHandoffContext(state.handoffContext);
+  persistState(root, state);
+  return state;
+}
+
+export function setHandoffContext(root, patch) {
+  const state = readState(root);
+  state.handoffContext = normalizeHandoffContext(mergeState(state.handoffContext, patch || {}));
+  persistState(root, state);
+  return state;
+}
+
+// ── slice state machine (slice-axis-v1) ───────────────────────────────────
+
+/** Return the active slice object (or null). */
+export function getActiveSlice(state) {
+  const ss = state.sliceState || {};
+  if (!ss.activeSliceId || ss.activeSliceId === 'none') return null;
+  return (ss.slices || []).find((s) => s.sliceId === ss.activeSliceId) || null;
+}
+
+/**
+ * Update the active slice's status/verification/routeTo and persist. When a slice
+ * transitions to `verified`, the next slice blocked on it is unblocked and becomes
+ * active (auto-promotion). Returns { state, slice, promotedTo }.
+ */
+export function updateActiveSlice(root, { status, verification, routeTo } = {}) {
+  const state = readState(root);
+  const slices = state.sliceState.slices;
+  const active = slices.find((s) => s.sliceId === state.sliceState.activeSliceId);
+  if (!active) throw new Error('No active slice (sliceState.activeSliceId is none)');
+
+  if (status) {
+    if (!SLICE_STATUSES.has(status)) throw new Error(`Invalid slice status: ${status}`);
+    active.status = status;
+  }
+  if (verification) {
+    active.verification = Array.isArray(active.verification) ? active.verification : [];
+    active.verification.push(String(verification));
+  }
+  if (routeTo && isPlainObject(routeTo)) active.routeTo = routeTo;
+
+  let promotedTo = null;
+  if (active.status === 'verified') {
+    active.routeTo = null;
+    const next = slices.find((s) => s.status === 'blocked' && s.blockedBy === active.sliceId)
+      || slices.find((s) => s.status === 'pending' && s.sliceId !== active.sliceId);
+    if (next) {
+      if (next.status === 'blocked') next.blockedBy = null;
+      next.status = next.status === 'blocked' ? 'pending' : next.status;
+      state.sliceState.activeSliceId = next.sliceId;
+      promotedTo = next.sliceId;
+    } else {
+      // Queue drained: clear the active pointer so dispatchPacket goes null and a
+      // completed slice is never re-dispatched. Harness falls back to ring:loop.
+      state.sliceState.activeSliceId = 'none';
+    }
+  }
+
+  if (
+    active.status === 'verified'
+    || (active.status === 'failed' && active.routeTo?.role && active.routeTo?.reason)
+  ) {
+    state.sliceState.lastResolvedForStop = {
+      sliceId: active.sliceId,
+      role: String(active.role || 'developer'),
+    };
+  }
+
+  state.sliceState = normalizeSliceState(state.sliceState);
+  persistState(root, state);
+  return { state, slice: active, promotedTo };
+}
+
+/** Append a Progress Checkpoint entry programmatically. */
+export function appendCheckpoint(root, entry) {
+  const state = readState(root);
+  const at = entry.at || new Date().toISOString();
+  state.progressCheckpoint.push({
+    at,
+    by: entry.by ?? 'unknown',
+    iteration: entry.iteration ?? state.handoff.iteration,
+    loop: entry.loop ?? state.handoff.loop,
+    note: entry.note ?? '',
+  });
+  persistState(root, state);
+  return state;
+}
+
+/** Set (replace by id) a Production Pipeline wave row. */
+export function setPipelineWave(root, wave) {
+  const state = readState(root);
+  const waves = state.productionPipeline.waves;
+  const idx = waves.findIndex((w) => String(w.id) === String(wave.id));
+  if (idx >= 0) waves[idx] = { ...waves[idx], ...wave };
+  else waves.push(wave);
+  persistState(root, state);
+  return state;
+}
+
+/** Replace the File Index list. */
+export function setFileIndex(root, files) {
+  const state = readState(root);
+  state.fileIndex = Array.isArray(files) ? files : [];
+  persistState(root, state);
+  return state;
+}
+
+/** Update ringDoD entries (object merge). */
+export function setRingDoD(root, ringDoD) {
+  return writeState(root, { ringDoD });
+}
+
+/**
+ * Update programmatic validator artifact paths for a specific ring.
+ * ringArtifacts is stored as { "1": {...}, "2": {...}, ... }.
+ * @param {string} root
+ * @param {number|string} ring Ring number (1-4)
+ * @param {Record<string, string>} paths Map of artifact name → relative path
+ */
+export function setRingArtifacts(root, ring, paths) {
+  const state = readState(root);
+  const existing = state.ringArtifacts || {};
+  const key = String(ring);
+  const updated = { ...existing, [key]: { ...(existing[key] || {}), ...paths } };
+  return writeState(root, { ringArtifacts: updated });
+}
+
+/** Update ring gate runner fields (object merge). */
+export function setRingGateRunner(root, fields) {
+  return writeState(root, { ringGateRunner: fields });
+}
+
+export function advanceRing(root, { iteration, accepted = false } = {}) {
+  const state = readState(root);
+  const current = normalizeIteration(iteration ?? state.handoff?.iteration);
+  if (!accepted) {
+    throw new Error('Ring advance requires --accepted');
+  }
+  if (!current) {
+    throw new Error('Ring advance requires a valid iteration 1..4');
+  }
+  if (String(state.ringGateRunner?.ringGateCanAskUser || '').toLowerCase() !== 'yes') {
+    throw new Error('Ring advance blocked: ringGateCanAskUser is not yes — run npm run ring:gate first');
+  }
+
+  const activeKeys = ringDoDKeysForIteration(current, root);
+  if (!allDoDPassed(state.ringDoD || {}, activeKeys)) {
+    throw new Error(`Ring advance blocked: ring ${current} DoD is not fully passed`);
+  }
+
+  const archivedSnapshot = {};
+  for (const key of activeKeys) archivedSnapshot[key] = state.ringDoD[key];
+  state.archivedRings = { ...(state.archivedRings || {}), [current]: archivedSnapshot };
+  state.archivedRingContexts = {
+    ...(state.archivedRingContexts || {}),
+    [current]: normalizeHandoffContext(state.handoffContext),
+  };
+
+  if (current < 4) {
+    const next = current + 1;
+    const nextKeys = ringDoDKeysForIteration(next, root);
+    state.handoff = {
+      ...state.handoff,
+      iteration: String(next),
+      ringGoal: RING_GOALS[next],
+      loop: 'clarify',
+      subagent: 'none',
+      subagent_stop: 'false',
+      waiting_for: 'orchestrator',
+      ringGate: 'pending',
+      next_orchestrator_action: 'null',
+      last_completed_by: 'orchestrator',
+      block_reason: 'null',
+    };
+    state.ringDoD = Object.fromEntries(nextKeys.map((key) => [key, 'pending']));
+    state.handoffContext = normalizeHandoffContext({
+      ...state.handoffContext,
+      ring: {
+        summary: `Ring ${next} ready to start.`,
+        goal: RING_GOALS[next],
+        passedDoD: [],
+      },
+      lastRole: {
+        role: 'orchestrator',
+        summary: `Ring ${current} accepted; stable shared decisions carried forward.`,
+        decisions: [],
+        artifactRefs: [],
+        validation: activeKeys.map((key) => `${key}:${archivedSnapshot[key] || 'passed'}`),
+        blockers: [],
+      },
+      nextRole: {
+        role: 'orchestrator',
+        mustKnow: [
+          `Start Ring ${next} clarify from sharedDecisions; read only state:get disclosed files.`,
+        ],
+        requiredFiles: ['CLAUDE.md'],
+        forbiddenFiles: [],
+        artifactRefs: [],
+      },
+      openQuestions: [],
+    });
+    state.ringGateRunner = {
+      ringGateCurrent: 'none',
+      ringGateVerdict: 'not_run',
+      ringGateCheckedAt: 'unset',
+      ringGateBlockingIssues: '0',
+      ringGateCanAskUser: 'no',
+      ringGateRouteTo: 'none',
+      ringGateFailReason: 'none',
+      ringGateNonRegression: 'n-a',
+    };
+  } else {
+    state.handoff = {
+      ...state.handoff,
+      iteration: '4',
+      ringGoal: RING_GOALS[4],
+      loop: 'verify',
+      subagent: 'none',
+      subagent_stop: 'true',
+      waiting_for: 'none',
+      ringGate: 'passed',
+      next_orchestrator_action: 'Project workflow complete',
+      last_completed_by: 'orchestrator',
+      block_reason: 'null',
+    };
+    state.assetMappingLocked = true;
+    state.ringGateRunner = {
+      ...(state.ringGateRunner || {}),
+      ringGateCurrent: '4',
+      ringGateVerdict: 'pass',
+      ringGateCanAskUser: 'no',
+      ringGateRouteTo: 'none',
+      ringGateFailReason: 'none',
+    };
+  }
+
+  return persistState(root, state);
+}
+
+/** Flatten state.handoff + ringDoD/archivedRings into a string map for legacy readers. */
+export function flatHandoff(state) {
+  return {
+    ...state.handoff,
+    ringDoD: serializeRingDoD(state.ringDoD),
+    archivedRings: serializeArchivedRings(state.archivedRings),
+  };
+}
+
+export function serializeRingDoD(ringDoD) {
+  const pairs = Object.entries(ringDoD || {}).map(([k, v]) => `${k}: ${v}`);
+  return `{ ${pairs.join(', ')} }`;
+}
+
+export function serializeArchivedRings(archived) {
+  const entries = Object.entries(archived || {});
+  if (entries.length === 0) return '{}';
+  const body = entries
+    .map(([ring, dod]) => `${ring}: ${serializeRingDoD(dod)}`)
+    .join(', ');
+  return `{ ${body} }`;
+}