cc-devflow 4.5.2 → 4.5.4

package/.claude/skills/cc-spec-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-spec-init
-version: 1.0.1
+version: 1.1.0
 description: Use when you need to initialize capability specs under `devflow/specs/`, create or evolve capability truth sources, generate `change-meta.json`, or validate roadmap/change/spec links before roadmap, planning, or closeout work continues.
 ---
 
@@ -67,6 +67,7 @@ description: Use when you need to initialize capability specs under `devflow/spe
 2. 先判断你是在做 `bootstrap`、`create`、`update-links`、`split`、`merge` 还是 `deprecate`。
 3. 先锁定 capability 边界，再写模板；不要先写 prose 再猜结构。
 4. 先明确 primary capability，再允许 secondary capabilities 存在。
+5. 先检查命名是否已经有 canonical term；同义词、歧义词和关系约束没收口前，不要新建第二套 capability 名称。
 
 ## Session Protocol
 
@@ -80,6 +81,7 @@ description: Use when you need to initialize capability specs under `devflow/spe
    - 为当前已知 capability 写最小 spec
 3. 如果是新 capability：
    - 先写 capability 边界、约束、当前 truth、gaps
+   - 再写最小 language block：canonical term、definition、aliases to avoid、relationships、flagged ambiguities
    - 再登记到 `INDEX.md`
 4. 如果是 change 绑定：
    - 生成或更新 `change-meta.json`
