cc-devflow 4.5.2 → 4.5.4

package/lib/skill-runtime/errors.js

@@ -0,0 +1,39 @@
+/**
+ * [INPUT]: 接收 runtime/query/compiler 边界抛出的错误或失败字段。
+ * [OUTPUT]: 生成可序列化 named error，保留 artifact refs 与 rescue action。
+ * [POS]: skill runtime 的失败语义层，避免用 null/false/string 表达可恢复失败。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+class SkillRuntimeError extends Error {
+  constructor(name, message, options = {}) {
+    super(message);
+    this.name = name;
+    this.artifactRefs = options.artifactRefs || [];
+    this.rescueAction = options.rescueAction || 'inspect-runtime-artifacts';
+    this.details = options.details || {};
+  }
+}
+
+function namedError(name, message, options = {}) {
+  return new SkillRuntimeError(name, message, options);
+}
+
+function serializeError(error, fallbackName = 'SkillRuntimeError') {
+  const name = error?.name || fallbackName;
+  const message = error?.message || String(error || 'Unknown runtime error');
+
+  return {
+    name,
+    message,
+    artifactRefs: error?.artifactRefs || [],
+    rescueAction: error?.rescueAction || 'inspect-runtime-artifacts',
+    details: error?.details || {}
+  };
+}
+
+module.exports = {
+  SkillRuntimeError,
+  namedError,
+  serializeError
+};

package/lib/skill-runtime/index.js

@@ -9,6 +9,10 @@ const store = require('./store');
 const schemas = require('./schemas');
 const planner = require('./planner');
 const query = require('./query');
+const queryRegistry = require('./query-registry');
+const errors = require('./errors');
+const trace = require('./trace');
+const readiness = require('./readiness');
 const intent = require('./intent');
 const artifacts = require('./artifacts');
 const lifecycle = require('./lifecycle');
@@ -24,6 +28,10 @@ module.exports = {
   ...schemas,
   ...planner,
   ...query,
+  ...queryRegistry,
+  ...errors,
+  ...trace,
+  ...readiness,
   ...artifacts,
   ...intent,
   ...lifecycle,

package/lib/skill-runtime/operations/approve.js

@@ -15,6 +15,7 @@ const {
 const { parseRuntimeState, parseManifest } = require('../schemas');
 const { syncIntentMemory } = require('../intent');
 const { normalizeExecutionMode } = require('../lifecycle');
+const { namedError } = require('../errors');
 
 async function runApprove({ repoRoot, changeId, executionMode }) {
   const statePath = getRuntimeStatePath(repoRoot, changeId);
@@ -23,11 +24,25 @@ async function runApprove({ repoRoot, changeId, executionMode }) {
   const rawManifest = await readJson(manifestPath, null);
 
   if (!rawState) {
-    throw new Error(`Cannot approve ${changeId}: change-state.json is missing`);
+    throw namedError(
+      'MissingChangeStateError',
+      `Cannot approve ${changeId}: change-state.json is missing`,
+      {
+        artifactRefs: [statePath],
+        rescueAction: 'run cc-roadmap or cc-plan init before approving execution'
+      }
+    );
   }
 
   if (!rawManifest) {
-    throw new Error(`Cannot approve ${changeId}: task-manifest.json is missing`);
+    throw namedError(
+      'MissingTaskManifestError',
+      `Cannot approve ${changeId}: task-manifest.json is missing`,
+      {
+        artifactRefs: [manifestPath],
+        rescueAction: 'run cc-plan to create planning/task-manifest.json before approving execution'
+      }
+    );
   }
 
   const state = parseRuntimeState(rawState);

package/lib/skill-runtime/operations/release.js

@@ -17,6 +17,7 @@ const {
 } = require('../store');
 const { parseReportCard, parseManifest } = require('../schemas');
 const { syncIntentMemory } = require('../intent');
+const { assertShipReady } = require('../readiness');
 
 function formatReleaseNote({ changeId, manifest, report }) {
   const passedTasks = manifest.tasks.filter((task) => task.status === 'passed');
@@ -59,9 +60,11 @@ async function runRelease({ repoRoot, changeId }) {
   const manifest = parseManifest(await readJson(manifestPath));
   const previousState = await readJson(statePath, null);
 
-  if (report.overall !== 'pass') {
-    throw new Error('Release blocked: report-card overall is not pass');
-  }
+  assertShipReady(report, {
+    reportPath,
+    errorName: 'ReleaseReadinessError',
+    rescueAction: 'run cc-check until ship-readiness is ready before release'
+  });
 
   const note = formatReleaseNote({ changeId, manifest, report });
   const releaseNotePath = getReleaseNotePath(repoRoot, changeId);

package/lib/skill-runtime/operations/worker-run.js

@@ -33,6 +33,7 @@ const {
 const { parseCheckpoint, parseManifest, parseRuntimeState } = require('../schemas');
 const { applyManifestExecutionState } = require('../planner');
 const { syncIntentMemory } = require('../intent');
+const { namedError } = require('../errors');
 
 function quoteShellArg(value) {
   return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
@@ -136,6 +137,34 @@ async function buildTaskBrief(repoRoot, changeId, taskId, planVersion) {
   ].join('\n');
 }
 
+async function assertWorkerPlanFresh(repoRoot, changeId, handoff) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = parseManifest(await readJson(manifestPath));
+  const currentPlanVersion = manifest.metadata?.planVersion || 1;
+
+  if (currentPlanVersion === handoff.planVersion) {
+    return;
+  }
+
+  throw namedError(
+    'StalePlanVersionError',
+    `Worker ${handoff.workerId} was assigned to planVersion ${handoff.planVersion}, but current planVersion is ${currentPlanVersion}`,
+    {
+      artifactRefs: [
+        `devflow/changes/<change>/planning/task-manifest.json`,
+        handoff.assignmentPath
+      ],
+      rescueAction: 'rerun delegation sync for current planVersion before worker-run',
+      details: {
+        workerId: handoff.workerId,
+        assignedPlanVersion: handoff.planVersion,
+        currentPlanVersion,
+        manifestPath
+      }
+    }
+  );
+}
+
 async function buildProviderPrompt(repoRootOrHandoff, handoffOrTaskId, maybeTaskId) {
   const repoRoot = typeof repoRootOrHandoff === 'string' ? repoRootOrHandoff : process.cwd();
   const handoff = typeof repoRootOrHandoff === 'string' ? handoffOrTaskId : repoRootOrHandoff;
@@ -317,6 +346,7 @@ async function runWorkerCommand({
   }
 
   const handoff = await buildWorkerHandoff(repoRoot, changeId, workerId);
+  await assertWorkerPlanFresh(repoRoot, changeId, handoff);
   const primaryTaskId = pickTaskId(handoff, taskId);
   const assignment = {
     workerId,

package/lib/skill-runtime/planner.js

@@ -66,6 +66,14 @@ function parseCsvLike(rawText) {
     .filter(Boolean);
 }
 
+function quoteShellArg(value) {
+  return `'${String(value).replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function buildTaskRunCommand(taskId, title) {
+  return `printf '%s\\n' ${quoteShellArg(`[TASK ${taskId}] ${title}`)}`;
+}
+
 function parseFieldValues(rawValue) {
   const inlineRefs = parseInlineCodeRefs(rawValue);
   if (inlineRefs.length > 0) {
@@ -245,7 +253,7 @@ function parseTasksMarkdown(content) {
         dependsOn,
         touches,
         files: inlineFiles,
-        run: [`echo "[TASK ${taskId}] ${title}"`],
+        run: [buildTaskRunCommand(taskId, title)],
         checks: [],
         acceptance: [],
         verification: [],
@@ -420,7 +428,7 @@ function buildDefaultTasks(changeId) {
       dependsOn: [],
       touches: [],
       files: [],
-      run: [`echo "[TASK T001] Bootstrap ${changeId}"`],
+      run: [buildTaskRunCommand('T001', `Bootstrap ${changeId}`)],
       checks: [],
       acceptance: ['Bootstrap the requirement workspace'],
       verification: ['echo "[TASK T001] Bootstrap complete"'],

package/lib/skill-runtime/query-registry.js

@@ -0,0 +1,101 @@
+/**
+ * [INPUT]: 接收 query id、repoRoot/changeId 与只读 handler registry。
+ * [OUTPUT]: 返回 typed query result：ok/data 或 named error，并附 operational trace。
+ * [POS]: skill runtime 的查询分发表，只读派生已有 artifact，不承载 workflow 语义。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+
+const { namedError, serializeError } = require('./errors');
+const { createTrace } = require('./trace');
+
+function resolveArtifactRefs(entry, context, key) {
+  const refs = entry[key];
+  return typeof refs === 'function' ? refs(context) : refs || [];
+}
+
+function createQueryRegistry(entries) {
+  const registry = new Map(entries.map((entry) => [entry.id, entry]));
+
+  function listQueryIds() {
+    return [...registry.keys()].sort();
+  }
+
+  async function runQuery(queryId, context = {}) {
+    const entry = registry.get(queryId);
+
+    if (!entry) {
+      const supported = listQueryIds();
+      const error = namedError(
+        'UnknownQueryError',
+        `Unknown query id: ${queryId}`,
+        {
+          rescueAction: `use one of: ${supported.join(', ')}`,
+          details: { supported }
+        }
+      );
+
+      return {
+        ok: false,
+        queryId,
+        error: serializeError(error),
+        trace: createTrace({
+          event: 'query.unknown',
+          changeId: context.changeId,
+          nextAction: 'choose-supported-query'
+        })
+      };
+    }
+
+    const artifactRefs = resolveArtifactRefs(entry, context, 'artifactRefs');
+    const requiredArtifactRefs = resolveArtifactRefs(entry, context, 'requiredArtifactRefs');
+
+    try {
+      const missingRefs = requiredArtifactRefs.filter((ref) => !fs.existsSync(ref));
+      if (missingRefs.length > 0) {
+        throw namedError(
+          'MissingQueryArtifactError',
+          `Missing required query artifact: ${missingRefs.join(', ')}`,
+          {
+            artifactRefs: missingRefs,
+            rescueAction: 'create required runtime artifacts before running this query'
+          }
+        );
+      }
+
+      return {
+        ok: true,
+        queryId,
+        data: await entry.handler(context),
+        trace: createTrace({
+          event: `query.${queryId}`,
+          changeId: context.changeId,
+          artifactRefs,
+          nextAction: entry.nextAction || 'read-query-result'
+        })
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        queryId,
+        error: serializeError(error),
+        trace: createTrace({
+          event: `query.${queryId}.failed`,
+          changeId: context.changeId,
+          artifactRefs,
+          nextAction: error.rescueAction || 'inspect-runtime-artifacts'
+        })
+      };
+    }
+  }
+
+  return {
+    listQueryIds,
+    runQuery
+  };
+}
+
+module.exports = {
+  createQueryRegistry
+};

package/lib/skill-runtime/query.js

@@ -1,6 +1,6 @@
 /**
  * [INPUT]: 依赖 store/artifacts/lifecycle 读取 requirement 工件，接收 repoRoot 和 changeId。
- * [OUTPUT]: 对外提供 getProgress/getNextTask/getFullState 查询函数，作为兼容查询面聚合当前阶段与 PR brief 路径。
+ * [OUTPUT]: 对外提供 typed query registry 与兼容查询函数，附 named error 和 trace shape。
  * [POS]: skill runtime 的薄查询兼容层，只读 artifact 与共享 lifecycle 语义，不再自带流程推导副本。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
  */
