cc-devflow 4.4.1 → 4.5.1

package/bin/cc-devflow-cli.js

@@ -7,6 +7,13 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, '.claude');
 const TEMPLATE_SKILLS_DIR = path.join(TEMPLATE_DIR, 'skills');
 const DISTRIBUTION_CONFIG = require(path.join(PACKAGE_ROOT, 'config', 'distributable-skills.json'));
+const {
+  doctorUserConfig,
+  getConfigValue,
+  resolveUserConfig,
+  setConfigValue,
+  writeConfigTemplate
+} = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/config.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']);
@@ -42,6 +49,11 @@ Usage: cc-devflow <command> [options]
 Commands:
   init                Install .claude template into a project
   adapt               Compile .claude into multi-platform outputs
+  config init         Create a YAML config template
+  config get          Print one resolved config value
+  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
 
 Init options:
   --dir <path>         Target project path (default: cwd)
@@ -56,11 +68,26 @@ Adapt options:
   --rules              Generate rules entry files only
   --verbose            Show detailed output
 
+Config options:
+  --cwd <path>         Project path used for project/local config lookup
+  --user               Read/write ~/.cc-devflow/config.yml
+  --project            Read/write .cc-devflow/config.yml
+  --local              Read/write .cc-devflow/config.local.yml
+  --scope <name>       Backward-compatible scope alias: user, project, or local
+  --format <name>      Output format: json or policy
+  --document-language  CLI override for output.document_language
+  --trace              Include key-level source trace with policy output
+  --force              Overwrite an existing config template
+
 Examples:
   cc-devflow init
   cc-devflow init --dir /path/to/project
   cc-devflow adapt --platform cursor
   cc-devflow adapt --cwd /path/to/project --platform codex
+  cc-devflow config init --cwd /path/to/project --project
+  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
 `);
 }
 
@@ -210,6 +237,201 @@ function runInit(args) {
   return 0;
 }
 
+function parseConfigArgs(args) {
+  const parsed = {
+    cwd: null,
+    documentLanguage: null,
+    force: false,
+    format: 'json',
+    scope: 'project',
+    trace: false
+  };
+  const rest = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--force') {
+      parsed.force = true;
+      continue;
+    }
+
+    if (arg === '--trace') {
+      parsed.trace = true;
+      continue;
+    }
+
+    if (arg === '--user') {
+      parsed.scope = 'user';
+      continue;
+    }
+
+    if (arg === '--project') {
+      parsed.scope = 'project';
+      continue;
+    }
+
+    if (arg === '--local') {
+      parsed.scope = 'local';
+      continue;
+    }
+
+    if (arg === '--cwd') {
+      parsed.cwd = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--cwd=')) {
+      parsed.cwd = arg.slice('--cwd='.length);
+      continue;
+    }
+
+    if (arg === '--scope') {
+      parsed.scope = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--scope=')) {
+      parsed.scope = arg.slice('--scope='.length);
+      continue;
+    }
+
+    if (arg === '--format') {
+      parsed.format = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--format=')) {
+      parsed.format = arg.slice('--format='.length);
+      continue;
+    }
+
+    if (arg === '--document-language') {
+      parsed.documentLanguage = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--document-language=')) {
+      parsed.documentLanguage = arg.slice('--document-language='.length);
+      continue;
+    }
+
+    rest.push(arg);
+  }
+
+  parsed.rest = rest;
+  return parsed;
+}
+
+function parseConfigOverrides(options) {
+  if (!options.documentLanguage) {
+    return {};
+  }
+
+  return {
+    output: {
+      document_language: options.documentLanguage
+    }
+  };
+}
+
+function runConfig(args) {
+  const [subcommand, ...rest] = args;
+  const options = parseConfigArgs(rest);
+  const cwd = path.resolve(options.cwd || process.cwd());
+
+  if (subcommand === 'init') {
+    const configPath = writeConfigTemplate({
+      cwd,
+      force: options.force,
+      scope: options.scope
+    });
+    console.log(`Config template ready: ${configPath}`);
+    return 0;
+  }
+
+  if (subcommand === 'get') {
+    const keyPath = options.rest[0];
+    if (!keyPath) {
+      console.error('Config key is required.');
+      return 3;
+    }
+
+    const resolved = resolveUserConfig({
+      cwd,
+      overrides: parseConfigOverrides(options)
+    });
+    const value = getConfigValue(resolved.config, keyPath);
+    if (value === undefined) {
+      return 4;
+    }
+    process.stdout.write(`${typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value)}\n`);
+    return 0;
+  }
+
+  if (subcommand === 'set') {
+    const [keyPath, value] = options.rest;
+    if (!keyPath || value === undefined) {
+      console.error('Use: cc-devflow config set <key> <value>');
+      return 3;
+    }
+
+    const configPath = setConfigValue(keyPath, value, {
+      cwd,
+      scope: options.scope
+    });
+    console.log(`Updated ${configPath}`);
+    return 0;
+  }
+
+  if (subcommand === 'doctor') {
+    const result = doctorUserConfig({
+      cwd,
+      overrides: parseConfigOverrides(options)
+    });
+
+    if (result.ok) {
+      console.log('Config OK');
+      return 0;
+    }
+
+    for (const warning of result.warnings) {
+      console.error(`Config warning: ${warning}`);
+    }
+    return 2;
+  }
+
+  if (subcommand !== 'resolve') {
+    console.error('Unknown config command. Use: cc-devflow config init|get|set|resolve|doctor');
+    return 3;
+  }
+
+  const resolved = resolveUserConfig({
+    cwd,
+    overrides: parseConfigOverrides(options)
+  });
+
+  if (options.format === 'policy') {
+    process.stdout.write(resolved.policy || '');
+    if (options.trace) {
+      process.stdout.write('\nTrace:\n');
+      for (const entry of resolved.trace) {
+        const sourcePath = entry.path ? ` ${entry.path}` : '';
+        process.stdout.write(`- ${entry.key} = ${entry.value} (${entry.source}${sourcePath})\n`);
+      }
+    }
+    return 0;
+  }
+
+  if (options.format !== 'json') {
+    console.error(`Unknown config format: ${options.format}`);
+    return 3;
+  }
+
+  process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
+  return 0;
+}
+
 function runAdapt(args) {
   const { options, rest } = parseCliArgs(args);
 
@@ -270,6 +492,10 @@ function main() {
     return runAdapt(rest);
   }
 
+  if (command === 'config') {
+    return runConfig(rest);
+  }
+
   return runAdapter(command, rest);
 }
 

package/config/schema/cc-devflow-config.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CC-DevFlow User Config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "document_language": {
+          "type": "string",
+          "enum": ["en", "zh-CN"]
+        }
+      }
+    },
+    "agent_preferences": {
+      "type": "object",
+      "description": "Advisory user preferences. These can be non-standard, but they do not override workflow contracts.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "number" },
+          { "type": "boolean" },
+          {
+            "type": "array",
+            "items": {
+              "type": ["string", "number", "boolean", "object", "array", "null"]
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": true
+          },
+          { "type": "null" }
+        ]
+      }
+    }
+  },
+  "required": ["version"]
+}

package/config/user-config.template.yml

@@ -0,0 +1,16 @@
+version: 1
+
+output:
+  # Machine-enforced. Supported values: en, zh-CN.
+  document_language: zh-CN
+
+# Advisory preferences. cc-devflow preserves these values and exposes them in
+# `cc-devflow config resolve --format policy`, but workflow rules still win.
+agent_preferences:
+  general:
+    - Durable planning, review, and handoff documents should be direct and verifiable.
+    - State assumptions before task breakdowns.
+  planning:
+    - Record trade-offs and non-goals before implementation tasks.
+  review:
+    - List behavior risks before style suggestions.

package/docs/examples/example-bindings.json

@@ -1,13 +1,13 @@
 {
-  "updatedAt": "2026-04-25",
+  "updatedAt": "2026-04-28",
   "skills": {
-    "cc-roadmap": "4.3.1",
-    "cc-plan": "3.5.3",
-    "cc-investigate": "1.1.1",
-    "cc-do": "1.5.1",
-    "cc-check": "1.8.1",
-    "cc-act": "1.6.1",
-    "cc-spec-init": "1.0.0"
+    "cc-roadmap": "4.3.4",
+    "cc-plan": "3.5.6",
+    "cc-investigate": "1.1.2",
+    "cc-do": "1.5.2",
+    "cc-check": "1.8.2",
+    "cc-act": "1.6.2",
+    "cc-spec-init": "1.0.1"
   },
   "examples": [
     {

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

@@ -3,7 +3,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v2`
-- Skill version: `4.3.1`
+- Skill version: `4.3.4`
 - 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.1`, `cc-plan@3.5.3`, `cc-do@1.5.1`, `cc-check@1.8.1`
+- Bound skills: `cc-roadmap@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.2`
 
 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.1`
