cc-devflow 4.4.1 → 4.5.1

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

@@ -1,6 +1,6 @@
 ---
 name: cc-spec-init
-version: 1.0.0
+version: 1.0.1
 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.
 ---
 
@@ -33,6 +33,14 @@ description: Use when you need to initialize capability specs under `devflow/spe
 - 重建 `devflow/specs/INDEX.md`
 - 校验 capability、roadmap item、change 之间的链接完整性
 
+## Runtime Output Policy
+
+写入任何 durable Markdown 或 JSON metadata 前，先运行 `cc-devflow config resolve --format policy`。
+
+- `Output language` 是机器约束，capability spec、`devflow/specs/INDEX.md` 和 `change-meta.json` 必须记录并遵守它。
+- `agent_preferences` 是用户偏好建议，只影响表达方式和结构选择，不覆盖本 Skill 的工作流边界。
+- 如果配置解析失败，先修配置或向用户说明阻塞，不要用默认语言继续生成正式文档。
+
 ## Read First
 
 1. `PLAYBOOK.md`

package/.claude/skills/cc-spec-init/assets/CAPABILITY_TEMPLATE.md

@@ -4,6 +4,7 @@ title: Example Capability
 type: user-visible
 status: partial
 primary_owner: ""
+output_language: ""
 last_verified_at: 2026-04-19
 roadmap_links:
   - RM-001

package/.claude/skills/cc-spec-init/assets/CHANGE_META_TEMPLATE.json

@@ -1,6 +1,9 @@
 {
   "changeId": "REQ-001",
   "requirementId": "REQ-001",
+  "outputPolicy": {
+    "documentLanguage": ""
+  },
   "sourceRoadmap": {
     "itemId": "RM-001",
     "roadmapVersion": "roadmap.v1",

package/.claude/skills/cc-spec-init/assets/INDEX_TEMPLATE.md

@@ -3,6 +3,7 @@
 ## Index Meta
 
 - Spec system version: `spec.v1`
+- Output language:
 - Last updated:
 - Maintainer:
 - Notes:

package/CHANGELOG.md

@@ -9,6 +9,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.1] - 2026-04-28
+
+### Planning Evidence Gates
+
+v4.5.1 strengthens roadmap and requirement planning so downstream execution gets
+clearer evidence, option tradeoffs, rescue behavior, and test obligations before
+implementation starts.
+
+### Changed
+
+- Updated `cc-roadmap` to record planning posture, evidence maturity, framing checks, and developer/operator adoption handoff fields.
+- Updated `cc-plan` to require named option roles, implementation decision horizon, error/rescue mapping, test framework evidence, coverage quality mapping, and regression-test planning.
+- Updated README and getting-started docs to describe the new roadmap and planning quality gates.
+- Refreshed public examples and skill binding metadata for `cc-roadmap@4.3.4` and `cc-plan@3.5.6`.
+
+### Fixed
+
+- Improved publish validation diagnostics for YAML frontmatter list items that accidentally parse as mappings when they contain `": "`.
+- Added a regression test so malformed public-skill string arrays report the exact field, index, actual type, and repair hint.
+
+## [4.5.0] - 2026-04-27
+
+### ✨ Runtime YAML Config
+
+v4.5.0 adds a personal/project YAML config mechanism that resolves output policy
+at runtime before durable workflow documents are written.
+
+### Added
+
+- Added `~/.cc-devflow/config.yml`, `<repo>/.cc-devflow/config.yml`, and `<repo>/.cc-devflow/config.local.yml` resolution with deterministic defaults < user < project < local < env < CLI precedence.
+- Added strict `output.document_language` validation for `en` and `zh-CN`, with non-standard preferences preserved under advisory `agent_preferences`.
+- Added `cc-devflow config init|get|set|resolve|doctor` so users can create, inspect, update, trace, and diagnose the effective output contract.
+- Added `config/user-config.template.yml` and `config/schema/cc-devflow-config.schema.json`.
+
+### Changed
+
+- Public workflow skills now resolve config at runtime with `cc-devflow config resolve --format policy` before writing durable Markdown or human-readable metadata.
+- `cc-devflow init` and `cc-devflow adapt --platform codex` no longer bake resolved user policy into managed Skill files.
+
 ## [4.4.1] - 2026-04-25
 
 ### 🔧 Canonical Change Keys + Planning Contract Hardening

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+[中文版](./CODE_OF_CONDUCT.zh-CN.md) | [English](./CODE_OF_CONDUCT.md)
+
+## Purpose
+
+cc-devflow is built for practical agent-coding workflows. The project benefits from direct technical debate, but that debate must stay focused on code, design, evidence, and maintainability.
+
+This code of conduct applies to project spaces, including issues, pull requests, discussions, documentation, examples, and maintainer communication channels.
+
+## Expected Behavior
+
+- Be clear, specific, and evidence-based when reporting bugs or reviewing code.
+- Critique ideas, code, architecture, and tradeoffs instead of attacking people.
+- Assume contributors may have different language backgrounds and levels of context.
+- Keep discussions aligned with the project scope: workflow skills, CLI distribution, adapters, examples, and documentation.
+- Respect maintainer decisions after a direction is explained.
+
+## Unacceptable Behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Personal attacks, repeated bad-faith arguments, or derailing technical threads.
+- Publishing private information without permission.
+- Spam, advertising, or automated low-quality issue and PR noise.
+- Security disclosure pressure, public exploit details, or demands for private maintainer information.
+
+## Reporting
+
+For conduct concerns, open a private maintainer contact path if one is available in the project profile. If no private path exists, create a GitHub issue with only the minimum public context needed and ask maintainers to move the discussion to a private channel.
+
+For vulnerabilities, do not use conduct reports. Follow [SECURITY.md](./SECURITY.md).
+
+## Enforcement
+
+Maintainers may remove content, close issues or pull requests, block accounts, or limit participation when behavior harms the project. Enforcement should be proportional, evidence-based, and focused on restoring a productive project environment.
+
+## Notes
+
+This is a project-specific conduct policy, written to match cc-devflow's technical collaboration model. It is intentionally short so contributors can read and apply it quickly.

package/CODE_OF_CONDUCT.zh-CN.md

@@ -0,0 +1,39 @@
+# 行为准则
+
+[中文版](./CODE_OF_CONDUCT.zh-CN.md) | [English](./CODE_OF_CONDUCT.md)
+
+## 目的
+
+cc-devflow 服务于真实的 Agent 编程工作流。项目欢迎直接、严格的技术讨论，但讨论必须始终围绕代码、设计、证据和可维护性。
+
+本行为准则适用于项目空间，包括 issue、pull request、discussion、文档、样例，以及维护者沟通渠道。
+
+## 期望行为
+
+- 报告 Bug 或 Review 代码时，保持清晰、具体、基于证据。
+- 批评想法、代码、架构和取舍，不攻击个人。
+- 尊重贡献者的语言背景和上下文差异。
+- 讨论保持在项目范围内：workflow skill、CLI 分发、adapter、样例和文档。
+- 当维护者解释方向后，尊重最终维护决策。
+
+## 不可接受行为
+
+- 骚扰、威胁、侮辱或歧视性表达。
+- 人身攻击、反复恶意争论，或故意带偏技术讨论。
+- 未经许可公开他人隐私信息。
+- 垃圾信息、广告，或自动化低质量 issue / PR 噪音。
+- 安全披露施压、公开漏洞利用细节，或索要维护者私人信息。
+
+## 报告方式
+
+如果遇到行为准则问题，优先使用项目资料中可用的私密维护者联系方式。如果暂时没有私密渠道，可以创建 GitHub issue，只写最少必要的公开上下文，并请求维护者转入私密渠道处理。
+
+漏洞报告不要走行为准则渠道。请遵循 [SECURITY.zh-CN.md](./SECURITY.zh-CN.md)。
+
+## 执行
+
+当行为损害项目环境时，维护者可以删除内容、关闭 issue 或 PR、阻止账号，或限制参与。执行应基于证据、保持比例，并以恢复健康的项目协作为目标。
+
+## 说明
+
+这是为 cc-devflow 技术协作方式定制的项目级行为准则。它刻意保持简短，方便贡献者快速阅读和执行。

package/CONTRIBUTING.md

@@ -0,0 +1,195 @@
+# Contributing to cc-devflow
+
+[中文版](./CONTRIBUTING.zh-CN.md) | [English](./CONTRIBUTING.md)
+
+---
+
+Please also read the [Code of Conduct](./CODE_OF_CONDUCT.md). If you are reporting a vulnerability, follow the [Security Policy](./SECURITY.md) instead of opening a public issue.
+
+## Overview
+
+cc-devflow is now a skills-first repository with a restored distributable CLI.
+
+Public surface:
+
+- `cc-roadmap`
+- `cc-plan`
+- `cc-investigate`
+- `cc-do`
+- `cc-check`
+- `cc-act`
+- `cc-devflow init`
+- `cc-devflow adapt`
+
+Shared runtime helpers may still live under `lib/skill-runtime/`, but they are not the user-facing workflow anymore.
+
+Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`, but they do not change the public `cc-roadmap + PDCA/IDCA` workflow story.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm
+- Git
+
+### Install
+
+```bash
+git clone https://github.com/YOUR_USERNAME/cc-devflow.git
+cd cc-devflow
+npm install
+```
+
+### Local CLI Smoke Test
+
+When working from source, use the repo-local entrypoint:
+
+```bash
+node bin/cc-devflow-cli.js --help
+tmpdir=$(mktemp -d)
+node bin/cc-devflow-cli.js init --dir "$tmpdir"
+node bin/cc-devflow-cli.js adapt --cwd "$tmpdir" --platform codex
+rm -rf "$tmpdir"
+```
+
+For packaged behavior, validate with:
+
+```bash
+npm pack
+node scripts/validate-publish.js
+```
+
+---
+
+## Project Structure
+
+```text
+cc-devflow/
+├── .claude/skills/            # Distributed skills
+├── bin/                       # CLI entrypoints
+├── config/                    # Adapter configuration
+├── docs/                      # Public docs
+├── lib/adapters/              # Platform adapter layer
+├── lib/compiler/              # Multi-platform compiler
+├── lib/skill-runtime/         # Shared runtime helpers and colocated tests for skill scripts
+├── README.md
+├── README.zh-CN.md
+└── package.json
+```
+
+### Contribution Areas
+
+- `.claude/skills/`: skill behavior, assets, references, scripts
+- `bin/`: distributable CLI behavior
+- `lib/compiler/`: skills/prompts parsing, transformation, emitters, rules generation
+- `lib/adapters/`: platform adapter config and validation
+- `lib/skill-runtime/`: shared runtime helpers used by skill-local scripts
+- `docs/`: user-facing documentation
+
+---
+
+## Contribution Rules
+
+### 1. Keep The Public Surface Small
+
+Do not reintroduce old `/flow:*` or `harness:*` CLI instructions into new user docs.
+
+The user-facing story should stay:
+
+- whole pack: `cc-devflow init`
+- platform outputs: `cc-devflow adapt`
+- workflow execution: visible `cc-roadmap + PDCA/IDCA` skills
+- capability truth maintenance: `cc-spec-init`
+
+### 2. Preserve Skills-First Layout
+
+Each shipped skill should keep its own folder:
+
+```text
+.claude/skills/<skill>/
+├── SKILL.md
+├── PLAYBOOK.md
+├── assets/
+├── references/
+└── scripts/
+```
+
+If you touch a shipped skill, treat these files as one contract:
+
+- `SKILL.md`
+- local `CHANGELOG.md`
+- any referenced `PLAYBOOK.md`, `assets/`, `references/`, `scripts/`
+
+Do not change one part of the contract and leave the others stale.
+
+### 3. Keep Distribution Clean
+
+Do not ship transient files in templates or tarballs.
+
+Examples of junk we should exclude:
+
+- `.claude/tsc-cache/`
+- `.DS_Store`
+- local editor or OS artifacts
+
+### 4. Keep Runtime Helpers Secondary
+
+If you touch `lib/skill-runtime/`, keep the behavior testable, but do not document it as the primary user entry. The public workflow still belongs to the shipped skills.
+
+---
+
+## Testing
+
+### Main Test Command
+
+```bash
+npm test
+```
+
+### Focused CLI Regression
+
+```bash
+npm test -- --runInBand lib/skill-runtime/__tests__/cli-bootstrap.integration.test.js
+```
+
+### Publish Validation
+
+```bash
+node scripts/validate-publish.js
+```
+
+This should confirm:
+
+- the expected CLI files exist
+- the expected skills exist
+- the packed tarball is clean
+- transient cache files are not shipped
+
+---
+
+## Documentation Rules
+
+- README and getting-started docs should default to packaged CLI usage
+- contributor-only docs may use `node bin/cc-devflow-cli.js ...`
+- `skills.sh` should be documented only as a single-skill distribution path
+- do not describe `.claude/commands/` as required structure
+- do not describe internal runtime helpers as the supported public workflow
+- if a shipped skill changes, update that skill's `version`, local `CHANGELOG.md`, and affected public docs in the same PR
+- keep the workflow story as `cc-roadmap + PDCA/IDCA` visible skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+
+---
+
+## Pull Requests
+
+Good PRs for this repo usually do one of these cleanly:
+
+- improve a skill
+- fix CLI distribution
+- fix compiler/adaptation behavior
+- clean stale docs
+- add focused regression coverage
+
+If a change touches the public surface, update the relevant docs in the same PR.

