cc-devflow 4.5.8 → 4.5.10

package/lib/skill-runtime/planner.js

@@ -1,5 +1,5 @@
 /**
- * [INPUT]: 依赖 store 读取 tasks.md 与输出路径，依赖 schemas 校验 manifest。
+ * [INPUT]: 依赖 store 读取 tasks.md 与输出路径，接收 changeId/changeKey，依赖 schemas 校验 manifest。
  * [OUTPUT]: 对外提供 tasks.md → task-manifest.json 的解析与生成能力。
  * [POS]: skill runtime 计划编排层，被 operations/plan 直接调用。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
@@ -14,6 +14,7 @@ const {
   getTaskManifestPath,
   getTasksMarkdownPath
 } = require('./store');
+const path = require('path');
 const { parseManifest } = require('./schemas');
 const { isTaskCompletedStatus } = require('./lifecycle');
 
@@ -130,12 +131,21 @@ function dedupeList(values) {
   return [...new Set(values.filter(Boolean))];
 }
 
+function pushMissing(target, values) {
+  for (const value of values) {
+    if (value && !target.includes(value)) {
+      target.push(value);
+    }
+  }
+}
+
 function pickPrimaryTestTarget(task) {
   return [...(task.files || []), ...(task.touches || [])].find((item) => /\.test\./i.test(item)) || '';
 }
 
-function enrichTaskMetadata(task) {
+function enrichTaskMetadata(task, options = {}) {
   const primaryTestTarget = pickPrimaryTestTarget(task);
+  const defaultReadFiles = options.defaultReadFiles || ['design.md'];
 
   if (task.acceptance.length === 0) {
     if (task.type === 'TEST') {
@@ -162,9 +172,9 @@ function enrichTaskMetadata(task) {
   }
 
   if (task.context.readFiles.length === 0) {
-    task.context.readFiles.push('design.md');
+    pushMissing(task.context.readFiles, defaultReadFiles);
     if (task.type === 'TEST') {
-      task.context.readFiles.push('tasks.md');
+      pushMissing(task.context.readFiles, ['tasks.md']);
     }
     if (primaryTestTarget && !task.context.readFiles.includes(primaryTestTarget)) {
       task.context.readFiles.push(primaryTestTarget);
@@ -192,7 +202,7 @@ function parseDependsOn(rawTail, fallbackDependsOn, isParallel) {
   return [fallbackDependsOn];
 }
 
-function parseTasksMarkdown(content) {
+function parseTasksMarkdown(content, options = {}) {
   const lines = content.split(/\r?\n/);
   const tasks = [];
   let previousTaskId = null;
@@ -213,7 +223,7 @@ function parseTasksMarkdown(content) {
     task.context.readFiles = dedupeList(task.context.readFiles);
     task.context.commands = dedupeList(task.context.commands);
     task.context.notes = dedupeList(task.context.notes);
-    enrichTaskMetadata(task);
+    enrichTaskMetadata(task, options);
     task.acceptance = dedupeList(task.acceptance);
     task.verification = dedupeList(task.verification);
     task.evidence = dedupeList(task.evidence);
@@ -480,31 +490,33 @@ function deriveManifestExecutionState(tasks) {
 function applyManifestExecutionState(manifest, updatedAt = nowIso()) {
   const executionState = deriveManifestExecutionState(manifest.tasks || []);
   manifest.currentTaskId = executionState.currentTaskId;
-  manifest.activePhase = executionState.activePhase;
+  delete manifest.activePhase;
   manifest.updatedAt = updatedAt;
   return manifest;
 }
 
-async function createTaskManifest({ repoRoot, changeId, goal, overwrite = false }) {
-  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+async function createTaskManifest({ repoRoot, changeId, changeKey, goal, overwrite = false }) {
+  const pathOptions = changeKey ? { changeKey } : {};
+  const manifestPath = getTaskManifestPath(repoRoot, changeId, pathOptions);
   const previous = await readJson(manifestPath, null);
 
   if (!overwrite && (await exists(manifestPath))) {
     return parseManifest(previous);
   }
 
-  const tasksPath = getTasksMarkdownPath(repoRoot, changeId);
+  const tasksPath = getTasksMarkdownPath(repoRoot, changeId, pathOptions);
   const hasTasksFile = await exists(tasksPath);
-  const rawTasks = hasTasksFile ? parseTasksMarkdown(await readText(tasksPath)) : [];
+  const legacyDesignPath = path.join(path.dirname(tasksPath), 'design.md');
+  const defaultReadFiles = await exists(legacyDesignPath) ? ['design.md'] : ['tasks.md'];
+  const rawTasks = hasTasksFile ? parseTasksMarkdown(await readText(tasksPath), { defaultReadFiles }) : [];
   const tasks = rawTasks.length > 0 ? rawTasks : buildDefaultTasks(changeId);
   const previousPlanVersion = previous?.metadata?.planVersion || 0;
   const manifest = applyManifestExecutionState({
     changeId,
-    goal: goal || `Deliver ${changeId} safely with auditable checkpoints.`,
+    goal: goal || `Deliver ${changeId} safely with task-state truth.`,
     createdAt: previous?.createdAt || nowIso(),
     updatedAt: nowIso(),
     currentTaskId: null,
-    activePhase: null,
     tasks,
     metadata: {
       source: hasTasksFile ? 'tasks.md' : 'default',

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

@@ -59,7 +59,7 @@ function createQueryRegistry(entries) {
           `Missing required query artifact: ${missingRefs.join(', ')}`,
           {
             artifactRefs: missingRefs,
-            rescueAction: 'create required runtime artifacts before running this query'
+            rescueAction: 'create required workflow artifacts before running this query'
           }
         );
       }
@@ -84,7 +84,7 @@ function createQueryRegistry(entries) {
           event: `query.${queryId}.failed`,
           changeId: context.changeId,
           artifactRefs,
-          nextAction: error.rescueAction || 'inspect-runtime-artifacts'
+          nextAction: error.rescueAction || 'inspect-workflow-artifacts'
         })
       };
     }

package/lib/skill-runtime/query.js

@@ -23,6 +23,11 @@ const {
 const { createQueryRegistry } = require('./query-registry');
 const { namedError } = require('./errors');
 const { deriveShipReadiness } = require('./readiness');
+const {
+  getWorkflowContext,
+  getWorkflowContextArtifactRefs,
+  getWorkflowContextRequiredArtifactRefs
+} = require('./workflow-context');
 
 async function readQueryArtifact(filePath, { required = true } = {}) {
   try {
@@ -34,7 +39,7 @@ async function readQueryArtifact(filePath, { required = true } = {}) {
         `Missing required query artifact: ${filePath}`,
         {
           artifactRefs: [filePath],
-          rescueAction: 'create required runtime artifacts before running this query'
+          rescueAction: 'create required workflow artifacts before running this query'
         }
       );
     }
@@ -50,7 +55,7 @@ async function readQueryArtifact(filePath, { required = true } = {}) {
       `Invalid query artifact ${filePath}: ${error.message}`,
       {
         artifactRefs: [filePath],
-        rescueAction: 'repair or regenerate the invalid runtime artifact before running this query',
+        rescueAction: 'repair or regenerate the invalid workflow artifact before running this query',
         details: {
           cause: error.name || 'Error'
         }
@@ -81,7 +86,7 @@ async function getNextTask(repoRoot, changeId, options = {}) {
   const manifestPath = getTaskManifestPath(repoRoot, changeId, options);
   const manifest = await readQueryArtifact(manifestPath);
   const executionState = deriveManifestExecutionState(manifest.tasks || []);
-  const activePhase = manifest.activePhase ?? executionState.activePhase;
+  const activePhase = executionState.activePhase;
   const completedIds = new Set(
     (manifest.tasks || [])
       .filter((task) => isTaskCompletedStatus(task.status))
@@ -212,6 +217,13 @@ const registry = createQueryRegistry([
     id: 'ship-readiness',
     artifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['report'], { changeKey }),
     handler: ({ repoRoot, changeId, changeKey }) => getShipReadiness(repoRoot, changeId, { changeKey })
+  },
+  {
+    id: 'workflow-context',
+    artifactRefs: ({ repoRoot, changeId, changeKey }) => getWorkflowContextArtifactRefs(repoRoot, changeId, { changeKey }),
+    requiredArtifactRefs: ({ repoRoot, changeId, changeKey }) => getWorkflowContextRequiredArtifactRefs(repoRoot, changeId, { changeKey }),
+    nextAction: 'read-compact-workflow-context',
+    handler: ({ repoRoot, changeId, changeKey }) => getWorkflowContext(repoRoot, changeId, { changeKey })
   }
 ]);
 
@@ -220,6 +232,7 @@ module.exports = {
   getNextTask,
   getFullState,
   getShipReadiness,
+  getWorkflowContext,
   listQueryIds: registry.listQueryIds,
   runQuery: registry.runQuery
 };

package/lib/skill-runtime/review-records.js

@@ -0,0 +1,123 @@
+/**
+ * [INPUT]: 依赖 path/change paths 和 review ledger event 列表。
+ * [OUTPUT]: 提供 review 记录路径、reviewId 分配、CLI 参数归一化和 ledger 容错解析。
+ * [POS]: review durable records 的小核心；不写文件，只计算稳定标识和路径。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const path = require('path');
+
+const { getChangePaths } = require('./paths');
+const { parseReviewLedgerEvent } = require('./schemas');
+
+function getReviewLedgerPath(repoRoot, changeId, options = {}) {
+  return path.join(getChangePaths(repoRoot, changeId, options).reviewDir, 'review-ledger.jsonl');
+}
+
+function getReviewFindingsPath(repoRoot, changeId, options = {}) {
+  return path.join(getChangePaths(repoRoot, changeId, options).reviewDir, 'review-findings.json');
+}
+
+function reviewIdDate(date = new Date()) {
+  const year = String(date.getUTCFullYear());
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(date.getUTCDate()).padStart(2, '0');
+  return `${year}${month}${day}`;
+}
+
+function nextReviewId(events = [], date = new Date()) {
+  const datePart = reviewIdDate(date);
+  const prefix = `RVW-${datePart}-`;
+  const maxSequence = events.reduce((max, event) => {
+    const reviewId = String(event?.reviewId || '');
+    if (!reviewId.startsWith(prefix)) {
+      return max;
+    }
+
+    const sequence = Number(reviewId.slice(prefix.length));
+    return Number.isInteger(sequence) && sequence > max ? sequence : max;
+  }, 0);
+
+  return `${prefix}${String(maxSequence + 1).padStart(3, '0')}`;
+}
+
+function parseSkippedNode(value) {
+  const text = String(value || '').trim();
+  const separator = text.indexOf(':');
+  if (separator === -1) {
+    return { node: text, reason: '' };
+  }
+
+  return {
+    node: text.slice(0, separator).trim(),
+    reason: text.slice(separator + 1).trim()
+  };
+}
+
+function freshnessForLedger(entries, errors) {
+  if (errors.length > 0) {
+    return {
+      status: 'unknown',
+      reviewedCommit: '',
+      currentCommit: '',
+      commitsSinceReview: null,
+      staleReason: 'review ledger contained unparseable rows'
+    };
+  }
+
+  const latestClosed = [...entries].reverse().find((event) => event.event === 'review-closed');
+  const started = latestClosed
+    ? entries.find((event) => event.reviewId === latestClosed.reviewId && event.event === 'review-started')
+    : [...entries].reverse().find((event) => event.event === 'review-started');
+  const headSha = started?.headSha || '';
+
+  return {
+    status: headSha ? 'fresh' : 'unknown',
+    reviewedCommit: headSha,
+    currentCommit: headSha,
+    commitsSinceReview: headSha ? 0 : null,
+    staleReason: headSha ? '' : 'review ledger has no started event with headSha'
+  };
+}
+
+function parseReviewLedger(text = '') {
+  const entries = [];
+  const errors = [];
+
+  String(text || '').split(/\r?\n/).forEach((line, index) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
+    }
+
+    try {
+      entries.push(parseReviewLedgerEvent(JSON.parse(trimmed)));
+    } catch (error) {
+      errors.push(`line ${index + 1}: ${error.message}`);
+    }
+  });
+
+  const latestClosed = [...entries].reverse().find((event) => event.event === 'review-closed');
+  const findings = entries.filter((event) => event.event === 'review-finding-added');
+
+  return {
+    entries,
+    errors,
+    freshness: freshnessForLedger(entries, errors),
+    summary: {
+      status: latestClosed?.status || 'blocked',
+      blockingCount: latestClosed?.blockingCount ?? findings.filter((event) => event.displayTier === 'blocking').length,
+      warningCount: latestClosed?.warningCount ?? findings.filter((event) => event.displayTier === 'warning').length,
+      next: latestClosed?.next || (errors.length > 0 ? 'cc-do' : 'cc-check')
+    },
+    findings
+  };
+}
+
+module.exports = {
+  getReviewFindingsPath,
+  getReviewLedgerPath,
+  nextReviewId,
+  parseReviewLedger,
+  parseSkippedNode
+};

package/lib/skill-runtime/review.js

@@ -6,8 +6,18 @@
  */
 
 const {
+  exists,
+  readJson,
+  readText,
   runCommand
 } = require('./store');
