@playcraft/cli 0.1.33 → 0.1.35-prod

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

@@ -1,783 +0,0 @@
-/**
- * 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 || {},
-  };
-}