@playcraft/cli 0.1.50-beta → 0.1.51

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

@@ -1,339 +0,0 @@
-#!/usr/bin/env node
-/**
- * Read project state from docs/project-state.json.
- *
- * Outputs two views:
- *   - Orchestrator view (default): pipeline, stageExit, dispatchableRoles,
- *     canWriteTodo, todo pool summary, todosCleared, gate, recent handoff history tail.
- *   - Subagent view (--json dispatch): just state.dispatch (the workticket).
- *     Must NOT include exit/dispatchableRoles.
- *
- * Usage:
- *   npm run state:get
- *   node skills/_shared/scripts/state-get.mjs --root=. --json dispatch
- *   node skills/_shared/scripts/state-get.mjs --root=. iteration stage
- */
-
-import {
-  flatHandoff,
-  readState,
-  stateExists,
-  todosCleared,
-} from './state-store.mjs';
-import {
-  specForIteration,
-  stageConfig,
-  dispatchableRoles,
-  canWriteTodo,
-  stageExit,
-  subagentFieldsForStage,
-  STAGES,
-  dodKeysForStage,
-  dodDefinition,
-  routeForFailedDoDKeys,
-} from './pipeline/index.mjs';
-
-function parseArgs(argv) {
-  const opts = { root: process.cwd(), keys: [], json: false, jsonTarget: null };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg.startsWith('--root=')) {
-      opts.root = arg.slice('--root='.length);
-    } else if (arg === '--json') {
-      opts.json = true;
-      // Check if next arg is a target (not a flag)
-      if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
-        opts.jsonTarget = argv[++i];
-      }
-    } else if (arg === '--help' || arg === '-h') {
-      console.log('Usage: state-get.mjs [--root=.] [--json [dispatch|orchestrator]] [key ...]');
-      console.log('  --json dispatch     Emit only state.dispatch (subagent workticket)');
-      console.log('  --json              Emit full orchestrator view as JSON');
-      process.exit(0);
-    } else if (!arg.startsWith('-')) {
-      opts.keys.push(arg);
-    }
-  }
-  return opts;
-}
-
-/** Summarize todo pool for the current iteration in orchestrator view. */
-function buildTodoSummary(todos, iteration) {
-  const currentIteration = Number(iteration) || 1;
-  const all = (todos || []).filter((t) => Number(t.iteration ?? currentIteration) === currentIteration);
-  const byStatus = { pending: [], in_progress: [], done: [], failed: [] };
-  for (const t of all) {
-    const bucket = byStatus[t.status] ?? (byStatus[t.status] = []);
-    bucket.push(t.id);
-  }
-  return {
-    total: all.length,
-    pending: byStatus.pending,
-    in_progress: byStatus.in_progress,
-    done: byStatus.done,
-    failed: byStatus.failed,
-    contextReuse: all
-      .filter((t) => t.contextReuse)
-      .map((t) => ({
-        id: t.id,
-        status: t.status,
-        key: t.contextReuse || '',
-      })),
-  };
-}
-
-function buildContextReuseHint(todos, iteration, stage, handoff) {
-  if (stage !== 'generate') return null;
-
-  const currentIteration = Number(iteration) || 1;
-  const all = (todos || []).filter((t) => Number(t.iteration ?? currentIteration) === currentIteration);
-  const nextPendingIndex = all.findIndex((t) => t.status === 'pending');
-  if (nextPendingIndex < 0) return null;
-
-  const candidate = all[nextPendingIndex];
-  const previous = nextPendingIndex > 0 ? all[nextPendingIndex - 1] : null;
-  const limit = 3;
-  const recent = handoff?.history?.length ? handoff.history[handoff.history.length - 1] : null;
-  const blockers = Array.isArray(recent?.blockers) ? recent.blockers : [];
-
-  const base = {
-    nextTodoId: candidate.id,
-    reusable: Boolean(candidate.contextReuse),
-    key: candidate.contextReuse || '',
-    limit,
-    eligibleForSendMessage: false,
-    reason: '',
-  };
-
-  if (!candidate.contextReuse) return { ...base, reason: 'next todo has no contextReuse' };
-  if (!previous) return { ...base, reason: 'next todo has no previous contiguous todo' };
-  if (previous.status !== 'done') return { ...base, reason: 'previous contiguous todo is not done' };
-  if (!previous.contextReuse || previous.contextReuse !== candidate.contextReuse) {
-    return { ...base, reason: 'previous contiguous todo has different reuse key' };
-  }
-  if (!recent) return { ...base, reason: 'no latest handoff to resume with sendMessage' };
-  if (recent.role !== candidate.role) {
-    return { ...base, reason: 'latest handoff role does not match next todo role' };
-  }
-  if (blockers.length > 0) return { ...base, reason: 'latest handoff has blockers' };
-
-  let contiguousCount = 1;
-  for (let idx = nextPendingIndex - 1; idx >= 0; idx -= 1) {
-    const todo = all[idx];
-    if (
-      todo.status !== 'done'
-      || !todo.contextReuse
-      || todo.contextReuse !== candidate.contextReuse
-      || todo.role !== candidate.role
-    ) {
-      break;
-    }
-    contiguousCount += 1;
-  }
-
-  if (contiguousCount > limit) {
-    return {
-      ...base,
-      contiguousCount,
-      reason: `contiguous reusable run ${contiguousCount} exceeds limit ${limit}`,
-    };
-  }
-
-  return {
-    ...base,
-    contiguousCount,
-    previousTodoId: previous.id,
-    eligibleForSendMessage: true,
-    reason: 'same role, contiguous done todo, same reuse key, within limit, no blocker',
-  };
-}
-
-function isRealTodoId(id) {
-  return id && id !== 'none' && !id.startsWith('stage:');
-}
-
-function findTodoForDispatch(state) {
-  const id = state.dispatch?.activeTodoId;
-  if (!isRealTodoId(id)) return null;
-  return (state.todos || []).find((t) => t.id === id && t.iteration === state.pipeline.iteration)
-    ?? (state.todos || []).find((t) => t.id === id)
-    ?? null;
-}
-
-function buildDispatchView(state) {
-  const dispatch = state.dispatch || {};
-  const todo = findTodoForDispatch(state);
-  if (!todo) return dispatch;
-
-  return {
-    activeTodoId: dispatch.activeTodoId || todo.id,
-    role: dispatch.role || todo.role,
-    title: todo.title || todo.id,
-    goal: dispatch.goal || todo.goal || todo.title || '',
-    context: todo.context || '',
-    guidance: dispatch.guidance || '',
-    skillHints: dispatch.skillHints || [],
-    requiredContext: dispatch.requiredContext?.length ? dispatch.requiredContext : todo.requiredContext || [],
-    contextReuse: dispatch.contextReuse || todo.contextReuse || '',
-    allowedFiles: dispatch.allowedFiles || [],
-    forbiddenTasks: dispatch.forbiddenTasks || [],
-    acceptance: dispatch.acceptance?.length ? dispatch.acceptance : todo.acceptance || [],
-    verifier: dispatch.verifier || todo.verifier || '',
-  };
-}
-
-function omitEmptyDispatchFields(dispatch) {
-  const out = {};
-  for (const [key, value] of Object.entries(dispatch || {})) {
-    if (value === '') continue;
-    if (Array.isArray(value) && value.length === 0) continue;
-    out[key] = value;
-  }
-  return out;
-}
-
-/** Build stageDod summary for orchestrator view. */
-function buildStageDod(iteration, stage, stageDoD) {
-  const keys = dodKeysForStage(iteration, stage);
-  if (!keys.length) return null;
-
-  const current = stageDoD || {};
-  const pending = keys.filter((k) => !current[k]);
-  const passed = keys.filter((k) => current[k] === true || current[k] === 'passed' || current[k] === 'pass');
-  const failed = keys.filter((k) => current[k] === false || current[k] === 'failed' || current[k] === 'fail');
-
-  const scripts = {};
-  const routing = {};
-  for (const k of keys) {
-    const def = dodDefinition(k);
-    if (def?.script) scripts[k] = def.script;
-    routing[k] = { routeTo: def?.routeTo ?? 'developer', nextAction: def?.nextAction ?? '' };
-  }
-
-  const failRoute = failed.length ? routeForFailedDoDKeys(failed) : null;
-
-  return { keys, scripts, pending, passed, failed, routing, failRoute };
-}
-
-function buildOrchestratorAction(dispatch, pendingUserInput) {
-  if (
-    dispatch?.activeTodoId
-    && dispatch.activeTodoId !== 'none'
-    && pendingUserInput?.status === 'awaiting_user_input'
-  ) {
-    return 'ask_user_then_sendMessage_to_active_subagent';
-  }
-  if (
-    dispatch?.activeTodoId
-    && dispatch.activeTodoId !== 'none'
-    && pendingUserInput?.status === 'answered'
-  ) {
-    return 'sendMessage_answer_to_active_subagent';
-  }
-  if (dispatch?.activeTodoId && dispatch.activeTodoId !== 'none') {
-    return 'resume_active_dispatch';
-  }
-  return 'select_next_dispatch_or_stage_action';
-}
-
-/** Build orchestrator view. */
-function buildOrchestratorView(state) {
-  const { pipeline, todos, gate, handoff, dispatch, devPreview } = state;
-  const iteration = pipeline.iteration;
-  const stage = pipeline.stage;
-
-  const exitStr = stageExit(iteration, stage);
-  const roles = dispatchableRoles(iteration, stage);
-  const todoWriteRoles = canWriteTodo(iteration, stage);
-  const cleared = todosCleared(state);
-  const todoSummary = buildTodoSummary(todos, iteration);
-
-  // recent handoff history tail (last 3)
-  const history = handoff.history || [];
-  const recentHistory = history.slice(-3).map((e) => ({
-    seq: e.seq,
-    role: e.role,
-    stage: e.stage,
-    status: e.status,
-    summary: e.summary,
-    artifactRefs: e.artifactRefs,
-    pendingUserInput: e.pendingUserInput?.status && e.pendingUserInput.status !== 'none'
-      ? e.pendingUserInput
-      : null,
-  }));
-
-  return {
-    // 主线指针
-    pipeline: {
-      iteration: pipeline.iteration,
-      stage: pipeline.stage,
-      stageStatus: pipeline.stageStatus,
-      userConfirm: pipeline.userConfirm,
-    },
-    // 退出条件(只给调度者,不给 subagent)
-    stageExit: exitStr,
-    // 调度者可派角色
-    dispatchableRoles: roles,
-    // todo 写权限角色
-    canWriteTodo: todoWriteRoles,
-    // todo 池摘要
-    todoPool: todoSummary,
-    todosCleared: cleared,
-    // 闸门
-    gate: gate,
-    // 用户输入等待态:dispatch 仍 active,调度者问用户后用 sendMessage 恢复同一个 subagent
-    pendingUserInput: handoff.pendingUserInput || null,
-    orchestratorAction: buildOrchestratorAction(dispatch, handoff.pendingUserInput),
-    contextReuseHint: buildContextReuseHint(todos, iteration, stage, handoff),
-    // 最近 handoff 轨
-    recentHandoffHistory: recentHistory,
-    // 共享决策
-    sharedDecisions: handoff.sharedDecisions || {},
-    // dev server 状态
-    devStatus: devPreview?.devStatus ?? null,
-    devUrl: devPreview?.devUrl ?? null,
-    loadCheck: devPreview?.loadCheck ?? null,
-    // 当前 dispatch(调度者写的工单摘要)
-    activeTodoId: dispatch?.activeTodoId ?? 'none',
-    dispatchedRole: dispatch?.role ?? '',
-    // DoD 检查（只在有定义的阶段非 null）
-    stageDod: buildStageDod(iteration, stage, gate?.stageDoD),
-  };
-}
-
-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);
-
-  // Subagent dispatch view: only state.dispatch, nothing else
-  if (opts.jsonTarget === 'dispatch' || (opts.json && opts.jsonTarget === 'dispatch')) {
-    console.log(JSON.stringify(omitEmptyDispatchFields(buildDispatchView(state)), null, 2));
-    return;
-  }
-
-  const view = buildOrchestratorView(state);
-
-  if (opts.json) {
-    // Full JSON orchestrator view, optionally filtered by keys
-    const keys = opts.keys.length > 0 ? opts.keys : Object.keys(view);
-    const out = {};
-    for (const key of keys) {
-      out[key] = view[key] ?? null;
-    }
-    console.log(JSON.stringify(out, null, 2));
-    return;
-  }
-
-  // Text output
-  const keys = opts.keys.length > 0 ? opts.keys : Object.keys(view);
-  for (const key of keys) {
-    const value = view[key];
-    console.log(`${key}: ${typeof value === 'string' ? value : JSON.stringify(value)}`);
-  }
-}
-
-main();

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