+const { getChangePaths } = require('./paths');
+const { parseReviewFindingsDoc } = require('./schemas');
+const {
+  getReviewFindingsPath,
+  getReviewLedgerPath,
+  parseReviewLedger
+} = require('./review-records');
 
 const CODEX_BOUNDARY = [
   'IMPORTANT: Do NOT read or execute any files under ~/.claude/, ~/.agents/, .claude/skills/, or agents/.',
@@ -77,9 +87,11 @@ function makeFinding({
   line,
   action = 'none',
   status = 'open',
-  fingerprint
+  fingerprint,
+  confidenceScore,
+  displayTier
 }) {
-  const confidenceScore = severityRank(severity) >= severityRank('important') ? 8 : 6;
+  const derivedConfidenceScore = severityRank(severity) >= severityRank('important') ? 8 : 6;
   return {
     id,
     source,
@@ -92,11 +104,11 @@ function makeFinding({
     ...(typeof line === 'number' ? { line } : {}),
     action,
     status,
-    confidenceScore,
+    confidenceScore: confidenceScore || derivedConfidenceScore,
     fingerprint: fingerprint || `${source}:${category}:${id}`,
-    displayTier: status === 'informational'
+    displayTier: displayTier || (status === 'informational'
       ? 'info'
-      : (severityRank(severity) >= severityRank('important') ? 'blocking' : 'warning'),
+      : (severityRank(severity) >= severityRank('important') ? 'blocking' : 'warning')),
     suppressionReason: null
   };
 }
@@ -401,6 +413,218 @@ function buildCodexErrorFinding(source, summary, details, severity = 'important'
   });
 }
 
+async function firstExistingPath(paths) {
+  for (const filePath of paths) {
+    if (await exists(filePath)) {
+      return filePath;
+    }
+  }
+  return '';
+}
+
+function recordStatus(summary = {}, findings = []) {
+  if (summary.status === 'blocked') {
+    return 'blocked';
+  }
+  if (
+    summary.status === 'findings'
+    || Number(summary.blockingCount || 0) > 0
+    || findings.some((item) => item.displayTier === 'blocking' || severityRank(item.severity) >= severityRank('important'))
+  ) {
+    return 'fail';
+  }
+  return 'pass';
+}
+
+function reviewRecordSeverity(value) {
+  return value === 'advisory' ? 'minor' : value;
+}
+
+function reviewRecordAction(route, displayTier) {
+  if (route === 'cc-plan') return 'reroute-cc-plan';
+  if (route === 'cc-investigate') return 'reroute-cc-investigate';
+  if (route === 'cc-do') return displayTier === 'blocking' ? 'fix_now' : 'reroute-cc-do';
+  return displayTier === 'blocking' ? 'fix_now' : 'follow_up';
+}
+
+function makeReviewRecordFinding(item, index) {
+  const displayTier = item.displayTier || 'blocking';
+  const status = displayTier === 'info'
+    ? 'informational'
+    : (displayTier === 'suppressed' ? 'accepted' : 'open');
+  return makeFinding({
+    id: item.id || item.findingId || `review-record-${index + 1}`,
+    source: 'review-records',
+    scope: 'requirement',
+    category: 'review-record',
+    severity: reviewRecordSeverity(item.severity),
+    summary: truncate(item.evidence || item.recommendation || 'Review finding', 240),
+    details: item.recommendation || item.evidence || '',
+    file: item.path,
+    action: reviewRecordAction(item.route, displayTier),
+    status,
+    fingerprint: item.fingerprint,
+    confidenceScore: Number(item.confidence) || undefined,
+    displayTier
+  });
+}
+
+function normalizeFreshness(freshness = {}) {
+  return {
+    status: freshness.status || 'unknown',
+    reviewedCommit: freshness.reviewedCommit || '',
+    currentCommit: freshness.currentCommit || '',
+    commitsSinceReview: freshness.commitsSinceReview ?? null,
+    staleReason: freshness.staleReason || ''
+  };
+}
+
+function makeRecordReviewer(recordReview) {
+  return makeReviewer({
+    key: 'requirement-review-records',
+    scope: 'requirement',
+    mode: 'structured',
+    source: 'runtime',
+    status: recordReview.status,
+    summary: recordReview.summary,
+    evidence: [
+      makeEvidence('file', 'review record source', recordReview.source, recordReview.summary)
+    ],
+    findings: recordReview.findings || []
+  });
+}
+
+async function readReviewFindingsDoc(filePath) {
+  try {
+    const doc = parseReviewFindingsDoc(await readJson(filePath));
+    const findings = doc.findings.map(makeReviewRecordFinding);
+    return {
+      source: 'review-findings.json',
+      status: recordStatus(doc.summary, findings),
+      required: true,
+      summary: `review-findings.json reports ${doc.summary.status} with ${doc.summary.blockingCount} blocking finding(s).`,
+      freshness: normalizeFreshness(doc.freshness),
+      reviewers: [],
+      findings,
+      errors: []
+    };
+  } catch (error) {
+    return {
+      source: 'review-findings.json',
+      status: 'blocked',
+      required: true,
+      summary: `review-findings.json is unreadable: ${error.message}`,
+      freshness: normalizeFreshness({ status: 'unknown', staleReason: error.message }),
+      reviewers: [],
+      findings: [makeFinding({
+        id: 'review-findings-unreadable',
+        source: 'review-records',
+        scope: 'requirement',
+        category: 'review-record',
+        severity: 'important',
+        summary: 'review-findings.json is unreadable.',
+        details: error.message,
+        action: 'fix_now'
+      })],
+      errors: [error.message]
+    };
+  }
+}
+
+async function readReviewLedger(filePath) {
+  const parsed = parseReviewLedger(await readText(filePath, ''));
+  const findings = parsed.findings.map(makeReviewRecordFinding);
+  return {
+    source: 'review-ledger.jsonl',
+    status: recordStatus(parsed.summary, findings),
+    required: true,
+    summary: `review ledger reports ${parsed.summary.status} with ${parsed.summary.blockingCount} blocking finding(s).`,
+    freshness: normalizeFreshness(parsed.freshness),
+    reviewers: [],
+    findings,
+    errors: parsed.errors
+  };
+}
+
+async function runReviewRecordSection({ repoRoot, changeId }) {
+  const change = getChangePaths(repoRoot, changeId);
+  const findingsPath = await firstExistingPath([
+    getReviewFindingsPath(repoRoot, changeId, { changeKey: change.changeKey }),
+    `${change.reviewDir}/cc-review-findings.json`
+  ]);
+  if (findingsPath) {
+    const recordReview = await readReviewFindingsDoc(findingsPath);
+    return {
+      ...recordReview,
+      reviewers: [makeRecordReviewer(recordReview)]
+    };
+  }
+
+  const ledgerPath = await firstExistingPath([
+    getReviewLedgerPath(repoRoot, changeId, { changeKey: change.changeKey }),
+    `${change.reviewDir}/cc-review-ledger.jsonl`
+  ]);
+  if (ledgerPath) {
+    const recordReview = await readReviewLedger(ledgerPath);
+    return {
+      ...recordReview,
+      reviewers: [makeRecordReviewer(recordReview)]
+    };
+  }
+
+  const legacyReportPath = await firstExistingPath([
+    `${change.reviewDir}/cc-review-report.md`
+  ]);
+  if (legacyReportPath) {
+    const recordReview = {
+      source: 'cc-review-report.md',
+      status: 'pass',
+      required: true,
+      summary: 'legacy cc-review-report.md found; review freshness is unknown.',
+      freshness: normalizeFreshness({
+        status: 'unknown',
+        staleReason: 'legacy cc-review-report.md has no machine freshness fields'
+      }),
+      reviewers: [],
+      findings: [],
+      errors: []
+    };
+    return {
+      ...recordReview,
+      reviewers: [makeRecordReviewer(recordReview)]
+    };
+  }
+
+  const finding = makeFinding({
+    id: 'review-missing',
+    source: 'review-records',
+    scope: 'requirement',
+    category: 'review-record',
+    severity: 'important',
+    summary: 'review-missing: no review records are present.',
+    details: 'Expected review-findings.json, review-ledger.jsonl, or legacy cc-review-report.md before cc-check can pass.',
+    action: 'fix_now',
+    fingerprint: `${change.changeKey}:review-missing`
+  });
+  const recordReview = {
+    source: 'review-records',
+    status: 'blocked',
+    required: true,
+    summary: 'review-missing: no review records found.',
+    freshness: normalizeFreshness({
+      status: 'unknown',
+      staleReason: 'review-missing'
+    }),
+    reviewers: [],
+    findings: [finding],
+    errors: ['review-missing']
+  };
+  return {
+    ...recordReview,
+    reviewers: [makeRecordReviewer(recordReview)]
+  };
+}
+
 async function runDiffReviewSection({ repoRoot, strict, skipReview }) {
   if (!strict) {
     return {
@@ -526,10 +750,10 @@ function flattenFindings(...sections) {
   return sections.flatMap((section) => section.findings || []);
 }
 
-function deriveReviewStatus(taskReviews, diffReview) {
+function deriveReviewStatus(taskReviews, diffReview, recordReview) {
   let status = 'pass';
 
-  for (const section of [taskReviews, diffReview]) {
+  for (const section of [taskReviews, recordReview, diffReview]) {
     if (!section.required && section.status === 'skipped') {
       continue;
     }
@@ -541,20 +765,22 @@ function deriveReviewStatus(taskReviews, diffReview) {
 
 async function runReviewSuite({ repoRoot, changeId, manifest, strict, skipReview }) {
   const taskReviews = await runTaskReviewSection({ repoRoot, changeId, manifest });
+  const recordReview = await runReviewRecordSection({ repoRoot, changeId });
   const diffReview = await runDiffReviewSection({ repoRoot, strict, skipReview });
-  const findings = flattenFindings(taskReviews, diffReview);
-  const status = deriveReviewStatus(taskReviews, diffReview);
+  const findings = flattenFindings(taskReviews, recordReview, diffReview);
+  const status = deriveReviewStatus(taskReviews, diffReview, recordReview);
   const currentCommit = await detectCurrentCommit(repoRoot);
   const details = [
     taskReviews.summary,
+    recordReview.summary,
     diffReview.summary
   ].filter(Boolean).join(' ');
 
   return {
     status,
-    summary: `Task review: ${taskReviews.status}. Diff review: ${diffReview.status}.`,
+    summary: `Task review: ${taskReviews.status}. Record review: ${recordReview.status}. Diff review: ${diffReview.status}.`,
     details,
-    freshness: {
+    freshness: recordReview.freshness || {
       status: 'fresh',
       reviewedCommit: currentCommit,
       currentCommit,
@@ -570,6 +796,14 @@ async function runReviewSuite({ repoRoot, changeId, manifest, strict, skipReview
         summary: taskReviews.summary,
         skipReason: '',
         findings: []
+      },
+      {
+        name: 'review-records',
+        status: recordReview.status,
+        required: true,
+        summary: recordReview.summary,
+        skipReason: '',
+        findings: recordReview.findings || []
       }
     ],
     runtime: {
@@ -603,6 +837,7 @@ async function runReviewSuite({ repoRoot, changeId, manifest, strict, skipReview
       tddException: null
     },
     taskReviews,
+    recordReview,
     diffReview,
     findings
   };