cc-devflow 4.5.5 → 4.5.6

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/task-manifest.json

@@ -6,7 +6,7 @@
   "requirementId": "REQ-003",
   "requirementVersion": "REQ-003.v1",
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.5",
+    "reqPlanSkillVersion": "3.7.7",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-16T13:10:00.000Z",
     "approvedBy": "user",
@@ -29,7 +29,36 @@
       "testingDecisions": ["Test through the admin panel action and visible row data"],
       "outOfScope": ["JSON export", "scheduled reporting", "shared reporting backend"],
       "furtherNotes": ["Richer machine-readable exports should become a separate requirement"]
-    }
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Existing admin panel already owns the visible summary rows", "No reporting backend is needed for the first useful export"],
+        "recommendation": "Approve the tiny-design CSV export",
+        "options": [
+          {
+            "id": "A",
+            "label": "Tiny design CSV export",
+            "recommended": true,
+            "completeness": "8/10",
+            "good": "Solves weekly reporting friction with the current panel data",
+            "costRisk": "Does not handle JSON, scheduling, or shared reporting contracts"
+          },
+          {
+            "id": "B",
+            "label": "Shared reporting pipeline",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "Could support more formats and future scheduled reports",
+            "costRisk": "Creates a larger platform surface before the local export is proven"
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do exports only visible rows from the current panel and avoids new reporting contracts",
+        "status": "answered"
+      }
+    ]
   },
   "currentTaskId": null,
   "activePhase": null,

package/docs/examples/local-handoff/changes/REQ-003-audit-log-export/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-020`
 - Source roadmap version: `roadmap.v3`
 

package/docs/examples/pdca-loop/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.5`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
+- Bound skills: `cc-roadmap@5.0.0`, `cc-plan@3.7.7`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
 
 This folder shows one minimal but complete `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act` loop.
 

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Requirement ID: `REQ-001`
 - Design mode: `tiny-design`
 - Why this stays `tiny-design`: the patch is limited to an existing dialog and test file, with no API or data model changes
@@ -75,8 +75,15 @@
 - Ambiguity scan: pass; execution does not need to re-decide button placement or clipboard source
 - Feasibility scan: pass; existing dialog and tests already cover the target surface
 - PRD brief scan: pass; problem, story, implementation decision, testing decision, and out-of-scope are durable
+- Decision question scan: pass; `D1` approved the tiny-design copy-action boundary
 - Final recommendation: approved as `tiny-design`
 
+## Decision Questions
+
+| ID | Gate | Known evidence | Recommendation | User choice | Impact on `cc-do` | Status |
+|----|------|----------------|----------------|-------------|-------------------|--------|
+| D1 | approach-approval | Existing dialog already renders the invite URL and the change stays inside one UI/test surface | Approve the tiny-design copy action | Tiny design copy action | Keep implementation inside the share dialog; do not add backend or permission work | answered |
+
 ## Approval
 
 - User approval status: approved

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json

@@ -22,7 +22,7 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.7.5",
+    "reqPlanSkillVersion": "3.7.7",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T10:05:00.000Z",
     "approvedBy": "user",
@@ -45,7 +45,36 @@
       "testingDecisions": ["Test through the share dialog behavior, not an internal helper"],
       "outOfScope": ["invite generation", "role controls", "analytics", "clipboard fallback redesign"],
       "furtherNotes": ["Richer copied-state feedback is a separate UX requirement"]
-    }
+    },
+    "decisionQuestions": [
+      {
+        "questionId": "D1",
+        "gate": "approach-approval",
+        "knownEvidence": ["Existing dialog already renders the invite URL", "The patch stays inside one UI/test surface"],
+        "recommendation": "Approve the tiny-design copy action",
+        "options": [
+          {
+            "id": "A",
+            "label": "Tiny design copy action",
+            "recommended": true,
+            "completeness": "8/10",
+            "good": "Ships the visible user win with one dialog and one behavior test",
+            "costRisk": "Leaves richer feedback and clipboard fallback work for later"
+          },
+          {
+            "id": "B",
+            "label": "Full share-flow redesign",
+            "recommended": false,
+            "completeness": "10/10",
+            "good": "Could solve broader invite UX issues in one larger pass",
+            "costRisk": "Expands beyond the roadmap wedge and touches unrelated share contracts"
+          }
+        ],
+        "userChoice": "A",
+        "impact": "cc-do keeps implementation inside the share dialog and avoids backend or permission work",
+        "status": "answered"
+      }
+    ]
   },
   "currentTaskId": null,
   "activePhase": null,

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.7.5`
+- CC-Plan skill version: `3.7.7`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 

package/docs/guides/getting-started.md

@@ -94,7 +94,7 @@ Capability truth lives in `devflow/specs/`.
 Change truth lives in `devflow/changes/<change>/`.
 
 - Keep `INDEX.md` plus capability markdown under `devflow/specs/`.
-- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` are separate number sequences; old lowercase directories are compatibility reads only.
+- Name new change directories as `REQ-<number>-<description>` for requirements or `FIX-<number>-<description>` for bug fixes. `REQ` and `FIX` advance as separate local sequences, so cross-prefix duplicates are valid. Parallel worktrees may still repeat numbers; the full change key, especially the description, distinguishes the work. Old lowercase directories are compatibility reads only.
 - Keep `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`.
 - Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 