+- Skill version: `4.3.4`
 - 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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.1",
+    "skillVersion": "4.3.4",
     "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.1`
+- Skill version: `4.3.4`
 - 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.1`, `cc-plan@3.5.3`, `cc-do@1.5.1`, `cc-check@1.8.1`, `cc-act@1.6.1`
+- Bound skills: `cc-roadmap@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.2`, `cc-act@1.6.2`
 
 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.1`
+- Skill version: `4.3.4`
 - 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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.1",
+    "skillVersion": "4.3.4",
     "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.1`
+- Skill version: `4.3.4`
 - 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.1`, `cc-plan@3.5.3`, `cc-do@1.5.1`, `cc-check@1.8.1`, `cc-act@1.6.1`
+- Bound skills: `cc-roadmap@4.3.4`, `cc-plan@3.5.6`, `cc-do@1.5.2`, `cc-check@1.8.2`, `cc-act@1.6.2`
 
 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.1`
+- Skill version: `4.3.4`
 - 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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.1",
+    "roadmapSkillVersion": "4.3.4",
     "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.3",
+    "reqPlanSkillVersion": "3.5.6",
     "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.3`
+- CC-Plan skill version: `3.5.6`
 - 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.1",
+    "skillVersion": "4.3.4",
     "currentFocusStage": "Stage 1"
   },
   "dependencyHandoff": {

package/docs/guides/getting-started.md

@@ -98,6 +98,11 @@ Change truth lives in `devflow/changes/<change>/`.
 - 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.
 
+Planning handoffs should be evidence-rich before implementation starts:
+
+- `cc-roadmap` records planning posture, evidence maturity, framing check, dependency graph, and any developer/operator adoption context.
+- `cc-plan` records option roles, implementation surface, decision horizon, error/rescue map, test framework source, coverage quality, and regression-test requirements when they apply.
+
 Typical public contract fields:
 
 - `triggers`, `reads`, structured `writes`, `effects`

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

@@ -97,6 +97,11 @@ durable truth 分两层：
 - `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。
 
+进入实现前，planning handoff 应该先把证据写实：
+
+- `cc-roadmap` 记录 planning posture、evidence maturity、framing check、依赖图，以及适用时的 developer/operator adoption context。
+- `cc-plan` 记录 option roles、implementation surface、decision horizon、error/rescue map、测试框架来源、覆盖质量，以及适用时的 regression-test requirement。
+
 公开契约字段的典型形状：
 
 - `triggers`、`reads`、结构化 `writes`、`effects`