@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/skills/_shared/scripts/state-store.mjs

@@ -0,0 +1,783 @@
+/**
+ * Single read/write layer over docs/project-state.json — the process backing
+ * file 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` / STOP hooks — they never hand-edit the markdown.
+ *
+ * Schema: pipeline + dispatch + todos + handoff(history/pendingUserInput/sharedDecisions) + gate + devPreview
+ * See docs/harness/pipeline-design.md §4.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { STAGES, nextStage, MAX_ITERATION, dodKeysForStage } from './pipeline/index.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_LOCK_REL = 'docs/.project-state.lock';
+export const STATE_SCHEMA_VERSION = 3;
+const STATE_LOCK_TIMEOUT_MS = 10000;
+const STATE_LOCK_STALE_MS = 30000;
+const STATE_LOCK_RETRY_MS = 25;
+const SLEEP_BUFFER = new SharedArrayBuffer(4);
+const SLEEP_VIEW = new Int32Array(SLEEP_BUFFER);
+
+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);
+}
+
+export function resolveStateLockPath(root) {
+  return path.join(path.resolve(root), STATE_LOCK_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',
+]);
+
+// ── Default shapes ────────────────────────────────────────────────────────
+
+/** Return the default state object. */
+export function defaultState() {
+  return {
+    schemaVersion: STATE_SCHEMA_VERSION,
+    specVersion: 'pipeline',
+    userIntent: '',
+    settings: {},
+    pipeline: {
+      iteration: 1,
+      stage: 'ideate',
+      stageStatus: 'pending',
+      userConfirm: 'pending',
+    },
+    dispatch: {
+      activeTodoId: 'none',
+      role: '',
+      goal: '',
+      guidance: '',
+      skillHints: [],
+      requiredContext: [],
+      contextReuse: '',
+      allowedFiles: [],
+      forbiddenTasks: [],
+      acceptance: [],
+      verifier: '',
+    },
+    todos: [],
+    handoff: {
+      history: [],
+      pendingUserInput: {
+        status: 'none',
+        id: '',
+        requestedBy: '',
+        prompt: '',
+        options: [],
+        recommended: '',
+        impact: '',
+        answer: '',
+        answeredAt: '',
+      },
+      sharedDecisions: {
+        engine: 'unset',
+        coreAction: 'unset',
+      },
+    },
+    gate: {
+      stageDoD: {},
+      canAskUser: 'no',
+    },
+    devPreview: {
+      devStatus: 'pending',
+      devUrl: 'unset',
+      devStartedBy: 'none',
+      devLastChecked: 'unset',
+      loadCheck: 'pending',
+      loadCheckNotes: 'unset',
+      uiReviewStatus: 'deferred',
+      uiDiffNotes: 'deferred',
+      uiReworkRound: '0',
+      devBlockers: [],
+    },
+  };
+}
+
+/** A single todo's default shape. */
+export function defaultTodo() {
+  return {
+    id: '',
+    iteration: 1,
+    stage: '',
+    role: 'developer',
+    title: '',
+    goal: '',
+    context: '',
+    requiredContext: [],
+    contextReuse: '',
+    acceptance: [],
+    verifier: '',
+    createdBy: '',
+    status: 'pending',
+  };
+}
+
+// ── Utility helpers ──────────────────────────────────────────────────────────
+
+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 normalizeText(value) {
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean).join('\n');
+  if (isPlainObject(value)) return JSON.stringify(value, null, 2);
+  return String(value ?? '').trim();
+}
+
+function parseBoolean(value) {
+  if (typeof value === 'boolean') return value;
+  const raw = String(value ?? '').trim().toLowerCase();
+  if (!raw) return false;
+  return ['1', 'true', 'yes', 'y', 'on'].includes(raw);
+}
+
+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 sleepSync(ms) {
+  Atomics.wait(SLEEP_VIEW, 0, 0, ms);
+}
+
+function removeStaleLock(lockPath) {
+  try {
+    const stat = fs.statSync(lockPath);
+    if (Date.now() - stat.mtimeMs > STATE_LOCK_STALE_MS) {
+      fs.rmSync(lockPath, { recursive: true, force: true });
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+export function withStateLock(root, fn, { timeoutMs = STATE_LOCK_TIMEOUT_MS } = {}) {
+  const lockPath = resolveStateLockPath(root);
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  const startedAt = Date.now();
+  let acquired = false;
+
+  while (!acquired) {
+    try {
+      fs.mkdirSync(lockPath);
+      acquired = true;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      removeStaleLock(lockPath);
+      if (Date.now() - startedAt > timeoutMs) {
+        throw new Error(`Timed out waiting for project state lock: ${lockPath}`);
+      }
+      sleepSync(STATE_LOCK_RETRY_MS);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    fs.rmSync(lockPath, { recursive: true, force: true });
+  }
+}
+
+function atomicWriteFile(filePath, contents) {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const tmpPath = path.join(
+    dir,
+    `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`,
+  );
+  fs.writeFileSync(tmpPath, contents, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+/** 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 handoff block. */
+function normalizeHandoff(handoff) {
+  const base = defaultState().handoff;
+  const merged = isPlainObject(handoff) ? { ...base, ...handoff } : base;
+  if (!Array.isArray(merged.history)) merged.history = [];
+  if (!isPlainObject(merged.sharedDecisions)) merged.sharedDecisions = { engine: 'unset', coreAction: 'unset' };
+  merged.pendingUserInput = normalizePendingUserInput(merged.pendingUserInput);
+  // normalize each history entry
+  merged.history = merged.history.map((entry, idx) => ({
+    seq: entry.seq ?? idx + 1,
+    iteration: entry.iteration ?? 1,
+    stage: entry.stage ?? 'ideate',
+    role: entry.role ?? '',
+    status: entry.status ?? 'completed',
+    summary: entry.summary ?? '',
+    artifactRefs: parseStringList(entry.artifactRefs),
+    acceptanceResults: Array.isArray(entry.acceptanceResults) ? entry.acceptanceResults : [],
+    blockers: parseStringList(entry.blockers),
+    pendingUserInput: normalizePendingUserInput(entry.pendingUserInput),
+  }));
+  return merged;
+}
+
+function normalizePendingUserInput(input) {
+  const base = defaultState().handoff.pendingUserInput;
+  const merged = isPlainObject(input) ? { ...base, ...input } : base;
+  const validStatuses = new Set(['none', 'awaiting_user_input', 'answered', 'resolved']);
+  merged.status = validStatuses.has(String(merged.status)) ? String(merged.status) : 'none';
+  merged.id = String(merged.id || '');
+  merged.requestedBy = String(merged.requestedBy || '');
+  merged.prompt = String(merged.prompt || '');
+  merged.options = Array.isArray(merged.options)
+    ? merged.options.map((option) => {
+      if (isPlainObject(option)) {
+        return {
+          label: String(option.label || ''),
+          description: String(option.description || ''),
+        };
+      }
+      return { label: String(option || ''), description: '' };
+    }).filter((option) => option.label)
+    : [];
+  merged.recommended = String(merged.recommended || '');
+  merged.impact = String(merged.impact || '');
+  merged.answer = String(merged.answer || '');
+  merged.answeredAt = String(merged.answeredAt || '');
+  return merged;
+}
+
+/** Normalize todos array. */
+function normalizeTodos(todos, pipeline = {}) {
+  if (!Array.isArray(todos)) return [];
+  const validStatuses = new Set(['pending', 'in_progress', 'done', 'failed']);
+  const fallbackIteration = Number(pipeline.iteration) || 1;
+  const fallbackStage = String(pipeline.stage || '');
+  return todos
+    .filter((t) => isPlainObject(t) && String(t.id || '').trim())
+    .map((t) => {
+      const todo = { ...defaultTodo(), ...t };
+      todo.id = String(todo.id).trim();
+      todo.iteration = Number.parseInt(String(todo.iteration ?? fallbackIteration), 10) || fallbackIteration;
+      todo.stage = String(todo.stage || fallbackStage);
+      todo.title = normalizeText(todo.title || t.doWhat || t.goal || todo.id);
+      todo.goal = normalizeText(todo.goal || t.doWhat || todo.title);
+      todo.context = normalizeText(todo.context);
+      todo.requiredContext = parseStringList(todo.requiredContext);
+      todo.contextReuse = normalizeText(
+        todo.contextReuse
+        || todo.contextReuseKey
+        || (parseBoolean(todo.contextReusable) ? 'shared' : ''),
+      );
+      todo.acceptance = parseStringList(todo.acceptance);
+      if (!validStatuses.has(String(todo.status))) todo.status = 'pending';
+      delete todo.doWhat;
+      delete todo.contextReusable;
+      delete todo.contextReuseKey;
+      delete todo.contextReuseLimit;
+      delete todo.contextReuseNotes;
+      delete todo.deltaContext;
+      delete todo.artifactRefs;
+      return todo;
+    });
+}
+
+/** Normalize dispatch block. */
+function normalizeDispatch(dispatch) {
+  const base = defaultState().dispatch;
+  const merged = isPlainObject(dispatch) ? { ...base, ...dispatch } : base;
+  merged.skillHints = parseStringList(merged.skillHints);
+  merged.requiredContext = parseStringList(merged.requiredContext);
+  merged.contextReuse = normalizeText(
+    merged.contextReuse
+    || merged.contextReuseKey
+    || (parseBoolean(merged.contextReusable) ? 'shared' : ''),
+  );
+  merged.allowedFiles = parseStringList(merged.allowedFiles);
+  merged.forbiddenTasks = parseStringList(merged.forbiddenTasks);
+  merged.acceptance = parseStringList(merged.acceptance);
+  if (!merged.activeTodoId) merged.activeTodoId = 'none';
+  delete merged.contextReusable;
+  delete merged.contextReuseKey;
+  delete merged.contextReuseLimit;
+  delete merged.contextReuseNotes;
+  delete merged.deltaContext;
+  delete merged.artifacts;
+  delete merged.artifactRule;
+  return merged;
+}
+
+/** Normalize a freshly-parsed JSON state to the full default shape. */
+export function normalizeState(raw) {
+  const state = mergeState(defaultState(), raw || {});
+  state.schemaVersion = STATE_SCHEMA_VERSION;
+  state.handoff = normalizeHandoff(state.handoff);
+  state.todos = normalizeTodos(state.todos, state.pipeline);
+  state.dispatch = normalizeDispatch(state.dispatch);
+  if (!Array.isArray(state.devPreview.devBlockers)) {
+    state.devPreview.devBlockers = normalizeDevBlockers(state.devPreview.devBlockers);
+  }
+  return state;
+}
+
+// ── Read / write ─────────────────────────────────────────────────────────────
+
+/**
+ * Read the project state from docs/project-state.json (the process backing file).
+ * Returns defaults when the file is absent or unparseable. The .md is a
+ * generated view and is never read back.
+ * @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 {
+      /* unparseable — fall back to defaults */
+    }
+  }
+  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 });
+  atomicWriteFile(jsonPath, `${JSON.stringify(state, null, 2)}\n`);
+  try {
+    atomicWriteFile(resolveStateMdPath(root), renderProjectState(state));
+  } 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) {
+  return withStateLock(root, () => {
+    const next = mergeState(readState(root), patch || {});
+    return persistState(root, next);
+  });
+}
+
+// ── Structured mutators ───────────────────────────────────────────────────
+
+/**
+ * Push a todo into the pool. Assigns id if missing. Persists state.
+ * @param {string} root
+ * @param {object} todo
+ */
+export function addTodo(root, todo) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    const merged = { ...defaultTodo(), ...todo };
+    if (!merged.id) merged.id = `todo-${Date.now()}`;
+    merged.iteration = Number.parseInt(String(merged.iteration ?? state.pipeline.iteration), 10) || state.pipeline.iteration;
+    merged.stage = String(merged.stage || state.pipeline.stage || '');
+    merged.title = normalizeText(merged.title || todo.doWhat || merged.goal || merged.id);
+    merged.goal = normalizeText(merged.goal || todo.doWhat || merged.title);
+    merged.context = normalizeText(merged.context);
+    merged.requiredContext = parseStringList(merged.requiredContext);
+    merged.contextReuse = normalizeText(
+      merged.contextReuse
+      || todo.contextReuseKey
+      || (parseBoolean(todo.contextReusable) ? 'shared' : ''),
+    );
+    merged.acceptance = parseStringList(merged.acceptance);
+    if (!merged.status) merged.status = 'pending';
+    delete merged.doWhat;
+    delete merged.contextReusable;
+    delete merged.contextReuseKey;
+    delete merged.contextReuseLimit;
+    delete merged.contextReuseNotes;
+    delete merged.deltaContext;
+    delete merged.artifactRefs;
+    state.todos.push(merged);
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Remove a todo by id. Persists state.
+ * @param {string} root
+ * @param {string} id
+ */
+export function removeTodo(root, id) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    const hasCurrentIterationMatch = state.todos.some((t) => (
+      t.id === id && t.iteration === state.pipeline.iteration
+    ));
+    state.todos = state.todos.filter((t) => {
+      if (t.id !== id) return true;
+      return hasCurrentIterationMatch && t.iteration !== state.pipeline.iteration;
+    });
+    return persistState(root, state);
+  });
+}
+
+function findTodoForCurrentIteration(state, id) {
+  return state.todos.find((t) => t.id === id && t.iteration === state.pipeline.iteration)
+    ?? state.todos.find((t) => t.id === id);
+}
+
+function patchTodoState(todo, { status } = {}) {
+  if (status) todo.status = status;
+}
+
+/**
+ * Set status on a todo. No auto-promotion — 調度者 decides next.
+ * @param {string} root
+ * @param {string} id
+ * @param {{ status?: string }} patch
+ */
+export function markTodoState(root, id, { status } = {}) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    const todo = findTodoForCurrentIteration(state, id);
+    if (!todo) throw new Error(`todo "${id}" not found`);
+    patchTodoState(todo, { status });
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Append a handoff entry to handoff.history (append-only).
+ * Auto-increments seq. Persists state.
+ * @param {string} root
+ * @param {object} entry
+ */
+export function appendHandoff(root, entry) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    const history = state.handoff.history;
+    const seq = history.length > 0 ? history[history.length - 1].seq + 1 : 1;
+    let pendingUserInput = normalizePendingUserInput(entry.pendingUserInput);
+    const status = entry.status ?? (
+      pendingUserInput.status === 'awaiting_user_input' ? 'awaiting_user_input' : 'completed'
+    );
+    if (status === 'awaiting_user_input' && pendingUserInput.status === 'none') {
+      pendingUserInput = normalizePendingUserInput({
+        ...pendingUserInput,
+        status: 'awaiting_user_input',
+      });
+    }
+    const nextEntry = {
+      seq,
+      iteration: entry.iteration ?? state.pipeline.iteration,
+      stage: entry.stage ?? state.pipeline.stage,
+      role: entry.role ?? '',
+      status,
+      summary: entry.summary ?? '',
+      artifactRefs: parseStringList(entry.artifactRefs),
+      acceptanceResults: Array.isArray(entry.acceptanceResults) ? entry.acceptanceResults : [],
+      blockers: parseStringList(entry.blockers),
+      pendingUserInput,
+    };
+    history.push(nextEntry);
+    if (pendingUserInput.status !== 'none') {
+      state.handoff.pendingUserInput = {
+        ...pendingUserInput,
+        requestedBy: pendingUserInput.requestedBy || nextEntry.role,
+      };
+    }
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Merge patch into handoff.sharedDecisions (just-in-place update, not append).
+ * @param {string} root
+ * @param {object} patch
+ */
+export function setSharedDecisions(root, patch) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    state.handoff.sharedDecisions = { ...(state.handoff.sharedDecisions || {}), ...patch };
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Replace state.dispatch (the subagent's workticket). Persists state.
+ * @param {string} root
+ * @param {object} dispatch
+ */
+export function setDispatch(root, dispatch) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    state.dispatch = normalizeDispatch({ ...defaultState().dispatch, ...dispatch });
+    return persistState(root, state);
+  });
+}
+
+export function setDispatchAndMarkTodoState(root, dispatch, id, todoPatch = {}) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    state.dispatch = normalizeDispatch({ ...defaultState().dispatch, ...dispatch });
+    const todo = findTodoForCurrentIteration(state, id);
+    if (!todo) throw new Error(`todo "${id}" not found`);
+    patchTodoState(todo, todoPatch);
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Clear state.dispatch back to its default empty workticket. Persists state.
+ * @param {string} root
+ */
+export function clearDispatch(root) {
+  return withStateLock(root, () => {
+    const state = readState(root);
+    state.dispatch = defaultState().dispatch;
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Returns true when every todo for the current iteration is done.
+ * Failed todos are not cleared; they must be fixed, removed, or converted into
+ * explicit follow-up work before the iteration can close.
+ * @param {object} state
+ */
+export function todosCleared(state) {
+  const iteration = Number(state.pipeline?.iteration) || 1;
+  return (state.todos || [])
+    .filter((t) => Number(t.iteration ?? iteration) === iteration)
+    .every((t) => t.status === 'done');
+}
+
+function currentIterationTodos(state) {
+  const iteration = Number(state.pipeline?.iteration) || 1;
+  return (state.todos || []).filter((t) => Number(t.iteration ?? iteration) === iteration);
+}
+
+function isPassed(value) {
+  return value === true || value === 'passed' || value === 'pass';
+}
+
+function currentStageDodPassed(state) {
+  const { iteration, stage } = state.pipeline;
+  const keys = dodKeysForStage(iteration, stage);
+  if (!keys.length) return true;
+  const stageDoD = state.gate?.stageDoD || {};
+  return keys.every((key) => isPassed(stageDoD[key]));
+}
+
+/**
+ * Advance pipeline.stage along STAGES from ./pipeline/index.mjs.
+ * - When advancing past 'wrapup', increments iteration and resets stage to 'ideate'.
+ * - Guards stage exits with the hard project gates documented in docs/harness.
+ * - Resets dispatch.activeTodoId to 'none' on stage change.
+ * @param {string} root
+ * @param {{ accepted?: boolean }} opts
+ */
+export function advanceStage(root, { accepted = false } = {}) {
+  if (!accepted) throw new Error('advanceStage requires accepted=true');
+  return withStateLock(root, () => {
+    const state = readState(root);
+    const { iteration, stage } = state.pipeline;
+
+    if (state.dispatch?.activeTodoId && state.dispatch.activeTodoId !== 'none') {
+      throw new Error(`Cannot advance past "${stage}": active dispatch "${state.dispatch.activeTodoId}" must be cleared first`);
+    }
+
+    if (stage === 'ideate' && state.pipeline.userConfirm !== 'confirmed') {
+      throw new Error('Cannot advance past "ideate": userConfirm must be confirmed');
+    }
+
+    if (stage === 'context' && currentIterationTodos(state).length === 0) {
+      throw new Error('Cannot advance past "context": current iteration todo pool is empty');
+    }
+
+    // 硬约束:generate→optimize 与 wrapup→next-iteration 前 todo 池必须清空
+    const guardedTransitions = new Set(['generate', 'wrapup']);
+    if (guardedTransitions.has(stage) && !todosCleared(state)) {
+      throw new Error(
+        `Cannot advance past "${stage}": current iteration has todos that are not done`,
+      );
+    }
+
+    if (stage === 'optimize' && !currentStageDodPassed(state)) {
+      throw new Error('Cannot advance past "optimize": current stage DoD keys are not all passed');
+    }
+
+    const next = nextStage(stage);
+    if (next) {
+      // 同迭代内推进
+      state.pipeline.stage = next;
+      state.pipeline.stageStatus = 'pending';
+      state.pipeline.userConfirm = 'pending';
+    } else {
+      // wrapup → 下一迭代 ideate
+      const nextIteration = iteration + 1;
+      if (nextIteration > MAX_ITERATION) {
+        throw new Error(`Already on the last iteration (${MAX_ITERATION}); no further iteration to advance to`);
+      }
+      state.pipeline.iteration = nextIteration;
+      state.pipeline.stage = 'ideate';
+      state.pipeline.stageStatus = 'pending';
+      state.pipeline.userConfirm = 'pending';
+    }
+
+    // 阶段切换时清空 dispatch,避免旧 role 让主会话误判仍有 active dispatch.
+    state.dispatch = defaultState().dispatch;
+
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Apply flat key/value updates, routing by key to the right section.
+ * Flat keys: iteration, stage, stageStatus, userConfirm → pipeline.*;
+ *            canAskUser → gate.canAskUser;
+ *            devPreview keys;
+ *            userIntent.
+ * JSON-patch keys: dispatchPatch, todosPatch, handoffPatch, pendingUserInputPatch,
+ *                  sharedDecisionsPatch, gatePatch, pipelinePatch.
+ * @param {string} root
+ * @param {object} updates map of key → raw string value
+ */
+export function applyStateUpdates(root, updates) {
+  return withStateLock(root, () => {
+    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 (key === 'userIntent') {
+        state.userIntent = value;
+      } else if (key === 'iteration') {
+        state.pipeline.iteration = Number.parseInt(value, 10) || state.pipeline.iteration;
+      } else if (key === 'stage') {
+        state.pipeline.stage = value;
+      } else if (key === 'stageStatus') {
+        state.pipeline.stageStatus = value;
+      } else if (key === 'userConfirm') {
+        state.pipeline.userConfirm = value;
+      } else if (key === 'canAskUser') {
+        state.gate.canAskUser = value;
+      } else if (key === 'pipelinePatch') {
+        state.pipeline = mergeState(state.pipeline, parseJsonObject(value, key));
+      } else if (key === 'dispatchPatch') {
+        state.dispatch = normalizeDispatch(mergeState(state.dispatch, parseJsonObject(value, key)));
+      } else if (key === 'todosPatch') {
+        // todosPatch replaces the full array (pass a JSON array)
+        const parsed = JSON.parse(value);
+        state.todos = normalizeTodos(Array.isArray(parsed) ? parsed : [parsed], state.pipeline);
+      } else if (key === 'handoffPatch') {
+        state.handoff = normalizeHandoff(mergeState(state.handoff, parseJsonObject(value, key)));
+      } else if (key === 'pendingUserInputPatch') {
+        state.handoff.pendingUserInput = normalizePendingUserInput(
+          mergeState(state.handoff.pendingUserInput || {}, parseJsonObject(value, key)),
+        );
+      } else if (key === 'sharedDecisionsPatch') {
+        state.handoff.sharedDecisions = {
+          ...(state.handoff.sharedDecisions || {}),
+          ...parseJsonObject(value, key),
+        };
+      } else if (key === 'gatePatch') {
+        state.gate = mergeState(state.gate, parseJsonObject(value, key));
+      } else {
+        // unknown key: silently ignore (don't crash)
+        // eslint-disable-next-line no-console
+        process.stderr.write(`[state:set] unknown key "${key}" — ignored\n`);
+      }
+    }
+    return persistState(root, state);
+  });
+}
+
+/**
+ * Flatten pipeline + dispatch into a flat map for state-get orchestrator view.
+ * @param {object} state
+ */
+export function flatHandoff(state) {
+  return {
+    ...(state.pipeline || {}),
+    dispatch: state.dispatch || {},
+    todos: state.todos || [],
+    handoff: state.handoff || {},
+    gate: state.gate || {},
+  };
+}