@@ -1,39 +0,0 @@
-/**
- * state-handoff — thin façade over state-store for hooks/callers that only need
- * the flat handoff map.
- *
- * Process backing file is docs/project-state.json; the md is a rendered, read-only
- * view. Hooks read state via flatHandoff; they never parse the md. This module
- * exists so read-only hooks and dev-start can import a stable, store-backed API
- * instead of touching state-store internals directly.
- */
-
-import path from 'node:path';
-import { applyStateUpdates, flatHandoff, readState } from './state-store.mjs';
-
-export function resolveProjectStatePath(root) {
-  return path.join(path.resolve(root), 'docs/project-state.md');
-}
-
-/** 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 updates through the store (JSON truth + rendered md).
- * Takes the md path; resolves the project root from it internally.
- * @param {string} statePath path to docs/project-state.md
- * @param {Record<string, string>} updates
- * @returns {object} flattened handoff view
- */
-export function applyHandoffUpdates(statePath, updates) {
-  const state = applyStateUpdates(rootFromStatePath(statePath), updates);
-  return flatHandoff(state);
-}
-
-/** Read the flat handoff view (pipeline+dispatch+todos+gate) for a project root. */
-export function readHandoffForRoot(root) {
-  return flatHandoff(readState(root));
-}

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

@@ -1,94 +0,0 @@
-#!/usr/bin/env node
-/**
- * Update project state without hand-editing markdown.
- *
- * Writes into docs/project-state.json (process backing file) and re-renders
- * docs/project-state.md. Keys are routed to the right section automatically.
- *
- * Usage:
- *   npm run state:set -- stage=generate stageStatus=in_progress
- *   npm run state:set -- devStatus=ready
- *   npm run state:set -- canAskUser=yes
- *   npm run state:set -- pipelinePatch='{"userConfirm":"confirmed"}'
- *   npm run state:set -- dispatchPatch='{"role":"developer","goal":"..."}'
- *   node skills/_shared/scripts/state-set.mjs --root=. key=value [...]
- *
- * Flat keys:
- *   iteration, stage, stageStatus, userConfirm → pipeline.*
- *   canAskUser → gate.canAskUser
- *   devPreview keys (devStatus, devUrl, loadCheck, etc.)
- *   userIntent
- * JSON-patch keys (merge):
- *   pipelinePatch, dispatchPatch, handoffPatch, pendingUserInputPatch,
- *   sharedDecisionsPatch, gatePatch
- * Array-replace key:
- *   todosPatch (JSON array)
- */
-
-import {
-  applyStateUpdates,
-  readState,
-} from './state-store.mjs';
-
-function parseArgs(argv) {
-  const opts = { root: process.cwd(), pairs: [] };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg.startsWith('--root=')) {
-      opts.root = arg.slice('--root='.length);
-    } else if (arg === '--help' || arg === '-h') {
-      console.log('Usage: state-set.mjs [--root=.] key=value [...]');
-      console.log('Flat keys: iteration, stage, stageStatus, userConfirm, canAskUser, userIntent, devStatus, devUrl, loadCheck, ...');
-      console.log('JSON-patch keys: pipelinePatch, dispatchPatch, handoffPatch, pendingUserInputPatch, sharedDecisionsPatch, gatePatch, todosPatch');
-      process.exit(0);
-    } else if (arg.includes('=')) {
-      const eq = arg.indexOf('=');
-      opts.pairs.push({ key: arg.slice(0, eq), value: arg.slice(eq + 1) });
-    }
-  }
-  return opts;
-}
-
-function flattenForPrint(state) {
-  return {
-    // pipeline fields
-    iteration: state.pipeline?.iteration,
-    stage: state.pipeline?.stage,
-    stageStatus: state.pipeline?.stageStatus,
-    userConfirm: state.pipeline?.userConfirm,
-    // gate
-    canAskUser: state.gate?.canAskUser,
-    // top-level
-    userIntent: state.userIntent,
-    // devPreview
-    ...state.devPreview,
-    devBlockers: JSON.stringify(state.devPreview?.devBlockers ?? []),
-    // dispatch summary
-    dispatch: JSON.stringify(state.dispatch || {}),
-    pendingUserInput: JSON.stringify(state.handoff?.pendingUserInput || {}),
-    pendingUserInputPatch: JSON.stringify(state.handoff?.pendingUserInput || {}),
-  };
-}
-
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-
-  if (opts.pairs.length === 0) {
-    console.error('Nothing to set. Example: npm run state:set -- stage=generate');
-    process.exit(1);
-  }
-
-  const updates = {};
-  for (const { key, value } of opts.pairs) {
-    updates[key] = value;
-  }
-  applyStateUpdates(opts.root, updates);
-
-  const printable = flattenForPrint(readState(opts.root));
-  for (const { key } of opts.pairs) {
-    const v = printable[key];
-    console.log(`${key}: ${v != null ? v : ''}`);
-  }
-}
-
-main();