@@ -91,6 +93,17 @@ description: Use when you need to initialize capability specs under `devflow/spe
    - `INDEX.md` 引到的 capability 文件都存在
    - `change-meta.json` 里的 capability 都能落到 spec
    - roadmap / backlog 里的 capability 引用仍可追踪
+   - 新 capability 的名称、aliases、relationships 没有和已有 spec 冲突
+
+## Language Boundary Gate
+
+capability spec 是长期 truth source，命名必须比一次需求更稳定：
+
+- canonical term：只选一个主名，优先沿用 roadmap、历史 design/analysis、代码公共接口和用户领域语言里已经稳定的词。
+- aliases to avoid：记录容易混用的别名，说明为什么不能继续用。
+- flagged ambiguity：同一个词指向两个概念时，必须写清拆分边界，必要时拆 capability。
+- relationships：用一句话写清 capability 之间的拥有、依赖、生命周期、输入输出或互斥关系。
+- implementation names：类名、文件名、函数名只有在它们已经是公共领域语言时才进入 spec；否则留在 change 设计里。
 
 ## Output
 

package/CHANGELOG.md

@@ -9,6 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.4] - 2026-04-29
+
+### Fixed
+
+- Fixed typed runtime queries so malformed required artifacts, including invalid
+  `task-manifest.json`, return `InvalidQueryArtifactError` with `ok:false`
+  instead of reporting a successful query with an embedded error payload.
+
+## [4.5.3] - 2026-04-29
+
+### Skill Strategy Integration
+
+v4.5.3 absorbs the useful strategies from an external skill library into native
+cc-devflow contracts, keeping the public workflow cohesive instead of adding
+parallel skill surfaces.
+
+### Changed
+
+- Added an external skill strategy audit and migrated the useful patterns into native cc-devflow contracts instead of copying external skill prose.
+- Updated `cc-plan` to capture glossary deltas, compare non-trivial interface shapes, mark `AFK` / `HITL` vertical slices, and keep durable handoffs behavior-focused.
+- Updated `cc-investigate` to sharpen feedback loops as investigation products and record prevention handoffs after root-cause freeze.
+- Updated `cc-do` and `cc-check` to enforce tracer-bullet execution and review test fixture honesty around partial data, casts, stubs, and mocks.
+- Updated `cc-simplify` to apply deep-module, deletion-test, and real-seam checks before accepting architecture cleanup findings.
+- Updated `cc-act`, `cc-spec-init`, and `docs-sync` to harden issue handoffs, dangerous git action safety, capability language boundaries, and skill contract quality gates.
+- Updated `cc-check` to require QA feedback-loop and behavior evidence for bugfix and user-visible behavior verification, including reproduction mode, determinism, expected/actual behavior, and test seam follow-ups.
+- Updated `cc-act` to carry QA behavior evidence into PR briefs, handoffs, and release notes, and to write follow-ups as durable behavior briefs before roadmap/backlog writeback.
+- Updated `cc-roadmap`, `cc-plan`, and `cc-investigate` to keep canonical language and durable decisions in cc-devflow-native sources: `devflow/specs/`, roadmap/backlog, design/analysis, and change metadata.
+- Refreshed public examples and skill binding metadata for `cc-roadmap@4.4.1`, `cc-plan@3.7.0`, `cc-investigate@1.2.0`, `cc-do@1.6.0`, `cc-check@1.10.0`, `cc-act@1.8.0`, and `cc-spec-init@1.1.0`.
+
 ## [4.5.2] - 2026-04-28
 
 ### Skill Review Hardening

package/README.md

@@ -76,9 +76,17 @@ Maintenance skills are shipped with the pack:
 
 ## Planning Quality Gates
 
-`cc-roadmap` now records planning posture and evidence maturity before recommending a route. That keeps idea-stage, active-user, paying-customer, infrastructure, and recovery work from being forced through the same questions. Developer-facing or operator-facing roadmap items also carry target user, time to first value, magic moment, and adoption bottleneck into `cc-plan`.
+`cc-roadmap` now records planning posture, evidence maturity, canonical project language, and durable decision context before recommending a route. That keeps idea-stage, active-user, paying-customer, infrastructure, and recovery work from being forced through the same questions, and prevents roadmap items from inventing a second vocabulary. Developer-facing or operator-facing roadmap items also carry target user, time to first value, magic moment, adoption bottleneck, and domain handoff into `cc-plan`.
 
-`cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, coverage quality, and mandatory regression tests when existing behavior changes.
+Canonical language and durable decisions stay inside cc-devflow-native sources: `devflow/specs/`, `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, `planning/design.md`, `planning/analysis.md`, and `change-meta.json`.
+
+`cc-plan` freezes more implementation decisions before `cc-do` starts. Non-trivial plans compare minimal viable and ideal architecture options, full designs include decision horizon plus error/rescue mapping, and test-first plans record test framework evidence, public test seams, behavior assertions, mock boundaries, coverage quality, mandatory regression tests, interface depth, and vertical tracer-bullet slices when existing behavior changes.
+
+## Verification And Ship Gates
+
+`cc-check` now treats QA as a feedback-loop problem, not only a green-test problem. Bugfix and behavior work records the loop used to prove reality, expected versus actual behavior, reproduction steps, test boundary quality, and architecture follow-ups when no clean public test seam exists.
+
+`cc-act` carries that evidence into PR briefs, handoffs, and release notes. Follow-ups must be durable behavior briefs with current behavior, desired behavior, key interfaces, acceptance criteria, and explicit out-of-scope notes before they are written back to roadmap or backlog.
 
 ## Installation Modes
 

package/README.zh-CN.md

@@ -76,9 +76,17 @@ npx cc-devflow@latest adapt --cwd /path/to/your/project --all
 
 ## 计划质量门禁
 
-`cc-roadmap` 现在会先记录 planning posture 和 evidence maturity，再推荐路线。idea、已有用户、付费客户、infra、recovery 场景不会被套进同一组问题。面向开发者或操作者的 roadmap item 还会把目标用户、time to first value、magic moment 和 adoption bottleneck 交给 `cc-plan`。
+`cc-roadmap` 现在会先记录 planning posture、evidence maturity、项目 canonical language 和持久决策上下文，再推荐路线。idea、已有用户、付费客户、infra、recovery 场景不会被套进同一组问题，也不会让 roadmap item 发明第二套词汇。面向开发者或操作者的 roadmap item 还会把目标用户、time to first value、magic moment、adoption bottleneck 和 domain handoff 交给 `cc-plan`。
 
-`cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、覆盖质量，并在修改既有行为时强制规划 regression test。
+Canonical language 和 durable decisions 只收敛到 cc-devflow 原生真相源：`devflow/specs/`、`devflow/ROADMAP.md`、`devflow/BACKLOG.md`、`planning/design.md`、`planning/analysis.md` 和 `change-meta.json`。
+
+`cc-plan` 会在 `cc-do` 开始前冻结更多实现决策。非 trivial 计划需要比较 minimal viable 和 ideal architecture，full-design 需要包含 implementation decision horizon 和 error/rescue map；测试计划要记录测试框架证据、public test seam、behavior assertion、mock boundary、覆盖质量、强制 regression test、interface depth 和 vertical tracer-bullet slices。
+
+## 验证与交付门禁
+
+`cc-check` 现在把 QA 当成反馈环问题，而不是只看测试是否绿。Bugfix 和行为变更需要记录证明现实的 loop、expected / actual、复现步骤、测试边界质量；如果没有干净的 public test seam，要留下架构 follow-up。
+
+`cc-act` 会把这些证据带进 PR brief、handoff 和 release note。Follow-up 必须写成 durable behavior brief，包含 current behavior、desired behavior、key interfaces、acceptance criteria 和 out-of-scope，再回写 roadmap 或 backlog。
 
 ## 安装方式
 

package/bin/cc-devflow-cli.js

@@ -14,6 +14,10 @@ const {
   setConfigValue,
   writeConfigTemplate
 } = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/config.js'));