@@ -20,6 +20,44 @@ const {
   deriveTaskProgress,
   isTaskCompletedStatus
 } = require('./lifecycle');
+const { createQueryRegistry } = require('./query-registry');
+const { namedError } = require('./errors');
+const { deriveShipReadiness } = require('./readiness');
+
+async function readQueryArtifact(filePath, { required = true } = {}) {
+  try {
+    const value = await readJson(filePath, null);
+
+    if (required && value === null) {
+      throw namedError(
+        'MissingQueryArtifactError',
+        `Missing required query artifact: ${filePath}`,
+        {
+          artifactRefs: [filePath],
+          rescueAction: 'create required runtime artifacts before running this query'
+        }
+      );
+    }
+
+    return value;
+  } catch (error) {
+    if (error.name === 'MissingQueryArtifactError') {
+      throw error;
+    }
+
+    throw namedError(
+      'InvalidQueryArtifactError',
+      `Invalid query artifact ${filePath}: ${error.message}`,
+      {
+        artifactRefs: [filePath],
+        rescueAction: 'repair or regenerate the invalid runtime artifact before running this query',
+        details: {
+          cause: error.name || 'Error'
+        }
+      }
+    );
+  }
+}
 
 /**
  * 获取任务进度统计
@@ -29,21 +67,8 @@ const {
  */
 async function getProgress(repoRoot, changeId) {
   const manifestPath = getTaskManifestPath(repoRoot, changeId);
-
-  try {
-    const manifest = await readJson(manifestPath);
-    return deriveTaskProgress(manifest.tasks || []);
-  } catch (error) {
-    return {
-      totalTasks: 0,
-      completedTasks: 0,
-      failedTasks: 0,
-      pendingTasks: 0,
-      runningTasks: 0,
-      skippedTasks: 0,
-      error: error.message
-    };
-  }
+  const manifest = await readQueryArtifact(manifestPath);
+  return deriveTaskProgress(manifest.tasks || []);
 }
 
 /**
@@ -54,41 +79,36 @@ async function getProgress(repoRoot, changeId) {
  */
 async function getNextTask(repoRoot, changeId) {
   const manifestPath = getTaskManifestPath(repoRoot, changeId);
+  const manifest = await readQueryArtifact(manifestPath);
+  const executionState = deriveManifestExecutionState(manifest.tasks || []);
+  const activePhase = manifest.activePhase ?? executionState.activePhase;
+  const completedIds = new Set(
+    (manifest.tasks || [])
+      .filter((task) => isTaskCompletedStatus(task.status))
+      .map((task) => task.id)
+  );
+  const currentTaskId = manifest.currentTaskId ?? executionState.currentTaskId;
 
-  try {
-    const manifest = await readJson(manifestPath);
-    const executionState = deriveManifestExecutionState(manifest.tasks || []);
-    const activePhase = manifest.activePhase ?? executionState.activePhase;
-    const completedIds = new Set(
-      (manifest.tasks || [])
-        .filter((task) => isTaskCompletedStatus(task.status))
-        .map((task) => task.id)
-    );
-    const currentTaskId = manifest.currentTaskId ?? executionState.currentTaskId;
-
-    if (currentTaskId) {
-      const currentTask = manifest.tasks.find((task) => task.id === currentTaskId);
-      if (currentTask && currentTask.status === 'pending') {
-        return currentTask;
-      }
+  if (currentTaskId) {
+    const currentTask = manifest.tasks.find((task) => task.id === currentTaskId);
+    if (currentTask && currentTask.status === 'pending') {
+      return currentTask;
     }
+  }
 
-    const nextTask = (manifest.tasks || []).find((task) => {
-      if (task.status !== 'pending') {
-        return false;
-      }
+  const nextTask = (manifest.tasks || []).find((task) => {
+    if (task.status !== 'pending') {
+      return false;
+    }
 
-      if (activePhase !== null && activePhase !== undefined && (task.phase || 1) !== activePhase) {
-        return false;
-      }
+    if (activePhase !== null && activePhase !== undefined && (task.phase || 1) !== activePhase) {
+      return false;
+    }
 
-      return (task.dependsOn || []).every((depId) => completedIds.has(depId));
-    });
+    return (task.dependsOn || []).every((depId) => completedIds.has(depId));
+  });
 
-    return nextTask || null;
-  } catch (error) {
-    return null;
-  }
+  return nextTask || null;
 }
 
 /**
@@ -102,56 +122,104 @@ async function getFullState(repoRoot, changeId) {
   const reportPath = getReportCardPath(repoRoot, changeId);
   const prBriefPath = getIntentPrBriefPath(repoRoot, changeId);
 
-  try {
-    const [state, manifest, hasPrBrief] = await Promise.all([
-      readJson(statePath),
-      readJson(getTaskManifestPath(repoRoot, changeId), null),
-      exists(prBriefPath)
-    ]);
-    const progress = await getProgress(repoRoot, changeId);
-    const nextTask = await getNextTask(repoRoot, changeId);
-    const report = await readJson(reportPath, null);
-
-    return {
-      lifecycle: {
-        changeId: state.changeId,
-        goal: state.goal,
-        status: state.status,
-        initializedAt: state.initializedAt,
-        plannedAt: state.plannedAt,
-        verifiedAt: state.verifiedAt,
-        releasedAt: state.releasedAt,
-        updatedAt: state.updatedAt,
-        stage: deriveLifecycleStage({ state, manifest, report, hasPrBrief }),
-        approval: getApprovalState(state, manifest)
-      },
-      progress,
-      nextTask,
-      delivery: {
-        prBriefPath: hasPrBrief ? prBriefPath : null
-      },
-      quality: report ? {
-        overall: report.overall,
-        verdict: report.verdict || (report.overall === 'pass' ? 'pass' : 'fail'),
-        reviewStatus: report.review?.status || 'skipped',
-        reviewFindings: (report.review?.findings || []).length,
-        blockingFindings: report.blockingFindings,
-        timestamp: report.timestamp
-      } : null
-    };
-  } catch (error) {
-    return {
-      error: error.message,
-      lifecycle: null,
-      progress: null,
-      nextTask: null,
-      quality: null
-    };
+  const [state, manifest, hasPrBrief] = await Promise.all([
+    readQueryArtifact(statePath),
+    readQueryArtifact(getTaskManifestPath(repoRoot, changeId)),
+    exists(prBriefPath)
+  ]);
+  const progress = await getProgress(repoRoot, changeId);
+  const nextTask = await getNextTask(repoRoot, changeId);
+  const report = await readQueryArtifact(reportPath, { required: false });
+
+  return {
+    lifecycle: {
+      changeId: state.changeId,
+      goal: state.goal,
+      status: state.status,
+      initializedAt: state.initializedAt,
+      plannedAt: state.plannedAt,
+      verifiedAt: state.verifiedAt,
+      releasedAt: state.releasedAt,
+      updatedAt: state.updatedAt,
+      stage: deriveLifecycleStage({ state, manifest, report, hasPrBrief }),
+      approval: getApprovalState(state, manifest)
+    },
+    progress,
+    nextTask,
+    delivery: {
+      prBriefPath: hasPrBrief ? prBriefPath : null
+    },
+    quality: report ? {
+      overall: report.overall,
+      verdict: report.verdict || (report.overall === 'pass' ? 'pass' : 'fail'),
+      reviewStatus: report.review?.status || 'skipped',
+      reviewFindings: (report.review?.findings || []).length,
+      blockingFindings: report.blockingFindings,
+      timestamp: report.timestamp
+    } : null
+  };
+}
+
+async function getShipReadiness(repoRoot, changeId) {
+  const reportPath = getReportCardPath(repoRoot, changeId);
+  const report = await readJson(reportPath, null);
+
+  if (!report) {
+    throw namedError(
+      'MissingReportCardError',
+      `Missing report card for ${changeId}`,
+      {
+        artifactRefs: [reportPath],
+        rescueAction: 'run cc-check and create review/report-card.json before cc-act'
+      }
+    );
   }
+
+  return deriveShipReadiness(report, { reportPath });
 }
 
+function queryArtifactRefs(repoRoot, changeId, names) {
+  const refs = {
+    manifest: getTaskManifestPath(repoRoot, changeId),
+    state: getRuntimeStatePath(repoRoot, changeId),
+    report: getReportCardPath(repoRoot, changeId),
+    prBrief: getIntentPrBriefPath(repoRoot, changeId)
+  };
+
+  return names.map((name) => refs[name]).filter(Boolean);
+}
+
+const registry = createQueryRegistry([
+  {
+    id: 'progress',
+    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
+    requiredArtifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
+    handler: ({ repoRoot, changeId }) => getProgress(repoRoot, changeId)
+  },
+  {
+    id: 'next-task',
+    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
+    requiredArtifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
+    handler: ({ repoRoot, changeId }) => getNextTask(repoRoot, changeId)
+  },
+  {
+    id: 'full-state',
+    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['state', 'manifest', 'report', 'prBrief']),
+    requiredArtifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['state', 'manifest']),
+    handler: ({ repoRoot, changeId }) => getFullState(repoRoot, changeId)
+  },
+  {
+    id: 'ship-readiness',
+    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['report']),
+    handler: ({ repoRoot, changeId }) => getShipReadiness(repoRoot, changeId)
+  }
+]);
+
 module.exports = {
   getProgress,
   getNextTask,
-  getFullState
+  getFullState,
+  getShipReadiness,
+  listQueryIds: registry.listQueryIds,
+  runQuery: registry.runQuery
 };

package/lib/skill-runtime/readiness.js

@@ -0,0 +1,84 @@
+/**
+ * [INPUT]: 接收 report-card 对象与 report artifact path。
+ * [OUTPUT]: 派生 ship-readiness 结果，并在未 ready 时抛出 named error。
+ * [POS]: skill runtime 的交付就绪单一真相源，被 query/release 共享。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { namedError } = require('./errors');
+
+function deriveVerdict(report) {
+  return report.verdict || (report.overall === 'pass' ? 'pass' : 'fail');
+}
+
+function collectShipReadinessBlockers(report) {
+  const verdict = deriveVerdict(report);
+  const blockers = [];
+
+  if (report.overall !== 'pass') {
+    blockers.push('report-card overall is not pass');
+  }
+
+  if (verdict !== 'pass') {
+    blockers.push(`verdict is ${verdict}`);
+  }
+
+  if ((report.reroute || 'none') !== 'none') {
+    blockers.push(`reroute is ${report.reroute}`);
+  }
+
+  if (report.specSyncReady !== true) {
+    blockers.push('specSyncReady is not true');
+  }
+
+  blockers.push(...(report.blockingFindings || []));
+  blockers.push(...(report.gaps || []));
+  return blockers;
+}
+
+function deriveShipReadiness(report, { reportPath = '' } = {}) {
+  const verdict = deriveVerdict(report);
+  const reroute = report.reroute || 'none';
+  const specSyncReady = report.specSyncReady === true;
+  const blockers = collectShipReadinessBlockers(report);
+
+  return {
+    ready: blockers.length === 0,
+    verdict,
+    reroute,
+    specSyncReady,
+    blockers,
+    reportPath,
+    timestamp: report.timestamp || ''
+  };
+}
+
+function assertShipReady(report, {
+  reportPath = '',
+  errorName = 'ShipReadinessError',
+  rescueAction = 'run cc-check until ship-readiness is ready'
+} = {}) {
+  const readiness = deriveShipReadiness(report, { reportPath });
+
+  if (readiness.ready) {
+    return readiness;
+  }
+
+  throw namedError(
+    errorName,
+    `Ship readiness blocked: ${readiness.blockers.join('; ')}`,
+    {
+      artifactRefs: reportPath ? [reportPath] : [],
+      rescueAction,
+      details: {
+        blockers: readiness.blockers
+      }
+    }
+  );
+}
+
+module.exports = {
+  collectShipReadinessBlockers,
+  deriveShipReadiness,
+  assertShipReady
+};