package/docs/guides/getting-started.zh-CN.md

@@ -93,7 +93,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 durable truth 分两层：
 
 - `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
-- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，旧小写目录只作为历史兼容读取。
+- 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 的描述负责区分业务内容，旧小写目录只作为历史兼容读取。
 - `devflow/changes/<change>/`：变更真相，保留 `change-state.json`、`change-meta.json`、planning 文档、`task-manifest.json`、可选 `team-state.json`、任务级 `checkpoint.json`、`report-card.json` 和唯一的最终 handoff 文件。
 - worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 

package/lib/skill-runtime/__tests__/autopilot.test.js

@@ -55,9 +55,10 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       [
         '- [ ] T001 启动 autopilot 闭环 (src/a.ts)',
         '- [ ] T002 多文件委派任务 [P] (src/a.ts,src/b.ts)'
@@ -67,14 +68,14 @@ describe('runAutopilot', () => {
     const result = await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop'
+      goal
     });
 
     const runtimeState = JSON.parse(fs.readFileSync(getRuntimeStatePath(repoRoot, 'REQ-123'), 'utf8'));
 
     expect(result.executed).toEqual(['init', 'snapshot', 'plan']);
     expect(result.currentStage).toBe('approve');
-    expect(runtimeState.changeKey).toBe('REQ-123-change');
+    expect(runtimeState.changeKey).toBe('REQ-123-ship-thin-autopilot-loop');
     expect(fs.existsSync(getReportCardPath(repoRoot, 'REQ-123'))).toBe(false);
     expect(fs.existsSync(getIntentPrBriefPath(repoRoot, 'REQ-123'))).toBe(false);
     expect(fs.existsSync(getIntentResumeIndexPath(repoRoot, 'REQ-123'))).toBe(false);
@@ -93,9 +94,10 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop with delegated workers';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       [
         '- [ ] T001 直接执行任务 (src/a.ts)',
         '- [ ] T002 委派实现任务 [P] (src/a.ts,src/b.ts)'
@@ -105,7 +107,7 @@ describe('runAutopilot', () => {
     await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop with delegated workers'
+      goal
     });
 
     await runApprove({
@@ -160,16 +162,17 @@ describe('runAutopilot', () => {
       }
     });
 
-    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123')), { recursive: true });
+    const goal = 'Ship thin autopilot loop and release';
+    fs.mkdirSync(path.dirname(getTasksMarkdownPath(repoRoot, 'REQ-123', { goal })), { recursive: true });
     fs.writeFileSync(
-      getTasksMarkdownPath(repoRoot, 'REQ-123'),
+      getTasksMarkdownPath(repoRoot, 'REQ-123', { goal }),
       '- [ ] T001 发布前收尾 (src/a.ts)'
     );
 
     await runAutopilot({
       repoRoot,
       changeId: 'REQ-123',
-      goal: 'Ship thin autopilot loop and release'
+      goal
     });
 
     await runApprove({

package/lib/skill-runtime/__tests__/paths.test.js

@@ -39,4 +39,29 @@ describe('change directory naming', () => {
 
     fs.rmSync(repoRoot, { recursive: true, force: true });
   });
+
+  test('allows duplicate numbers when descriptions differ', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-paths-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-existing-plan'), { recursive: true });
+
+    const paths = getChangePaths(repoRoot, 'REQ-123', { goal: 'Another plan' });
+
+    expect(paths.changeKey).toBe('REQ-123-another-plan');
+    expect(paths.changeDir).toBe(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-another-plan'));
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
+
+  test('requires explicit change keys when duplicate numbers already exist', () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-paths-'));
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-first-plan'), { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', 'REQ-123-second-plan'), { recursive: true });
+
+    expect(() => getChangePaths(repoRoot, 'REQ-123'))
+      .toThrow(/Ambiguous changeId "REQ-123"/);
+    expect(getChangePaths(repoRoot, 'REQ-123', { changeKey: 'REQ-123-second-plan' }).changeKey)
+      .toBe('REQ-123-second-plan');
+
+    fs.rmSync(repoRoot, { recursive: true, force: true });
+  });
 });

package/lib/skill-runtime/__tests__/query.test.js

@@ -324,6 +324,55 @@ describe('query helpers', () => {
     expect(listQueryIds()).toEqual(expect.arrayContaining(['full-state', 'next-task', 'progress']));
   });
 
+  test('requires a full change key when duplicate local numbers exist', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-duplicate-key-'));
+    const firstKey = 'REQ-132-first-plan';
+    const secondKey = 'REQ-132-second-plan';
+
+    fs.mkdirSync(path.join(repoRoot, 'devflow', 'changes', firstKey), { recursive: true });
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-132', { changeKey: secondKey }), {
+      changeId: 'REQ-132',
+      goal: 'Resolve duplicate local numbers',
+      createdAt: '2026-05-08T01:00:00.000Z',
+      updatedAt: '2026-05-08T01:05:00.000Z',
+      tasks: [
+        { id: 'T001', status: 'passed' },
+        { id: 'T002', status: 'pending' }
+      ],
+      metadata: {
+        source: 'test',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    await expect(runQuery('progress', { repoRoot, changeId: 'REQ-132' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'progress',
+      error: {
+        message: expect.stringContaining('Ambiguous changeId "REQ-132"')
+      },
+      trace: {
+        event: 'query.progress.failed',
+        nextAction: 'inspect-runtime-artifacts'
+      }
+    });
+
+    await expect(runQuery('progress', {
+      repoRoot,
+      changeId: 'REQ-132',
+      changeKey: secondKey
+    })).resolves.toMatchObject({
+      ok: true,
+      queryId: 'progress',
+      data: {
+        totalTasks: 2,
+        completedTasks: 1,
+        pendingTasks: 1
+      }
+    });
+  });
+
   test('returns a named error for unknown query ids', async () => {
     const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-unknown-'));
 

package/lib/skill-runtime/artifacts.js

@@ -68,8 +68,8 @@ function getLegacyIntentProjectionPaths(repoRoot, goalId, taskIds = [], options
   ];
 }
 
-async function ensureIntentScaffold(repoRoot, goalId) {
-  const change = getChangePaths(repoRoot, goalId);
+async function ensureIntentScaffold(repoRoot, goalId, options = {}) {
+  const change = getChangePaths(repoRoot, goalId, options);
 
   await ensureDir(change.changeDir);
   await ensureDir(change.metaDir);

package/lib/skill-runtime/intent.js

@@ -68,11 +68,11 @@ function summarizeGateSection(gates = []) {
   });
 }
 
-async function readLatestCheckpoints(repoRoot, changeId, tasks = []) {
+async function readLatestCheckpoints(repoRoot, changeId, tasks = [], options = {}) {
   const checkpoints = [];
 
   for (const task of tasks) {
-    const checkpoint = await readJson(getCheckpointPath(repoRoot, changeId, task.id), null);
+    const checkpoint = await readJson(getCheckpointPath(repoRoot, changeId, task.id, options), null);
     if (!checkpoint) {
       continue;
     }
@@ -90,28 +90,28 @@ async function readLatestCheckpoints(repoRoot, changeId, tasks = []) {
   return checkpoints;
 }
 
-async function cleanupLegacyArtifacts(repoRoot, changeId, manifest) {
+async function cleanupLegacyArtifacts(repoRoot, changeId, manifest, options = {}) {
   const taskIds = (manifest?.tasks || []).map((task) => task.id);
-  const change = getChangePaths(repoRoot, changeId);
+  const change = getChangePaths(repoRoot, changeId, options);
 
   await Promise.all(
-    getLegacyIntentProjectionPaths(repoRoot, changeId, taskIds).map((target) => removePath(target))
+    getLegacyIntentProjectionPaths(repoRoot, changeId, taskIds, options).map((target) => removePath(target))
   );
   await removePath(change.workersDir);
 }
 
-async function clearHandoffArtifacts(repoRoot, changeId, keep = null) {
+async function clearHandoffArtifacts(repoRoot, changeId, keep = null, options = {}) {
   await Promise.all(
-    getIntentHandoffArtifactPaths(repoRoot, changeId)
+    getIntentHandoffArtifactPaths(repoRoot, changeId, options)
       .filter((target) => target !== keep)
       .map((target) => removePath(target))
   );
 }
 
-async function writeResumeIndex(repoRoot, changeId, state, manifest, report) {
-  await ensureIntentScaffold(repoRoot, changeId);
+async function writeResumeIndex(repoRoot, changeId, state, manifest, report, options = {}) {
+  await ensureIntentScaffold(repoRoot, changeId, options);
 
-  const checkpoints = await readLatestCheckpoints(repoRoot, changeId, manifest?.tasks || []);
+  const checkpoints = await readLatestCheckpoints(repoRoot, changeId, manifest?.tasks || [], options);
   const lastGoodCheckpoint = checkpoints.find((checkpoint) => checkpoint.status === 'passed') || checkpoints[0] || null;
   const blockers = [
     ...(manifest?.tasks || [])
@@ -119,8 +119,8 @@ async function writeResumeIndex(repoRoot, changeId, state, manifest, report) {
       .map((task) => `${task.id}: ${task.lastError || 'Task failed'}`),
     ...(report?.blockingFindings || [])
   ];
-  const hasPrBrief = await exists(getIntentPrBriefPath(repoRoot, changeId));
-  const hasReleaseNote = await exists(getReleaseNotePath(repoRoot, changeId));
+  const hasPrBrief = await exists(getIntentPrBriefPath(repoRoot, changeId, options));
+  const hasReleaseNote = await exists(getReleaseNotePath(repoRoot, changeId, options));
   const stage = deriveLifecycleStage({ state, manifest, report, hasPrBrief });
   const approval = getApprovalState(state, manifest);
   const goal = manifest?.goal || state?.goal || changeId;
@@ -131,7 +131,7 @@ async function writeResumeIndex(repoRoot, changeId, state, manifest, report) {
     hasPrBrief,
     hasReleaseNote
   });
-  const resumePath = getIntentResumeIndexPath(repoRoot, changeId);
+  const resumePath = getIntentResumeIndexPath(repoRoot, changeId, options);
 
   const content = [
     `# Resume Index: ${changeId}`,