+const {
+  listQueryIds,
+  runQuery
+} = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/query.js'));
 const ADAPT_BIN = path.join(PACKAGE_ROOT, 'bin', 'adapt.js');
 const ADAPTER_BIN = path.join(PACKAGE_ROOT, 'bin', 'cc-devflow.js');
 const TEMPLATE_IGNORES = new Set(['.DS_Store', 'tsc-cache']);
@@ -54,6 +58,8 @@ Commands:
   config set          Set one project/user/local config value
   config resolve      Print resolved YAML config with key-level trace
   config doctor       Validate config and local ignore safety
+  query list          List typed runtime query ids
+  query <id>          Run a typed runtime query as JSON
 
 Init options:
   --dir <path>         Target project path (default: cwd)
@@ -79,6 +85,11 @@ Config options:
   --trace              Include key-level source trace with policy output
   --force              Overwrite an existing config template
 
+Query options:
+  --cwd <path>         Project path used for devflow artifact lookup
+  --change <id>        Change id, for example REQ-123
+  --change-id <id>     Alias for --change
+
 Examples:
   cc-devflow init
   cc-devflow init --dir /path/to/project
@@ -88,6 +99,8 @@ Examples:
   cc-devflow config set output.document_language zh-CN --cwd /path/to/project --project
   cc-devflow config set output.document_language zh-CN --user
   cc-devflow config resolve --cwd /path/to/project --format policy
+  cc-devflow query list
+  cc-devflow query ship-readiness --cwd /path/to/project --change REQ-123
 `);
 }
 
@@ -432,6 +445,75 @@ function runConfig(args) {
   return 0;
 }
 
+function parseQueryArgs(args) {
+  const parsed = {
+    cwd: null,
+    changeId: null,
+    rest: []
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--cwd') {
+      parsed.cwd = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--cwd=')) {
+      parsed.cwd = arg.slice('--cwd='.length);
+      continue;
+    }
+
+    if (arg === '--change' || arg === '--change-id') {
+      parsed.changeId = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--change=')) {
+      parsed.changeId = arg.slice('--change='.length);
+      continue;
+    }
+
+    if (arg.startsWith('--change-id=')) {
+      parsed.changeId = arg.slice('--change-id='.length);
+      continue;
+    }
+
+    parsed.rest.push(arg);
+  }
+
+  return parsed;
+}
+
+async function runQueryCommand(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    console.error('Use: cc-devflow query list OR cc-devflow query <id> --change <changeId> [--cwd <path>]');
+    return 3;
+  }
+
+  if (subcommand === 'list') {
+    process.stdout.write(`${listQueryIds().join('\n')}\n`);
+    return 0;
+  }
+
+  const options = parseQueryArgs(rest);
+  if (!options.changeId) {
+    console.error('Query --change is required.');
+    return 3;
+  }
+
+  const result = await runQuery(subcommand, {
+    repoRoot: path.resolve(options.cwd || process.cwd()),
+    changeId: options.changeId
+  });
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result.ok ? 0 : 2;
+}
+
 function runAdapt(args) {
   const { options, rest } = parseCliArgs(args);
 
@@ -475,7 +557,7 @@ function runAdapter(command, args) {
   return typeof result.status === 'number' ? result.status : 1;
 }
 
-function main() {
+async function main() {
   const argv = process.argv.slice(2);
   const [command, ...rest] = argv;
 
@@ -496,9 +578,18 @@ function main() {
     return runConfig(rest);
   }
 
+  if (command === 'query') {
+    return runQueryCommand(rest);
+  }
+
   return runAdapter(command, rest);
 }
 
 if (require.main === module) {
-  process.exit(main());
+  main()
+    .then((code) => process.exit(code))
+    .catch((error) => {
+      console.error(error.message);
+      process.exit(1);
+    });
 }

package/docs/examples/example-bindings.json

@@ -1,13 +1,13 @@
 {
   "updatedAt": "2026-04-28",
   "skills": {
-    "cc-roadmap": "4.3.4",
-    "cc-plan": "3.5.6",
-    "cc-investigate": "1.1.4",
-    "cc-do": "1.5.2",
-    "cc-check": "1.8.4",
-    "cc-act": "1.6.4",
-    "cc-spec-init": "1.0.1"
+    "cc-roadmap": "4.4.1",
+    "cc-plan": "3.7.1",
+    "cc-investigate": "1.2.1",
+    "cc-do": "1.6.1",
+    "cc-check": "1.10.1",
+    "cc-act": "1.8.1",
+    "cc-spec-init": "1.1.0"
   },
   "examples": [
     {

package/docs/examples/full-design-blocked/BACKLOG.md

@@ -3,7 +3,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
 - Tracking source: `roadmap-tracking.json`

package/docs/examples/full-design-blocked/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.4`
+- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`
 
 This example shows a requirement that **looked executable**, but `cc-check` correctly stopped it and sent it back to `cc-plan`.
 

package/docs/examples/full-design-blocked/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.5.6`
+- CC-Plan skill version: `3.7.1`
 - Requirement ID: `REQ-002`
 - Design mode: `full-design`
 - Why not `tiny-design`: the feature crosses import parsing, invite rules, billing limits, duplicate handling, and audit logging

