cc-devflow 4.3.0 → 4.5.0

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/CLAUDE.md

@@ -7,20 +7,24 @@
 ```text
 docs/
 ├── CLAUDE.md
-├── SPEC_KIT_REFERENCE_ANALYSIS.md
-├── SPEC_KIT_ITERATION_BORROWING.md
 ├── commands/
-└── guides/
+├── examples/
+├── guides/
+├── skill-runtime-migration.md
+└── v4.3.0-migration-guide.md
 ```
 
 ## 文件职责（一句话说清）
 
-- `docs/SPEC_KIT_REFERENCE_ANALYSIS.md`: cc-devflow 与 spec-kit 的总体架构/理念/机制对照（静态对比基线）。
-- `docs/SPEC_KIT_ITERATION_BORROWING.md`: 基于 spec-kit 近期迭代（Changelog）的“增量差异”与可借鉴项（动态演进对比）。
+- `docs/commands/`: CLI、分发与平台适配相关文档。
+- `docs/examples/`: 端到端样例与样例绑定真相源。
+- `docs/guides/`: 上手与迁移类说明。
+- `docs/skill-runtime-migration.md`: 旧 runtime 叙事迁移说明。
+- `docs/v4.3.0-migration-guide.md`: 对外版本迁移说明。
 
 ## 编写约定
 
 - 面向使用者：优先写“怎么用/怎么做”，其次再写“为什么”。
 - 可检索：标题清晰、关键词统一（`/flow-*`、`/core-*`、`/speckit.*`）。
 - 可落地：结论必须能映射到具体命令、脚本或模板文件路径。
-
+- change 目录命名必须保留大写逻辑 ID 前缀：`REQ-123-...` 表示需求变更，`FIX-123-...` 表示缺陷修复；描述部分使用 kebab-case。

package/docs/commands/README.md

@@ -1,57 +1,30 @@
-# 📋 Command Reference
+# CLI And Skills
 
-[中文文档](./README.zh-CN.md) | [English](./README.md)
+CC-DevFlow no longer uses the old `/flow:*` command surface as the primary interface.
 
----
+Use the repository CLI for whole-pack setup and platform adaptation:
 
-## 🎯 Requirement Commands
+```bash
+npx cc-devflow init --dir /path/to/your/project
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
 
-| Command | Purpose | Quick Example | Detailed Docs |
-|---------|---------|---------------|---------------|
-| `/flow:init` | 📦 Initialize requirement context | `/flow:init "REQ-123\|Feature"` | [→](../../.claude/commands/flow/init.md) |
-| `/flow:spec` | 📋 Generate task-manifest | `/flow:spec "REQ-123"` | [→](../../.claude/commands/flow/spec.md) |
-| `/flow:dev` | 🛠️ Dispatch or resume task execution | `/flow:dev "REQ-123" --resume` | [→](../../.claude/commands/flow/dev.md) |
-| `/flow:verify` | ✅ Quick/strict quality gates | `/flow:verify "REQ-123" --strict` | [→](../../.claude/commands/flow/verify.md) |
-| `/flow:release` | 🚢 Release + runtime cleanup | `/flow:release "REQ-123"` | [→](../../.claude/commands/flow/release.md) |
-| `/flow:status` | 📊 Query progress snapshot | `/flow:status REQ-123` | [→](../../.claude/commands/flow/status.md) |
-| `/flow:restart` | 🔄 Recover interrupted workflow | `/flow:restart "REQ-123" --from=dev` | [→](../../.claude/commands/flow/restart.md) |
-| `/flow:update` | ✅ Update task progress | `/flow:update "REQ-123" "T001"` | [→](../../.claude/commands/flow/update.md) |
-| `/flow:fix` | 🐛 Bug fix workflow | `/flow:fix "BUG-001\|Description"` | [→](../../.claude/commands/flow/fix.md) |
+Use skills directly for the workflow itself:
 
-## ⚠️ Deprecated Commands
+```text
+cc-roadmap
 