package/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,195 @@
+# 为 cc-devflow 做贡献
+
+[中文版](./CONTRIBUTING.zh-CN.md) | [English](./CONTRIBUTING.md)
+
+---
+
+请同时阅读 [行为准则](./CODE_OF_CONDUCT.zh-CN.md)。如果你要报告漏洞，请遵循 [安全策略](./SECURITY.zh-CN.md)，不要创建公开 issue。
+
+## 概览
+
+cc-devflow 现在是一个 skills-first 仓库，并且重新带回了可分发的 CLI。
+
+对外可见面只有这些：
+
+- `cc-roadmap`
+- `cc-plan`
+- `cc-investigate`
+- `cc-do`
+- `cc-check`
+- `cc-act`
+- `cc-devflow init`
+- `cc-devflow adapt`
+
+`lib/skill-runtime/` 可以保留共享运行时支撑，但它已经不是用户要直接理解或运行的工作流入口。
+
+仓库里也可以存在维护类 Skill，例如 `cc-spec-init`、`cc-simplify`、`docs-sync`，但它们不改变公开的 `cc-roadmap + PDCA/IDCA` 叙事。
+
+---
+
+## 开发环境
+
+### 前置条件
+
+- Node.js 18+
+- npm
+- Git
+
+### 安装
+
+```bash
+git clone https://github.com/YOUR_USERNAME/cc-devflow.git
+cd cc-devflow
+npm install
+```
+
+### 本地 CLI 冒烟验证
+
+如果你在源码仓库里开发，请使用仓库内入口：
+
+```bash
+node bin/cc-devflow-cli.js --help
+tmpdir=$(mktemp -d)
+node bin/cc-devflow-cli.js init --dir "$tmpdir"
+node bin/cc-devflow-cli.js adapt --cwd "$tmpdir" --platform codex
+rm -rf "$tmpdir"
+```
+
+如果要验证打包后的行为，运行：
+
+```bash
+npm pack
+node scripts/validate-publish.js
+```
+
+---
+
+## 项目结构
+
+```text
+cc-devflow/
+├── .claude/skills/            # 对外分发的 Skill
+├── bin/                       # CLI 入口
+├── config/                    # Adapter 配置
+├── docs/                      # 公开文档
+├── lib/adapters/              # 平台适配层
+├── lib/compiler/              # 多平台编译器
+├── lib/skill-runtime/         # 供 Skill 脚本复用的共享运行时与同目录测试
+├── README.md
+├── README.zh-CN.md
+└── package.json
+```
+
+### 常见贡献区域
+
+- `.claude/skills/`：Skill 行为、资源、引用、脚本
+- `bin/`：可分发 CLI 行为
+- `lib/compiler/`：skills/prompts 解析、转换、emitters、rules 生成
+- `lib/adapters/`：平台 adapter 配置与校验
+- `lib/skill-runtime/`：Skill 脚本复用的共享运行时支撑
+- `docs/`：对外文档
+
+---
+
+## 贡献规则
+
+### 1. 保持对外入口极简
+
+不要再把旧 `/flow:*` 或 `harness:*` CLI 写回新的用户文档。
+
+对外故事应该始终保持为：
+
+- 整包安装：`cc-devflow init`
+- 平台产物：`cc-devflow adapt`
+- 工作流执行：`cc-roadmap + PDCA/IDCA` 可见 Skill
+- capability 真相维护：`cc-spec-init`
+
+### 2. 保持 Skills-First 结构
+
+每个已发布 Skill 都应保持独立目录：
+
+```text
+.claude/skills/<skill>/
+├── SKILL.md
+├── PLAYBOOK.md
+├── assets/
+├── references/
+└── scripts/
+```
+
+如果你改了一个已发布 Skill，要把这些文件当成同一个契约：
+
+- `SKILL.md`
+- 本地 `CHANGELOG.md`
+- 被引用的 `PLAYBOOK.md`、`assets/`、`references/`、`scripts/`
+
+不要只改其中一部分，让其余说明继续过期。
+
+### 3. 保持分发包干净
+
+不要把瞬态文件放进模板或 tarball。
+
+典型脏文件包括：
+
+- `.claude/tsc-cache/`
+- `.DS_Store`
+- 本地编辑器和操作系统产生的垃圾文件
+
+### 4. 让运行时辅助层保持次要
+
+如果你改了 `lib/skill-runtime/`，请保持可测试，但不要再把它写成用户主入口。真正的公开 workflow 仍然属于已发布 Skill。
+
+---
+
+## 测试
+
+### 主测试命令
+
+```bash
+npm test
+```
+
+### CLI 回归测试
+
+```bash
+npm test -- --runInBand lib/skill-runtime/__tests__/cli-bootstrap.integration.test.js
+```
+
+### 发布校验
+
+```bash
+node scripts/validate-publish.js
+```
+
+它应该保证：
+
+- CLI 必需文件存在
+- 关键 Skill 存在
+- 打包 tarball 干净
+- 瞬态缓存不会被分发
+
+---
+
+## 文档规则
+
+- README 和快速开始默认写打包后 CLI 的用法
+- 贡献者文档才写 `node bin/cc-devflow-cli.js ...`
+- `skills.sh` 只作为单 Skill 分发路径来写
+- 不要把 `.claude/commands/` 写成必需结构
+- 不要把内部运行时辅助层写成受支持的公开工作流
+- 如果改了已发布 Skill，在同一个 PR 里同步该 Skill 的 `version`、本地 `CHANGELOG.md` 和受影响的公开文档
+- 主 workflow 仍然只讲 `cc-roadmap + PDCA/IDCA`；`cc-spec-init` / `cc-simplify` 等维护类 Skill 单独说明
+
+---
+
+## Pull Request
+
+这个仓库比较好的 PR，通常会干净地只做一类事：
+
+- 改进某个 Skill
+- 修复 CLI 分发行为
+- 修复编译器 / 适配行为
+- 清理陈旧文档
+- 增加有针对性的回归测试
+
+如果改动触碰了公开入口，记得在同一个 PR 里同步文档。