package/docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import/planning/tasks.md

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-002.v2`
 - Design version: `design.v2`
-- CC-Plan skill version: `3.5.6`
+- CC-Plan skill version: `3.7.1`
 - Source roadmap item: `RM-010`
 - Source roadmap version: `roadmap.v2`
 

package/docs/examples/full-design-blocked/roadmap-tracking.json

@@ -3,7 +3,7 @@
   "lastSyncedAt": "2026-04-19",
   "backlogMeta": {
     "roadmapVersion": "roadmap.v2",
-    "skillVersion": "4.3.4",
+    "skillVersion": "4.4.1",
     "currentFocusStage": "Stage 2"
   },
   "dependencyHandoff": {

package/docs/examples/local-handoff/BACKLOG.md

@@ -3,7 +3,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 2`
 - Tracking source: `roadmap-tracking.json`

package/docs/examples/local-handoff/README.md

@@ -4,7 +4,7 @@
 
 - Example version: `1.0.0`
 - Last reviewed: `2026-04-17`
-- Bound skills: `cc-roadmap@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.4`, `cc-act@1.6.4`
+- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`, `cc-act@1.8.1`
 
 This example shows verified work that is **ready to move forward**, but `cc-act` still chooses `local-handoff`.
 

package/docs/examples/local-handoff/ROADMAP.md

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v3`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Status: `active`
 - Last updated: `2026-04-16`
 - Owner / decider: `product-owner`

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

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-003.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.5.6`
+- CC-Plan skill version: `3.7.1`
 - Requirement ID: `REQ-003`
 - Design mode: `tiny-design`
 - Why this stays `tiny-design`: the patch adds one export action inside the existing admin audit UI without changing data contracts

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.5.6`
+- CC-Plan skill version: `3.7.1`
 - Source roadmap item: `RM-020`
 - Source roadmap version: `roadmap.v3`
 

package/docs/examples/local-handoff/roadmap-tracking.json

@@ -3,7 +3,7 @@
   "lastSyncedAt": "2026-04-19",
   "backlogMeta": {
     "roadmapVersion": "roadmap.v2",
-    "skillVersion": "4.3.4",
+    "skillVersion": "4.4.1",
     "currentFocusStage": "Stage 2"
   },
   "dependencyHandoff": {

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

@@ -3,7 +3,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v1`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 1`
 - Tracking source: `roadmap-tracking.json`

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@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.4`, `cc-act@1.6.4`
+- Bound skills: `cc-roadmap@4.4.1`, `cc-plan@3.7.1`, `cc-do@1.6.1`, `cc-check@1.10.1`, `cc-act@1.8.1`
 
 This folder shows one minimal but complete `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act` loop.
 

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

@@ -3,7 +3,7 @@
 ## Roadmap Meta
 
 - Roadmap version: `roadmap.v1`
-- Skill version: `4.3.4`
+- Skill version: `4.4.1`
 - Status: `active`
 - Last updated: `2026-04-15`
 - Owner / decider: `product-owner`

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.5.6`
+- CC-Plan skill version: `3.7.1`
 - 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

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

@@ -9,7 +9,7 @@
   "sourceRoadmap": {
     "itemId": "RM-001",
     "roadmapVersion": "roadmap.v1",
-    "roadmapSkillVersion": "4.3.4",
+    "roadmapSkillVersion": "4.4.1",
     "sourceStage": "Stage 1",
     "successSignal": "Users can copy the invite link with one click",
     "killSignal": "The patch requires backend or permission changes",
@@ -22,7 +22,7 @@
     ]
   },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.5.6",
+    "reqPlanSkillVersion": "3.7.1",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T10:05:00.000Z",
     "approvedBy": "user",

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.5.6`
+- CC-Plan skill version: `3.7.1`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 

package/docs/examples/pdca-loop/roadmap-tracking.json

@@ -3,7 +3,7 @@
   "lastSyncedAt": "2026-04-19",
   "backlogMeta": {
     "roadmapVersion": "roadmap.v1",
-    "skillVersion": "4.3.4",
+    "skillVersion": "4.4.1",
     "currentFocusStage": "Stage 1"
   },
   "dependencyHandoff": {