-| Deprecated | Migration |
-|------------|-----------|
-| `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
-| `/flow:clarify` | Use `/flow:spec` |
-| `/flow:checklist` | Use `/flow:verify --strict` |
-| `/flow:quality` | Use `/flow:verify` |
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
+```
 
-## 🏗️ Core Commands
+Use maintenance skills separately when needed:
 
-| Command | Purpose | Quick Example | Detailed Docs |
-|---------|---------|---------------|---------------|
-| `/core:roadmap` | 🗺️ Generate product roadmap | `/core:roadmap` | [→](./core-roadmap.md) |
-| `/core:architecture` | 🏛️ Generate system architecture | `/core:architecture` | [→](./core-architecture.md) |
-| `/core:guidelines` | 📘 Generate project guidelines | `/core:guidelines` | [→](./core-guidelines.md) |
-| `/core:style` | 🎨 Generate style system guide | `/core:style` | [→](./core-style.md) |
+- `cc-spec-init`: bootstrap or repair `devflow/specs/` and `change-meta.json`
+- `cc-simplify`: cleanup pass before ship
 
-## 🎯 Quick Selection Guide
+Use [skills.sh CLI](https://skills.sh/docs/cli) when you only want one skill:
 
-```text
-Your Scenario:
-├─ Start requirement delivery? → /flow:init "REQ-123|Feature|URLs"
-├─ Need executable plan? → /flow:spec "REQ-123"
-├─ Need implementation/resume? → /flow:dev "REQ-123" [--resume]
-├─ Need release gates? → /flow:verify "REQ-123" --strict
-├─ Ready to ship? → /flow:release "REQ-123"
-├─ Check progress? → /flow:status REQ-123
-├─ Fix production bug? → /flow:fix "BUG-001|Description"
-└─ Project-level planning? → /core:roadmap /core:architecture /core:guidelines
+```bash
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
 ```
-
-## 📚 Related Documentation
-
-- [Getting Started Guide](../guides/getting-started.md)
-- [Workflow Guide](../guides/workflow-guide.md)
-- [Best Practices](../guides/best-practices.md)

package/docs/commands/README.zh-CN.md

@@ -1,53 +1,30 @@
-# 📋 命令参考文档
-
-## 🎯 需求命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/flow:init` | 📦 初始化需求上下文 | `/flow:init "REQ-123|功能"` → [详细文档](../../.claude/commands/flow/init.md) |
-| `/flow:spec` | 📋 生成可执行任务清单 | `/flow:spec "REQ-123"` → [详细文档](../../.claude/commands/flow/spec.md) |
-| `/flow:dev` | 🛠️ 分发/恢复任务执行 | `/flow:dev "REQ-123" --resume` → [详细文档](../../.claude/commands/flow/dev.md) |
-| `/flow:verify` | ✅ 执行快速/严格质量闸 | `/flow:verify "REQ-123" --strict` → [详细文档](../../.claude/commands/flow/verify.md) |
-| `/flow:release` | 🚢 发布并清理运行时 | `/flow:release "REQ-123"` → [详细文档](../../.claude/commands/flow/release.md) |
-| `/flow:status` | 📊 查询开发进度 | `/flow:status REQ-123` → [详细文档](../../.claude/commands/flow/status.md) |
-| `/flow:restart` | 🔄 恢复中断工作流 | `/flow:restart "REQ-123" --from=dev` → [详细文档](../../.claude/commands/flow/restart.md) |
-| `/flow:update` | ✅ 更新任务进度 | `/flow:update "REQ-123" "T001"` → [详细文档](../../.claude/commands/flow/update.md) |
-| `/flow:fix` | 🐛 Bug 修复流程 | `/flow:fix "BUG-001\|描述"` → [详细文档](../../.claude/commands/flow/fix.md) |
-
-## ⚠️ 已废弃命令
-
-| 废弃命令 | 迁移路径 |
-|----------|----------|
-| `/flow:new` | `/flow:init -> /flow:spec -> /flow:dev -> /flow:verify -> /flow:release` |
-| `/flow:clarify` | 使用 `/flow:spec` |
-| `/flow:checklist` | 使用 `/flow:verify --strict` |
-| `/flow:quality` | 使用 `/flow:verify` |
-
-## 🏗️ 核心命令
-
-| 命令 | 用途 | 快速示例 |
-|------|------|----------|
-| `/core:roadmap` | 🗺️ 生成产品路线图 | `/core:roadmap` → [详细文档](./core-roadmap.md) |
-| `/core:architecture` | 🏛️ 生成系统架构 | `/core:architecture` → [详细文档](./core-architecture.md) |
-| `/core:guidelines` | 📘 生成项目规范 | `/core:guidelines` → [详细文档](./core-guidelines.md) |
-| `/core:style` | 🎨 生成设计风格指南 | `/core:style` → [详细文档](./core-style.md) |
-
-## 🎯 快速选择指南
+# CLI 与 Skill
+
+CC-DevFlow 不再把旧的 `/flow:*` 命令面当作主要用户接口。
+
+整包安装和多平台适配，使用仓库自带 CLI：
+
+```bash
+npx cc-devflow init --dir /path/to/your/project
+npx cc-devflow adapt --cwd /path/to/your/project --platform codex
+```
+
+真正的工作流直接使用 Skill：
 
 ```text
-你的场景：
-├─ 启动需求交付？ → /flow:init "REQ-123|功能|URLs"
-├─ 生成可执行计划？ → /flow:spec "REQ-123"
-├─ 执行或恢复开发？ → /flow:dev "REQ-123" [--resume]
-├─ 进行发布门禁？ → /flow:verify "REQ-123" --strict
-├─ 准备发布上线？ → /flow:release "REQ-123"
-├─ 检查进度？ → /flow:status REQ-123
-├─ 修复生产 Bug？ → /flow:fix "BUG-001|描述"
-└─ 做项目级规划？ → /core:roadmap /core:architecture /core:guidelines
+cc-roadmap
+
+PDCA: cc-plan -> cc-do -> cc-check -> cc-act
+IDCA: cc-investigate -> cc-do -> cc-check -> cc-act
 ```
 
-## 📚 相关文档
+维护类动作按需单独调用：
+
+- `cc-spec-init`：初始化或修复 `devflow/specs/` 与 `change-meta.json`
+- `cc-simplify`：ship 前做清理和坏味道检查
 
-- [快速开始](../guides/getting-started.md)
-- [工作流指南](../guides/workflow-guide.md)
-- [最佳实践](../guides/best-practices.md)
+如果你只想安装单个 Skill，再使用 [skills.sh CLI](https://skills.sh/docs/cli)：
+
+```bash
+npx skills add https://github.com/Dimon94/cc-devflow --skill cc-roadmap
+```

package/docs/examples/BY-ARTIFACT.md

@@ -0,0 +1,7 @@
+# By Artifact
+
+This page is now a compatibility shortcut.
+
+The canonical one-page entry is [START-HERE.md](./START-HERE.md).
+
+If you only know which file you have in hand, jump to the `By Artifact` section inside [START-HERE.md](./START-HERE.md).

package/docs/examples/README.md

@@ -0,0 +1,38 @@
+# Example Gallery
+
+This page is now a compact list view.
+
+The canonical one-page entry is [START-HERE.md](./START-HERE.md).
+
+Use this page only when you already know you want the short list.
+
+If you need to verify that examples still match the current skill contracts, use [example-bindings.json](./example-bindings.json) and [scripts/check-example-bindings.sh](./scripts/check-example-bindings.sh).
+
+## Available Examples
+
+### 1. Happy Path: tiny-design + `create-pr`
+
+- Path: [./pdca-loop/README.md](./pdca-loop/README.md)
+- Shows:
+  - `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act`
+  - `tiny-design`
+  - `pass`
+  - `create-pr`
+
+### 2. Counterexample: `full-design` + `blocked` + reroute to `cc-plan`
+
+- Path: [./full-design-blocked/README.md](./full-design-blocked/README.md)
+- Shows:
+  - a requirement that was planned too narrowly for the real integration surface
+  - tests may pass, but `cc-check` still returns `blocked`
+  - the correct next move is to reopen planning instead of faking completion
+
+### 3. Counterexample: verified work + `local-handoff`
+
+- Path: [./local-handoff/README.md](./local-handoff/README.md)
+- Shows:
+  - work that is truly verified
+  - a case where remote / PR actions are intentionally skipped
+  - `cc-act` leaving exactly one final handoff file, with `resume-index.md` only for local-handoff
+
+If you need symptom routing or artifact-based lookup, go back to [START-HERE.md](./START-HERE.md).

package/docs/examples/START-HERE.md

@@ -0,0 +1,149 @@
+# Start Here
+
+This is the **single entry page** for the example set.
+
+Use it in any of these situations:
+
+- you want the fastest path to the right example
+- you only know your current symptom
+- you only know which artifact file you have
+- you want one-page context before diving into the examples
+
+## Version Trust
+
+Examples are pinned to current skill versions through:
+
+- [example-bindings.json](./example-bindings.json): canonical bindings for example-to-skill versions
+- [scripts/check-example-bindings.sh](./scripts/check-example-bindings.sh): verifies the bindings against current `SKILL.md` versions and example artifacts
+
+For day-to-day work, the shortest habit is:
+
+```bash
+npm run verify
+```
+
+For publish-grade validation, use:
+
+```bash
+npm run verify:publish
+```
+
+## Fast Route
+
+### 1. Do you already have a `report-card.json` verdict?
+
+- If **no**, start with [the happy path example](./pdca-loop/README.md) to understand the full loop once.
+- If **yes**, continue below.
+
+### 2. Is the verdict `pass`?
+
+- If **no**, go to [the full-design blocked example](./full-design-blocked/README.md).
+  It shows the most important non-happy-path truth:
+  green tests do not override a broken planning contract.
+- If **yes**, continue below.
+
+### 3. Can you honestly create or update a PR right now?
+
+- If **yes**, go to [the happy path example](./pdca-loop/README.md).
+  That sample ends in `create-pr`.
+- If **no**, go to [the local-handoff example](./local-handoff/README.md).
+  That sample shows how verified work still leaves a clean next entry without pretending to ship.
+
+## Symptom Picker
+
+| If your situation feels like this | Read this example first | Why |
+| --- | --- | --- |
+| "I just want to understand the normal loop once." | [pdca-loop](./pdca-loop/README.md) | shows the straight-through path |
+| "The code is locally green, but I don't trust the requirement anymore." | [full-design-blocked](./full-design-blocked/README.md) | shows `blocked` + reroute to `cc-plan` |
+| "The work is verified, but I can't or shouldn't push yet." | [local-handoff](./local-handoff/README.md) | shows `pass` + `local-handoff` |
+| "I don't know whether this should stay `tiny-design`." | [pdca-loop](./pdca-loop/README.md), then [full-design-blocked](./full-design-blocked/README.md) | compare a truly small patch against a requirement that outgrew it |
+
+## By Artifact
+
+Use this when the only thing you know is the file in front of you.
+
+| If the main file you have is... | You are probably here | Read this first |
+| --- | --- | --- |
+| `ROADMAP.md` | `cc-roadmap` | [pdca-loop/ROADMAP.md](./pdca-loop/ROADMAP.md) |
+| `roadmap-tracking.json` | `cc-roadmap` machine truth source for roadmap + backlog | [pdca-loop/roadmap-tracking.json](./pdca-loop/roadmap-tracking.json) |
+| `BACKLOG.md` | `cc-roadmap` -> `cc-plan` handoff | [pdca-loop/BACKLOG.md](./pdca-loop/BACKLOG.md) |
+| `design.md` | `cc-plan` | [pdca-loop/design.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/design.md) or [full-design-blocked/design.md](./full-design-blocked/changes/REQ-002-bulk-invite-import/planning/design.md) |
+| `tasks.md` | `cc-plan` or `cc-do` | [pdca-loop/tasks.md](./pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md) |
+| `task-manifest.json` | `cc-do` | [pdca-loop/task-manifest.json](./pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json) |
+| `report-card.json` | `cc-check` | [pdca-loop/report-card.json](./pdca-loop/changes/REQ-001-copy-invite-link/review/report-card.json), [full-design-blocked/report-card.json](./full-design-blocked/changes/REQ-002-bulk-invite-import/review/report-card.json), or [local-handoff/report-card.json](./local-handoff/changes/REQ-003-audit-log-export/review/report-card.json) |
+| `pr-brief.md` | `cc-act` | [pdca-loop/pr-brief.md](./pdca-loop/changes/REQ-001-copy-invite-link/handoff/pr-brief.md) |
+| `resume-index.md` | `cc-act` with `local-handoff` | [local-handoff/resume-index.md](./local-handoff/changes/REQ-003-audit-log-export/handoff/resume-index.md) |
+
+### Read `report-card.json` Like This
+
+| Verdict | Reroute | Meaning |
+| --- | --- | --- |
+| `pass` | `none` | move toward `cc-act` |
+| `fail` | `cc-do` | implementation must continue |
+| `blocked` | `cc-do` | proof or execution prerequisites are missing |
+| `blocked` | `cc-plan` | design or scope truth is broken; do not keep coding blindly |
+
+### Read `resume-index.md` Like This
+
+Ask only:
+
+1. is verification already `pass`?
+2. is the blocker environmental instead of design-related?
+
+If both are true, you are usually in `cc-act` local handoff territory, not back in planning.
+
+## Example Map
+
+### 1. Happy Path: `tiny-design` + `pass` + `create-pr`
+
+- Read: [pdca-loop/README.md](./pdca-loop/README.md)
+- Best when:
+  - you want to understand the straight-through loop once
+  - you need a clean example of `cc-roadmap -> cc-plan -> cc-do -> cc-check -> cc-act`
+
+### 2. Counterexample: `full-design` + `blocked` + reroute to `cc-plan`
+
+- Read: [full-design-blocked/README.md](./full-design-blocked/README.md)
+- Best when:
+  - tests are green but the requirement still feels untrustworthy
+  - you need to see why `cc-check` can honestly block even after execution work happened
+
+### 3. Counterexample: `pass` + `local-handoff`
+
+- Read: [local-handoff/README.md](./local-handoff/README.md)
+- Best when:
+  - the work is verified
+  - but PR or remote actions are intentionally unavailable
+  - and you need a clean next-entry handoff instead of fake shipping
+
+## Wrong Turns To Avoid
+
+- Do not jump from `tasks.md` straight to `cc-act`
+- Do not treat green tests as stronger than a `report-card.json` reroute
+- Do not treat `resume-index.md` as proof that planning failed; it may simply mean local handoff
+
+## One-Minute Rule
+
+If you only have one minute, open these files in order:
+
+1. example `README.md`
+2. change `planning/design.md`
+3. `report-card.json` or the single final handoff file
+
+That should already tell you:
+
+- what planning density was chosen
+- whether verification passed, failed, or blocked
+- why `cc-act` selected the final ship mode
+
+## Minimal Output Rule
+
+`devflow/changes/<change>/` should stay lean.
+
+- Durable truth only: `change-state.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file.
+- Runtime scratch belongs in `devflow/workspaces/<change>/`, not beside the durable record.
+
+## If You Still Want The Split Views
+
+- [README.md](./README.md): compact example list
+- [BY-ARTIFACT.md](./BY-ARTIFACT.md): compatibility page for artifact-only lookup

package/docs/examples/example-bindings.json

@@ -0,0 +1,38 @@
+{
+  "updatedAt": "2026-04-27",
+  "skills": {
+    "cc-roadmap": "4.3.2",
+    "cc-plan": "3.5.4",
+    "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": [
+    {
+      "id": "pdca-loop",
+      "readme": "docs/examples/pdca-loop/README.md",
+      "root": "docs/examples/pdca-loop",
+      "changeDir": "docs/examples/pdca-loop/changes/REQ-001-copy-invite-link",
+      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "expectedShipMode": "create-pr"
+    },
+    {
+      "id": "full-design-blocked",
+      "readme": "docs/examples/full-design-blocked/README.md",
+      "root": "docs/examples/full-design-blocked",
+      "changeDir": "docs/examples/full-design-blocked/changes/REQ-002-bulk-invite-import",
+      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check"],
+      "expectedShipMode": "none"
+    },
+    {
+      "id": "local-handoff",
+      "readme": "docs/examples/local-handoff/README.md",
+      "root": "docs/examples/local-handoff",
+      "changeDir": "docs/examples/local-handoff/changes/REQ-003-audit-log-export",
+      "covers": ["cc-roadmap", "cc-plan", "cc-do", "cc-check", "cc-act"],
+      "expectedShipMode": "local-handoff"
+    }
+  ]
+}

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

@@ -0,0 +1,45 @@
+# BACKLOG
+
+## Backlog Meta
+
+- Roadmap version: `roadmap.v2`
+- Skill version: `4.3.2`
+- Last synced: `2026-04-19`
+- Current focus stage: `Stage 2`
+- Tracking source: `roadmap-tracking.json`
+
+## Queue
+
+| RM-ID | Title | Source Stage | Priority | Primary Capability | Secondary Capabilities | Capability Gap | Expected Spec Delta | Evidence | Depends On | Parallel With | Unknowns | Next Decision | Ready |
+|------|------|------|------|------|------|------|------|------|------|------|------|------|------|
+| RM-010 | Add CSV bulk invite import for admins | Stage 2 | P1 | cap-bulk-invite-import | cap-workspace-membership | admins can invite one user at a time but cannot safely import invite batches | define import semantics before widening current truth | sales onboarding asks for spreadsheet-scale invites | - | - | duplicate-email policy, seat enforcement, audit fan-out | reroute to full design before more execution work | Yes |
+
+## Dependency Handoff
+
+- Serial spine: RM-010
+- Parallel-ready next wave: -
+- Notes on blockers: verification is blocked until the import contract covers limits, duplicates, billing, and audit consistency
+
+## Ready For Req-Plan
+
+- RM-010:
+  - Primary Capability: `cap-bulk-invite-import`
+  - Secondary Capabilities: `cap-workspace-membership`
+  - Why now: demand is real, but the contract is too wide to keep improvising in code
+  - Success signal: the capability has a trusted import contract before implementation resumes
+  - Entry constraints: must freeze limits, duplicates, warnings, and audit behavior first
+  - Capability gap: admins can invite one user at a time but cannot safely import invite batches
+  - Expected spec delta: define import semantics before widening current truth
+  - Open risks: another partial implementation pass would deepen the semantic drift
+  - First planning question: which subflows share one import contract and which need explicit splits?
+  - Required context to load: invite limits, billing rules, duplicate handling, audit logging
+  - Depends On: `-`
+  - Parallel With: `-`
+  - Why this is ready now: the blocker is design truth, not implementation effort
+
+## Parked
+
+- RM-XXX:
+  - Reason parked:
+  - Trigger to reopen:
+  - Missing evidence:

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

@@ -0,0 +1,55 @@
+# Full-Design Blocked Example
+
+## Example Meta
+
+- Example version: `1.0.0`
+- Last reviewed: `2026-04-17`
+- Bound skills: `cc-roadmap@4.3.2`, `cc-plan@3.5.4`, `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`.
+
+The shape is intentional:
+
+- roadmap item is real enough to matter
+- design requires `full-design`
+- tasks were executed far enough to produce evidence
+- `report-card.json` is still `blocked`
+- reroute is `cc-plan`, not `cc-do`
+
+## Scenario
+
+The fictional product now wants CSV-based bulk invites for workspace admins.
+
+At first glance, it looks like an import feature inside the admin console.
+
+But the real surface is wider:
+
+- invite limit enforcement
+- duplicate email handling
+- billing-seat warnings
+- audit log consistency
+
+The sample shows what happens when implementation moved before the integration design was fully trustworthy.
+
+## What To Look For
+
+1. Why this requirement cannot stay `tiny-design`
+2. Which signals forced `full-design`
+3. Why tests passing is still not enough
+4. Why reroute goes to `cc-plan` instead of `cc-do`
+
+## Artifact Map
+
+- `ROADMAP.md`
+- `roadmap-tracking.json` (shared roadmap/backlog truth)
+- `BACKLOG.md`
+- `changes/REQ-002-bulk-invite-import/planning/design.md`
+- `changes/REQ-002-bulk-invite-import/planning/tasks.md`
+- `changes/REQ-002-bulk-invite-import/planning/task-manifest.json`
+- `changes/REQ-002-bulk-invite-import/review/report-card.json`
+
+## Why There Is No `cc-act` Output
+
+There is no final handoff file here because `cc-check` did **not** return `pass`.
+
+The loop must stop honestly before `cc-act`.

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

@@ -0,0 +1,53 @@
+# ROADMAP
+
+## Roadmap Meta
+
+- Roadmap version: `roadmap.v2`
+- Skill version: `4.3.2`
+- Status: `active`
+- Last updated: `2026-04-16`
+- Owner / decider: `product-owner`
+- Current focus stage: `Stage 2`
+- Confidence: `medium`
+- Supersedes roadmap version: `roadmap.v1`
+
+## Context Snapshot
+
+- Product / repo: `workspace-lite`
+- Project stage: teams actively collaborate after the first-share fixes
+- Users: workspace admins managing larger invite waves
+- Pain: inviting many users one by one is slow and error-prone
+- Existing workaround: admins repeatedly paste emails or use external spreadsheets
+- Strongest demand evidence: support calls now ask for admin-scale invite workflows
+- Why now: the product graduated past the first-share bottleneck
+- Distribution path: direct beta expansion to larger teams
+- Deadline / forcing function: larger-team beta starts on `2026-04-30`
+- Team / capacity: one engineer plus part-time design help
+- Hard constraints: billing and audit behavior must remain trustworthy
+- Adoption / trust bottleneck: admins will not trust bulk invite if seat usage and audit logs drift
+- Known unknowns: how duplicate users, seat limits, and partial imports should behave
+
+## Route Options
+
+| Shape | Why this could work | Why this may fail | Decision |
+|-------|---------------------|-------------------|----------|
+| wedge-first | deliver a minimal CSV import | may hide dangerous admin edge cases | Rejected |
+| platform-first | design import rules, billing boundaries, and audit consistency first | slower upfront | Recommended |
+| rescue-first | keep manual import and patch docs | does not solve admin pain | Rejected |
+
+## Recommended Route
+
+- Recommendation: `platform-first`
+- Why this route wins now: the biggest risk is trust and consistency, not button placement
+- Why the rejected routes lose now: a superficially small import flow can corrupt admin expectations if rules are underspecified
+- First signal to watch: admins can predict what happens for duplicates, seat limits, and partial success
+- Kill signal / stop condition: if the team cannot specify bulk invite semantics before implementation starts
+
+## Implementation Tracking
+- Tracking source: `roadmap-tracking.json`
+
+<!-- roadmap-tracking:start -->
+| RM-ID | Item | Stage | Priority | Primary Capability | Secondary Capabilities | Expected Spec Delta | Depends On | Status | REQ | Progress |
+|------|------|------|------|------|------|------|------|------|------|------|
+| RM-010 | Add CSV bulk invite import for admins | Stage 2 | P1 | cap-bulk-invite-import | cap-workspace-membership | define import semantics before widening current truth | - | Verification blocked | REQ-002 | 80% |
+<!-- roadmap-tracking:end -->