@@ -167,7 +167,7 @@ async function writeResumeIndex(repoRoot, changeId, state, manifest, report) {
     ])
   ].join('\n');
 
-  await clearHandoffArtifacts(repoRoot, changeId, resumePath);
+  await clearHandoffArtifacts(repoRoot, changeId, resumePath, options);
   await writeText(resumePath, `${content}\n`);
 
   return {

package/lib/skill-runtime/operations/autopilot-shared.js

@@ -28,11 +28,11 @@ function hasUnresolvedTasks(manifest) {
   );
 }
 
-async function loadState(repoRoot, changeId) {
+async function loadState(repoRoot, changeId, options = {}) {
   const [state, manifest, report] = await Promise.all([
-    readJson(getRuntimeStatePath(repoRoot, changeId), null),
-    readJson(getTaskManifestPath(repoRoot, changeId), null),
-    readJson(getReportCardPath(repoRoot, changeId), null)
+    readJson(getRuntimeStatePath(repoRoot, changeId, options), null),
+    readJson(getTaskManifestPath(repoRoot, changeId, options), null),
+    readJson(getReportCardPath(repoRoot, changeId, options), null)
   ]);
 
   return { state, manifest, report };

package/lib/skill-runtime/paths.js

@@ -1,7 +1,7 @@
 /**
  * [INPUT]: 依赖 fs/path，接收 repoRoot/changeId/taskId/workerId 等定位参数。
  * [OUTPUT]: 对外提供 devflow canonical layout 的唯一路径解析能力。
- * [POS]: skill runtime 的路径真相源，强制新 change 目录使用 REQ/FIX 前缀。
+ * [POS]: skill runtime 的路径真相源，完整 change key 才是目录身份。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
  */
 
@@ -85,17 +85,27 @@ function listChangeKeys(repoRoot) {
     .sort();
 }
 
-function findExistingChangeKey(repoRoot, changeId) {
+function findExistingChangeKeys(repoRoot, changeId) {
   const canonicalPrefix = `${getChangeKeyPrefix(changeId)}-`;
   const legacyKey = slugifySegment(changeId, 'change');
   const legacyPrefix = `${legacyKey}-`;
 
-  return listChangeKeys(repoRoot).find((name) => (
+  return listChangeKeys(repoRoot).filter((name) => (
     name === changeId
     || name === legacyKey
     || name.startsWith(canonicalPrefix)
     || name.startsWith(legacyPrefix)
-  )) || null;
+  ));
+}
+
+function findExactChangeKey(repoRoot, changeId, changeKey) {
+  const slug = getChangeSlug(changeId, changeKey);
+  const aliases = new Set([
+    changeKey,
+    `${slugifySegment(changeId, 'change')}-${slug}`
+  ]);
+
+  return listChangeKeys(repoRoot).find((name) => aliases.has(name)) || null;
 }
 
 function assertChangeKey(changeId, changeKey) {
@@ -132,9 +142,20 @@ function resolveChangeKey(repoRoot, changeId, options = {}) {
     return assertChangeKey(changeId, options.changeKey);
   }
 
-  const existing = findExistingChangeKey(repoRoot, changeId);
-  if (existing) {
-    return existing;
+  const requestedSlug = options.slug || stripChangeIdPrefix(changeId, options.goal);
+  if (requestedSlug) {
+    const requestedKey = buildChangeKey(changeId, { slug: requestedSlug });
+    return findExactChangeKey(repoRoot, changeId, requestedKey) || requestedKey;
+  }
+
+  const existing = findExistingChangeKeys(repoRoot, changeId);
+  if (existing.length === 1) {
+    return existing[0];
+  }
+  if (existing.length > 1) {
+    throw new Error(
+      `Ambiguous changeId "${changeId}": found ${existing.join(', ')}. Pass an explicit changeKey.`
+    );
   }
 
   return buildChangeKey(changeId, options);

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

@@ -48,10 +48,10 @@ function createQueryRegistry(entries) {
       };
     }
 
-    const artifactRefs = resolveArtifactRefs(entry, context, 'artifactRefs');
-    const requiredArtifactRefs = resolveArtifactRefs(entry, context, 'requiredArtifactRefs');
-
+    let artifactRefs = [];
     try {
+      artifactRefs = resolveArtifactRefs(entry, context, 'artifactRefs');
+      const requiredArtifactRefs = resolveArtifactRefs(entry, context, 'requiredArtifactRefs');
       const missingRefs = requiredArtifactRefs.filter((ref) => !fs.existsSync(ref));
       if (missingRefs.length > 0) {
         throw namedError(

package/lib/skill-runtime/query.js

@@ -1,5 +1,5 @@
 /**
- * [INPUT]: 依赖 store/artifacts/lifecycle 读取 requirement 工件，接收 repoRoot 和 changeId。
+ * [INPUT]: 依赖 store/artifacts/lifecycle 读取 requirement 工件，接收 repoRoot、changeId 和可选 changeKey。
  * [OUTPUT]: 对外提供 typed query registry 与兼容查询函数，附 named error 和 trace shape。
  * [POS]: skill runtime 的薄查询兼容层，只读 artifact 与共享 lifecycle 语义，不再自带流程推导副本。
  * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
@@ -65,8 +65,8 @@ async function readQueryArtifact(filePath, { required = true } = {}) {
  * @param {string} changeId - 需求 ID
  * @returns {Promise<Object>} 进度统计对象
  */
-async function getProgress(repoRoot, changeId) {
-  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+async function getProgress(repoRoot, changeId, options = {}) {
+  const manifestPath = getTaskManifestPath(repoRoot, changeId, options);
   const manifest = await readQueryArtifact(manifestPath);
   return deriveTaskProgress(manifest.tasks || []);
 }
@@ -77,8 +77,8 @@ async function getProgress(repoRoot, changeId) {
  * @param {string} changeId - 需求 ID
  * @returns {Promise<Object|null>} 下一个任务对象或 null
  */
-async function getNextTask(repoRoot, changeId) {
-  const manifestPath = getTaskManifestPath(repoRoot, changeId);
+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;
@@ -117,18 +117,18 @@ async function getNextTask(repoRoot, changeId) {
  * @param {string} changeId - 需求 ID
  * @returns {Promise<Object>} 完整状态对象
  */
-async function getFullState(repoRoot, changeId) {
-  const statePath = getRuntimeStatePath(repoRoot, changeId);
-  const reportPath = getReportCardPath(repoRoot, changeId);
-  const prBriefPath = getIntentPrBriefPath(repoRoot, changeId);
+async function getFullState(repoRoot, changeId, options = {}) {
+  const statePath = getRuntimeStatePath(repoRoot, changeId, options);
+  const reportPath = getReportCardPath(repoRoot, changeId, options);
+  const prBriefPath = getIntentPrBriefPath(repoRoot, changeId, options);
 
   const [state, manifest, hasPrBrief] = await Promise.all([
     readQueryArtifact(statePath),
-    readQueryArtifact(getTaskManifestPath(repoRoot, changeId)),
+    readQueryArtifact(getTaskManifestPath(repoRoot, changeId, options)),
     exists(prBriefPath)
   ]);
-  const progress = await getProgress(repoRoot, changeId);
-  const nextTask = await getNextTask(repoRoot, changeId);
+  const progress = await getProgress(repoRoot, changeId, options);
+  const nextTask = await getNextTask(repoRoot, changeId, options);
   const report = await readQueryArtifact(reportPath, { required: false });
 
   return {
@@ -160,8 +160,8 @@ async function getFullState(repoRoot, changeId) {
   };
 }
 
-async function getShipReadiness(repoRoot, changeId) {
-  const reportPath = getReportCardPath(repoRoot, changeId);
+async function getShipReadiness(repoRoot, changeId, options = {}) {
+  const reportPath = getReportCardPath(repoRoot, changeId, options);
   const report = await readJson(reportPath, null);
 
   if (!report) {
@@ -178,12 +178,12 @@ async function getShipReadiness(repoRoot, changeId) {
   return deriveShipReadiness(report, { reportPath });
 }
 
-function queryArtifactRefs(repoRoot, changeId, names) {
+function queryArtifactRefs(repoRoot, changeId, names, options = {}) {
   const refs = {
-    manifest: getTaskManifestPath(repoRoot, changeId),
-    state: getRuntimeStatePath(repoRoot, changeId),
-    report: getReportCardPath(repoRoot, changeId),
-    prBrief: getIntentPrBriefPath(repoRoot, changeId)
+    manifest: getTaskManifestPath(repoRoot, changeId, options),
+    state: getRuntimeStatePath(repoRoot, changeId, options),
+    report: getReportCardPath(repoRoot, changeId, options),
+    prBrief: getIntentPrBriefPath(repoRoot, changeId, options)
   };
 
   return names.map((name) => refs[name]).filter(Boolean);
@@ -192,26 +192,26 @@ function queryArtifactRefs(repoRoot, changeId, names) {
 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)
+    artifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['manifest'], { changeKey }),
+    requiredArtifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['manifest'], { changeKey }),
+    handler: ({ repoRoot, changeId, changeKey }) => getProgress(repoRoot, changeId, { changeKey })
   },
   {
     id: 'next-task',
-    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
-    requiredArtifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['manifest']),
-    handler: ({ repoRoot, changeId }) => getNextTask(repoRoot, changeId)
+    artifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['manifest'], { changeKey }),
+    requiredArtifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['manifest'], { changeKey }),
+    handler: ({ repoRoot, changeId, changeKey }) => getNextTask(repoRoot, changeId, { changeKey })
   },
   {
     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)
+    artifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['state', 'manifest', 'report', 'prBrief'], { changeKey }),
+    requiredArtifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['state', 'manifest'], { changeKey }),
+    handler: ({ repoRoot, changeId, changeKey }) => getFullState(repoRoot, changeId, { changeKey })
   },
   {
     id: 'ship-readiness',
-    artifactRefs: ({ repoRoot, changeId }) => queryArtifactRefs(repoRoot, changeId, ['report']),
-    handler: ({ repoRoot, changeId }) => getShipReadiness(repoRoot, changeId)
+    artifactRefs: ({ repoRoot, changeId, changeKey }) => queryArtifactRefs(repoRoot, changeId, ['report'], { changeKey }),
+    handler: ({ repoRoot, changeId, changeKey }) => getShipReadiness(repoRoot, changeId, { changeKey })
   }
 ]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.5.5",
+    "version": "4.5.6",
     "description": "Multi-platform CLI and skill pack for agent coding",
     "main": "bin/cc-devflow.js",
     "bin": {