cc-devflow 4.5.11 → 4.5.12

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

@@ -4,7 +4,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.9.2`
+- CC-Plan skill version: `3.10.1`
 - Work branch: `REQ/001-copy-invite-link`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
@@ -45,20 +45,25 @@
 ClaudeCode / Codex 执行本计划时，必须把本文件当成任务模板合同，而不是普通 TODO 列表。
 
 - Template source: `assets/TASKS_TEMPLATE.md`
-- Context index first: run `cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact` before opening deep sections; use `packetOnly` plus `mustNotForget` first, verify `sourceHashes`, open `defaultOpen` refs only when needed, and reserve `deepOpen` for matching `openWhen.conditions`.
-- Task selection: read `planning/task-manifest.json.currentTaskId`; if empty, run the ready-task selector before choosing work.
+- CLI resolver: all workflow commands must run through `.claude/skills/cc-dev/scripts/resolve-cc-devflow.sh` or `.codex/skills/cc-dev/scripts/resolve-cc-devflow.sh`; if it cannot prove `query workflow-context` and `next-change-key`, stop blocked.
+- Context first: run resolved CLI `query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact` before opening deep sections.
+- Task selection: use `scripts/select-ready-tasks.sh --tasks devflow/changes/<change-key>/task.md`.
 - Task block rule: read the full task block before coding; title-only execution is invalid.
-- Completion rule: after verification and review gates pass, run the completion script; do not manually edit checkbox, status, or `currentTaskId`.
-- Completion failure: if the script fails, fix the missing review / dependency evidence and rerun it. Do not bypass it by editing JSON or Markdown.
+- Completion rule: after verification and review gates pass, run `scripts/mark-task-complete.sh --tasks devflow/changes/<change-key>/task.md --task <task-id>`.
+- Runtime file ban: do not generate process files beyond this `task.md`.
 
 ```bash
-cc-devflow query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compact
-SCRIPT_ROOT=".claude/skills/cc-do/scripts"
+DEVFLOW=".claude/skills/cc-dev/scripts/resolve-cc-devflow.sh"
+if [[ ! -f "$DEVFLOW" && -f ".codex/skills/cc-dev/scripts/resolve-cc-devflow.sh" ]]; then
+  DEVFLOW=".codex/skills/cc-dev/scripts/resolve-cc-devflow.sh"
+fi
+bash "$DEVFLOW" require query workflow-context next-change-key
+bash "$DEVFLOW" query workflow-context --change <changeId> --change-key <changeKey> --cwd <repo-root> --data-only --no-trace --compactSCRIPT_ROOT=".claude/skills/cc-do/scripts"
 if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then
   SCRIPT_ROOT=".codex/skills/cc-do/scripts"
 fi
-bash "$SCRIPT_ROOT/select-ready-tasks.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json
-bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md --task <task-id>
+bash "$SCRIPT_ROOT/select-ready-tasks.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/
+bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/ --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/task.md --task <task-id>
 ```
 
 ## Phase 1: Foundation
@@ -70,7 +75,7 @@ bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/cha
   Read first: `design.md`, `src/features/share/ShareDialog.tsx`
   Verification: `npm test -- src/features/share/ShareDialog.test.tsx`
   Evidence: failing output that shows the missing button / action
-  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md --task T001`; do not hand-edit status.
+  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/ --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/task.md --task T001`; do not hand-edit status.
   Test seam: share dialog UI behavior
   Public verification path: Run the share dialog test and observe the copy action through the rendered dialog
   Allowed mocks: clipboard boundary
@@ -83,7 +88,7 @@ bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/cha
   Read first: `design.md`, `src/features/share/ShareDialog.test.tsx`
   Verification: `npm test -- src/features/share/ShareDialog.test.tsx`
   Evidence: passing output + review notes
-  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md --task T002`; do not hand-edit status.
+  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/ --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/task.md --task T002`; do not hand-edit status.
   Test seam: share dialog UI behavior
   Public verification path: Run the share dialog test and observe the copy action through the rendered dialog
   Allowed mocks: clipboard boundary
@@ -95,12 +100,12 @@ bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/cha
   Goal: 为 `cc-check` 准备本次实现的真实验证证据。
   TDD phase: evidence
   Files: `src/features/share/ShareDialog.tsx`, `src/features/share/ShareDialog.test.tsx`
-  Read first: `tasks.md`, `task-manifest.json`
+  Read first: `task.md`
   Verification:
   - `npm test -- src/features/share/ShareDialog.test.tsx`
   - `npm run lint -- src/features/share/ShareDialog.tsx`
   Evidence: passing test output + clean lint output
-  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/tasks.md --task T003`; do not hand-edit status.
+  Completion: after verification evidence and required review records exist, run `SCRIPT_ROOT=".claude/skills/cc-do/scripts"; if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then SCRIPT_ROOT=".codex/skills/cc-do/scripts"; fi; bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/ --tasks docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/task.md --task T003`; do not hand-edit status.
   Test seam: share dialog UI behavior
   Public verification path: Run the share dialog test and observe the copy action through the rendered dialog
   Allowed mocks: clipboard boundary

package/docs/examples/scripts/check-example-bindings.sh

@@ -17,11 +17,6 @@ fi
 skill_version() {
   local skill="$1"
   local file="$ROOT_DIR/.claude/skills/$skill/SKILL.md"
-  if [[ ! -f "$file" ]]; then
-    echo "Missing skill file: $file" >&2
-    exit 1
-  fi
-
   sed -n 's/^version: //p' "$file" | head -n 1
 }
 
@@ -35,27 +30,15 @@ assert_contains() {
 }
 
 ROADMAP_VERSION="$(skill_version cc-roadmap)"
-NEXT_VERSION="$(skill_version cc-next)"
-DEV_VERSION="$(skill_version cc-dev)"
 REQ_PLAN_VERSION="$(skill_version cc-plan)"
-INVESTIGATE_VERSION="$(skill_version cc-investigate)"
 REQ_DO_VERSION="$(skill_version cc-do)"
-REQ_REVIEW_VERSION="$(skill_version cc-review)"
-PR_REVIEW_VERSION="$(skill_version cc-pr-review)"
-PR_LAND_VERSION="$(skill_version cc-pr-land)"
 REQ_CHECK_VERSION="$(skill_version cc-check)"
 REQ_ACT_VERSION="$(skill_version cc-act)"
 
 for pair in \
   "cc-roadmap:$ROADMAP_VERSION" \
-  "cc-next:$NEXT_VERSION" \
-  "cc-dev:$DEV_VERSION" \
   "cc-plan:$REQ_PLAN_VERSION" \
-  "cc-investigate:$INVESTIGATE_VERSION" \
   "cc-do:$REQ_DO_VERSION" \
-  "cc-review:$REQ_REVIEW_VERSION" \
-  "cc-pr-review:$PR_REVIEW_VERSION" \
-  "cc-pr-land:$PR_LAND_VERSION" \
   "cc-check:$REQ_CHECK_VERSION" \
   "cc-act:$REQ_ACT_VERSION"
 do
@@ -73,11 +56,10 @@ while IFS= read -r encoded; do
   readme="$ROOT_DIR/$(jq -r '.readme' <<<"$encoded")"
   root="$ROOT_DIR/$(jq -r '.root' <<<"$encoded")"
   change_dir="$ROOT_DIR/$(jq -r '.changeDir' <<<"$encoded")"
-  planning_dir="$change_dir/planning"
-  review_dir="$change_dir/review"
+  task_file="$change_dir/task.md"
   handoff_dir="$change_dir/handoff"
 
-  for file in "$readme" "$root/ROADMAP.md" "$root/BACKLOG.md" "$root/roadmap.json" "$planning_dir/design.md" "$planning_dir/tasks.md" "$planning_dir/task-manifest.json"; do
+  for file in "$readme" "$root/ROADMAP.md" "$root/BACKLOG.md" "$root/roadmap.json" "$task_file"; do
     if [[ ! -f "$file" ]]; then
       echo "Example $example_id is missing required file: $file" >&2
       exit 1
@@ -85,40 +67,14 @@ while IFS= read -r encoded; do
   done
 
   assert_contains "$root/ROADMAP.md" "- Skill version: \`$ROADMAP_VERSION\`"
-  assert_contains "$root/ROADMAP.md" "- Roadmap state source: \`roadmap.json\`"
-  assert_contains "$root/ROADMAP.md" "## Technical Architecture"
-  assert_contains "$root/ROADMAP.md" "\`\`\`mermaid"
   assert_contains "$root/BACKLOG.md" "- Skill version: \`$ROADMAP_VERSION\`"
-  assert_contains "$root/BACKLOG.md" "> Deprecated projection. Edit \`roadmap.json\` instead."
-  assert_contains "$root/BACKLOG.md" "- Roadmap state source: \`roadmap.json\`"
-  assert_contains "$root/BACKLOG.md" "| RM-ID | Title | Source Stage | Priority | Primary Capability | Secondary Capabilities | Capability Gap | Expected Spec Delta | Evidence | Depends On | Parallel With | Unknowns | Next Decision | Ready |"
-  assert_contains "$root/BACKLOG.md" "## Ready For Req-Plan"
-  assert_contains "$root/BACKLOG.md" "  - Primary Capability:"
-  assert_contains "$root/BACKLOG.md" "  - Expected spec delta:"
-  jq -er '.version == 3 and (.items | length) > 0 and (.meta | type == "object") and (.handoff | type == "object") and (.architecture.nodes | length) > 0 and any(.items[]; .backlog != null)' "$root/roadmap.json" >/dev/null
-  assert_contains "$planning_dir/design.md" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
-  assert_contains "$planning_dir/tasks.md" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
-
-  jq -er --arg roadmap "$ROADMAP_VERSION" --arg reqplan "$REQ_PLAN_VERSION" '
-    (.planningMeta.reqPlanSkillVersion // $reqplan) == $reqplan and
-    (.status? == null) and
-    (.activePhase? == null) and
-    (.sourceRoadmap? == null) and
-    (.spec? == null) and
-    (.executionProtocol? == null) and
-    (.planningMeta.requirementBrief? == null) and
-    (.planningMeta.ambiguityGate? == null) and
-    (.planningMeta.reviewLoop? == null) and
-    all(.tasks[]; (.completion? == null) and (.tddPhase | type == "string") and (.testSeam.publicVerificationPath | type == "string"))
-  ' "$planning_dir/task-manifest.json" >/dev/null
-
-  assert_contains "$planning_dir/tasks.md" "## Execution Protocol"
-  assert_contains "$planning_dir/tasks.md" "cc-devflow query workflow-context"
-  assert_contains "$planning_dir/tasks.md" "--data-only --no-trace --compact"
-  assert_contains "$planning_dir/tasks.md" "mark-task-complete.sh"
-  assert_contains "$planning_dir/tasks.md" "TDD phase:"
-  assert_contains "$planning_dir/tasks.md" "Completion:"
-  assert_contains "$planning_dir/tasks.md" "Public verification path:"
+  assert_contains "$task_file" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
+  assert_contains "$task_file" "## Execution Protocol"
+  assert_contains "$task_file" "task.md"
+  assert_contains "$task_file" "mark-task-complete.sh"
+  assert_contains "$task_file" "TDD phase:"
+  assert_contains "$task_file" "Completion:"
+  assert_contains "$task_file" "Public verification path:"
 
   assert_contains "$readme" "## Example Meta"
   assert_contains "$readme" "\`cc-roadmap@$ROADMAP_VERSION\`"
@@ -128,15 +84,8 @@ while IFS= read -r encoded; do
 
   if jq -e '.covers | index("cc-act")' <<<"$encoded" >/dev/null; then
     assert_contains "$readme" "\`cc-act@$REQ_ACT_VERSION\`"
-  fi
-
-  if [[ -f "$review_dir/report-card.json" ]]; then
-    "$ROOT_DIR/.claude/skills/cc-check/scripts/verify-gate.sh" --report "$review_dir/report-card.json" >/dev/null
-  fi
-
-  if jq -e '.covers | index("cc-act")' <<<"$encoded" >/dev/null; then
-    if [[ ! -f "$handoff_dir/pr-brief.md" && ! -f "$handoff_dir/resume-index.md" && ! -f "$handoff_dir/release-note.md" && ! -f "$handoff_dir/status.md" ]]; then
-      echo "Example $example_id is missing a final handoff file under $handoff_dir" >&2
+    if [[ ! -f "$handoff_dir/pr-brief.md" ]]; then
+      echo "Example $example_id is missing PR file: $handoff_dir/pr-brief.md" >&2
       exit 1
     fi
   fi

package/docs/guides/artifact-contract.md

@@ -1,48 +1,18 @@
 # Artifact Contract
 
-cc-devflow artifacts follow two rules: progressive disclosure and one state owner.
-Machine JSON has a third rule: it is CLI-owned. Agents write the human contract
-in `planning/tasks.md`, then run `cc-devflow task-contract compile` / `validate`;
-they must not handwrite `task-manifest.json` or `change-meta.json`.
+cc-devflow keeps the workflow surface intentionally small.
 
-## Progressive Disclosure
+## Durable Files
 
-Every skill output should have a default path and deeper layers.
+- `devflow/changes/<change-key>/task.md`
+- `devflow/changes/<change-key>/handoff/pr-brief.md` when PR or local handoff needs it
+- `devflow/postmortems/incidents/<date>-<change-key>.md` when a FIX or recurring failure needs a postmortem
+- `devflow/postmortems/INDEX.md` as the postmortem index
 
-- Default layer: the next actor can see the current state, next action, and proof source quickly.
-- Conditional layer: open only when scope, dependency, review, or conflict questions arise.
-- Deep layer: full evidence, reasoning, or historical review, opened only for audit or recovery.
+## State Source
 
-If a field has no clear opener and no downstream consumer, remove it.
+Git records process history. Commit after each completed PDCA or IDCA environment/stage.
 
-## State Owners
+## Retired Surface
 
-| State | Owner artifact | Projection / derived readers |
-| --- | --- | --- |
-| Roadmap item status and progress | `devflow/roadmap.json` | `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, handoff summaries |
-| Capability/spec sync state | `devflow/changes/<change-key>/change-meta.json` | `planning/tasks.md`, `review/report-card.json`, handoff summaries |
-| Execution task status | `planning/task-manifest.json.tasks[].status` | `planning/tasks.md` checkboxes, recovery summaries |
-| Ready task / phase | derived from `tasks[].status`, `tasks[].phase`, and `tasks[].dependsOn` | `currentTaskId` cache, ready-task selector output |
-| Runtime event log | `execution/tasks/<task-id>/events.jsonl` only for debug/failed runs | recovery summaries |
-| Review verdict | `review/report-card.json.verdict` | PR brief, release note, act gate |
-| PR / remote queue truth | live GitHub API / `gh` output | local review notes and handoff summaries |
-| Project postmortem facts and principles | `devflow/postmortems/` | planning recall, investigation hypotheses, task guardrails |
-
-## Duplication Rules
-
-- Machine artifacts may reference another owner by id or path, but must not copy its status lifecycle.
-- Markdown projections must state their source instead of becoming editable truth.
-- Derived fields must be described as derived/cache and must be recomputable.
-- A skill must not create a new status field unless it also names the owner, lifecycle, projection readers, and validation gate.
-- Task manifests must not duplicate PRD narrative, review-loop prose, source-trust details, completion shell commands, roadmap progress, or spec sync status.
-- Task manifests and change metadata must be generated or refreshed by CLI/template tooling, not manually edited as process notes.
-- Project postmortems must cite stronger owner artifacts and Git evidence; they do not own roadmap progress, task status, review verdicts, or spec sync state.
-
-## Required Check
-
-Before changing any skill output, answer:
-
-1. Who owns this state?
-2. Is this field consumed directly, or is it a projection?
-3. Can it be recomputed from a stronger source?
-4. What validation fails if this state diverges?
+Do not create process JSON, review ledgers, report cards, status files, resume files, release notes, or principle files.

package/docs/guides/getting-started.md

@@ -86,20 +86,20 @@ Use the skills in this order:
 Typical outputs:
 
 - `cc-roadmap` writes `devflow/roadmap.json` as the editable roadmap truth, then generates `devflow/ROADMAP.md` and deprecated `devflow/BACKLOG.md`
-- `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
-- `cc-plan` writes `planning/tasks.md#Contract Summary`, then CLI-generates `task-manifest.json` and `change-meta.json`
-- `cc-investigate` writes `planning/tasks.md#Root Cause Contract`, then CLI-generates `task-manifest.json` and `change-meta.json`
-- `cc-review` writes `review-ledger.jsonl`, optional `review-findings.json`, and Markdown reports only when rendered on demand
-- `cc-check` writes `report-card.json`
-- `cc-act` writes exactly one final handoff file: `handoff/pr-brief.md`, `handoff/resume-index.md`, or `handoff/release-note.md`
+- `cc-spec-init` writes `devflow/specs/INDEX.md` and capability specs
+- `cc-plan` writes `task.md#Contract Summary`
+- `cc-investigate` writes `task.md#Root Cause Contract`
+- `cc-review` reports concrete findings in the response; it does not write review process files
+- `cc-check` reports verification facts in the response, PR brief, or Git commit
+- `cc-act` writes exactly one final PR file, `handoff/pr-brief.md`, or incident postmortem files when a real incident needs a corpse report
 
 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` 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 CLI-generated `change-meta.json`, `planning/tasks.md`, CLI-generated `task-manifest.json`, review ledger/findings records, optional CLI logs for debug/failure, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`. Do not generate task `context.md`, `checkpoint.json`, or AI-written process files.
-- Machine JSON is CLI-owned: run `cc-devflow task-contract compile` / `validate`; do not handwrite `task-manifest.json` or `change-meta.json`.
+- Keep `task.md`, optional `handoff/pr-brief.md`, and incident postmortem files under each `devflow/changes/<change>/`. Do not generate task `context.md`, `checkpoint.json`, review ledgers, status/resume files, release notes, principle files, or AI-written process files.
+- Workflow state is Git-owned: keep `task.md`, commit each completed stage, and do not create process JSON.
 - Legacy `planning/design.md`, `planning/analysis.md`, and `cc-review-*.md` are readable fallback inputs for older changes, not new default writes.
 - Worker prompts, journals, assignments, and session logs belong under `devflow/workspaces/<change>/` as ephemeral scratch.
 

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

@@ -86,19 +86,19 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 常见产物：
 
 - `cc-roadmap` 产出可编辑真相 `devflow/roadmap.json`，再生成 `devflow/ROADMAP.md` 和 deprecated `devflow/BACKLOG.md`
-- `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
-- `cc-plan` 产出 `planning/tasks.md#Contract Summary`，再由 CLI 生成 `task-manifest.json` 和 `change-meta.json`
-- `cc-investigate` 产出 `planning/tasks.md#Root Cause Contract`，再由 CLI 生成 `task-manifest.json` 和 `change-meta.json`
-- `cc-review` 产出 `review-ledger.jsonl`、可选 `review-findings.json`，Markdown 报告只在需要时按需渲染
-- `cc-check` 产出 `report-card.json`
-- `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
+- `cc-spec-init` 产出 `devflow/specs/INDEX.md` 和 capability spec
+- `cc-plan` 产出 `task.md#Contract Summary`
+- `cc-investigate` 产出 `task.md#Root Cause Contract`
+- `cc-review` 在当前回复里报告具体问题，不写 review 过程文件
+- `cc-check` 在当前回复、PR 文件或 Git commit 里记录验证事实
+- `cc-act` 只产出最终 PR 文件 `handoff/pr-brief.md`；真实事故需要尸检时才产出 incident postmortem 文件
 
 durable truth 分两层：
 
 - `devflow/specs/`：capability 真相，保留 `INDEX.md` 与 `capabilities/*.md`
 - 新 change 目录必须命名为 `REQ-<number>-<description>`（需求）或 `FIX-<number>-<description>`（修复）；`REQ` 和 `FIX` 分别维护自己的递增编号，跨前缀同号不是冲突；并行工作树造成重复编号时，完整 change key 的描述负责区分业务内容，旧小写目录只作为历史兼容读取。
-- `devflow/changes/<change>/`：变更真相，保留 CLI 生成的 `change-meta.json`、`planning/tasks.md`、CLI 生成的 `task-manifest.json`、review ledger / findings 记录、debug / failed 的可选 CLI 日志、`report-card.json` 和唯一的最终 handoff 文件。不要生成任务级 `context.md`、`checkpoint.json` 或 AI 手写过程文件。
-- 机器态 JSON 归 CLI 所有：运行 `cc-devflow task-contract compile` / `validate`；不要手写 `task-manifest.json` 或 `change-meta.json`。
+- `devflow/changes/<change>/`：变更真相，只保留 `task.md`、可选 `handoff/pr-brief.md`，以及真实事故需要的尸检文件。不要生成任务级 `context.md`、`checkpoint.json`、review ledger、status/resume 文件、release note、principles 或 AI 手写过程文件。
+- 流程状态归 Git：保留 `task.md`，每个完成阶段提交 commit，不创建过程 JSON。
 - 历史 `planning/design.md`、`planning/analysis.md` 和 `cc-review-*.md` 是旧 change 的可读 fallback，不再是新默认写入。
 - worker prompt、journal、assignment、session log 统一放到 `devflow/workspaces/<change>/`，作为 ephemeral scratch。
 

package/docs/guides/minimize-artifacts.md

@@ -1,137 +1,23 @@
-# Minimized Workflow Artifacts
+# Minimize Artifacts
 
-This guide describes the default artifact contract for new cc-devflow changes.
-The goal is simple: keep durable workflow truth readable, small, and measurable.
+The workflow is intentionally Git-first.
 
-## Default Shape
+## Keep
 
-Each new change keeps durable truth under `devflow/changes/<change-key>/`.
+- `task.md`
+- `handoff/pr-brief.md` when a PR or local handoff needs it
+- incident postmortem when a FIX or recurring failure needs it
 
-Default human-authored Markdown:
+## Do Not Keep
 
-- `planning/tasks.md`
+- process JSON
+- review ledgers or finding files
+- report cards
+- status or resume files
+- release notes
+- principles files
+- task context or checkpoint files
 
-Default CLI-owned machine records:
+## Commit Rule
 
-- `change-meta.json`
-- `planning/task-manifest.json`
-- `review/review-ledger.jsonl`
-- `review/review-findings.json` when findings exist
-- `execution/tasks/<task-id>/checkpoint.json`
-- `review/report-card.json`
-- one final handoff file under `handoff/`
-
-Runtime scratch, worker prompts, journals, assignments, and session logs belong
-under `devflow/workspaces/<change-key>/`, not beside durable change truth.
-
-## Feature Plans
-
-Feature and scope changes use:
-
-- `planning/tasks.md#Contract Summary`
-- `planning/task-manifest.json`
-- `change-meta.json`
-
-`Contract Summary` owns the frozen human-readable plan: user story, non-negotiable
-constraints, decisions that must not be reopened, task slices, and verification
-expectations. `task-manifest.json` and `change-meta.json` must be generated or
-updated by `cc-devflow task-contract compile`; agents must not handwrite them.
-
-## Bug Investigations
-
-Bug, regression, and unexpected-behavior work uses:
-
-- `planning/tasks.md#Root Cause Contract`
-- `planning/task-manifest.json`
-- `change-meta.json`
-
-`Root Cause Contract` owns the symptom, reproduction evidence, confirmed cause,
-rejected near-causes, repair boundary, and task handoff. `cc-do` should implement
-from that frozen contract instead of reopening investigation during execution.
-`task-manifest.json` and `change-meta.json` must be generated or updated by
-`cc-devflow task-contract compile`; agents must not handwrite them.
-
-## Review Records
-
-`cc-review` writes structured lifecycle events first:
-
-- `review/review-ledger.jsonl`
-- optional `review/review-findings.json`
-- optional rendered Markdown from `cc-devflow review render`
-
-Markdown review reports are for human reading when needed. They are not the
-default durable review source.
-
-Useful commands:
-
-```bash
-npx cc-devflow review start --change REQ-001 --change-key REQ-001-copy-invite-link --base-sha abc123 --head-sha def456
-npx cc-devflow review record-node --change REQ-001 --change-key REQ-001-copy-invite-link --review-id <review-id> --node-id R001 --target planning/tasks.md --status checked --coverage contract --evidence-ref "cmd:npm run verify"
-npx cc-devflow review add-finding --change REQ-001 --change-key REQ-001-copy-invite-link --review-id <review-id> --finding-id F001 --severity important --confidence 8 --display-tier blocking --fingerprint sha256:<hash> --scope "current change" --path planning/tasks.md --evidence "finding evidence" --recommendation "repair action" --route cc-do
-npx cc-devflow review close --change REQ-001 --change-key REQ-001-copy-invite-link --review-id <review-id> --status clean --blocking-count 0 --warning-count 0 --next cc-check
-npx cc-devflow review render --change REQ-001 --change-key REQ-001-copy-invite-link --review-id <review-id> --output review/review-report.md
-```
-
-## Legacy Fallback
-
-Older changes may still contain:
-
-- `planning/design.md`
-- `planning/analysis.md`
-- `review/cc-review-plan.md`
-- `review/cc-review-report.md`
-- `review/cc-review-agent-results.jsonl`
-
-Those files remain readable compatibility inputs. New changes should not write
-them by default. When migrating old work, fold feature-plan truth into
-`planning/tasks.md#Contract Summary` and bug-investigation truth into
-`planning/tasks.md#Root Cause Contract`.
-
-## Validation Gates
-
-Validate one change:
-
-```bash
-npx cc-devflow task-contract compile --change REQ-001 --change-key REQ-001-copy-invite-link
-npx cc-devflow task-contract validate --change REQ-001 --change-key REQ-001-copy-invite-link
-```
-
-Validate the repository artifact contract:
-
-```bash
-npm run verify:artifacts
-```
-
-Measure the contract:
-
-```bash
-npm run benchmark:artifacts
-```
-
-The package-level verification command also includes artifact validation:
-
-```bash
-npm run verify
-```
-
-Skill entrypoints have a separate context budget:
-
-```bash
-npm run benchmark:skills
-```
-
-Keep `SKILL.md` files as thin entry contracts. Move low-frequency planning,
-review, and recovery details behind `PLAYBOOK.md` or `references/*` so agents
-open them only when the matching escalation condition appears.
-
-## Authoring Rule
-
-Before adding a durable file under `devflow/changes/<change-key>/`, answer:
-
-1. Which downstream skill reads it by default?
-2. Which state does it own that no existing artifact owns?
-3. Which command fails if it drifts?
-
-If those answers are unclear, keep the information in `planning/tasks.md` or
-ephemeral workspace scratch. Machine JSON belongs to the CLI/compiler path, not
-manual agent authoring.
+Each completed PDCA or IDCA environment/stage gets a Git commit. Use the commit graph as the process record.

package/docs/guides/project-postmortem.md

@@ -1,78 +1,21 @@
-# Project Postmortem Contract
+# Project Postmortems
 
-cc-devflow treats project postmortems as a durable AI memory surface. They are not
-chat summaries. They are repo-owned evidence that future agents can search before
-planning, investigating, or executing work.
+Postmortems preserve recurring failures without turning every workflow step into a file.
 
-## Storage Layout
+## Files
 
-Project-level postmortems live under `devflow/postmortems/`:
+- `devflow/postmortems/INDEX.md`
+- `devflow/postmortems/incidents/<date>-<change-key>.md`
 
-| Path | Owner | Purpose |
-| --- | --- | --- |
-| `INDEX.md` | `cc-act` | Progressive entry point, latest incidents, tags, and search hints |
-| `principles.md` | `cc-act` | Generalized lessons about recurring model, process, and engineering mistakes |
-| `incidents/<date>-<change-key>.md` | `cc-act` | Immutable-ish factual record for one incident, bug, or repeated AI failure |
+## When To Write One
 
-`cc-act` owns writes because it has verified closeout, Git state, review state, and
-ship facts. Earlier skills only read and project the relevant reminders into their
-own artifacts.
+- closing a `FIX-*`
+- repeated AI, test, release, Git, or architecture failure
+- explicit user request
 
-## Progressive Disclosure
+## Rules
 
-- Default layer: `INDEX.md` gives tags, one-line lessons, severity, affected
-  surfaces, and links to deeper incident files.
-- Principle layer: `principles.md` gives reusable rules such as model failure
-  modes, domain-specific judgment traps, and required countermeasures.
-- Incident layer: `incidents/*.md` gives the detailed facts, Git evidence,
-  timeline, root cause, detection gap, repair, follow-ups, and search terms.
-
-Agents should start with keyword search over the default and principle layers, then
-open incident files only when the tags or failure class match the current task.
-
-## Required Incident Evidence
-
-Every incident file should include:
-
-- Symptom and impact.
-- Trigger and timeline.
-- Confirmed root cause and rejected near-causes.
-- Why the failure escaped planning, investigation, execution, review, or ship.
-- Git evidence: branch, base, head SHA, PR if any, relevant commits, review range,
-  and dirty-tree notes when they matter.
-- Verification evidence: commands, exit status, key output, and artifact paths.
-- Follow-up actions: root-cause fixes, detection improvements, and backlog items.
-- AI failure mode: model limitation, pattern-matching trap, missing evidence habit,
-  over-broad abstraction, fake compatibility, test-seam mistake, or other reusable
-  class.
-- Search terms future agents should use before repeating similar work.
-
-## Redaction Guard
-
-Postmortems are durable repo artifacts, so they must never preserve secrets,
-tokens, private customer data, personal machine paths, or raw private logs unless
-the repository already treats that exact artifact as public source truth.
-
-- Record the command, file path, commit, or artifact pointer that proves the fact.
-- Quote only the minimal output needed to prove the incident.
-- Replace sensitive values with `<redacted>` and add a short redaction summary.
-- If the only available proof is sensitive, cite the owner artifact and describe
-  the observed shape instead of copying the raw value.
-
-## Read Gates
-
-`cc-plan`, `cc-investigate`, and `cc-do` must run a quick local search before they
-freeze direction or touch code:
-
-```bash
-rg -n "<capability|module|error|failure-class|model-risk>" devflow/postmortems
-```
-
-If `devflow/postmortems/` does not exist, record `no-project-postmortems-yet`.
-If a match exists, load only `INDEX.md`, `principles.md`, and the one or two
-incident files most relevant to the current work.
-
-## State Ownership
-
-Postmortems do not own task status, roadmap progress, review verdicts, or spec sync
-state. They cite those stronger owners by path, commit, or command output.
+- Use Git evidence, commands, and current files.
+- Redact secrets, customer data, private logs, and local machine paths.
+- Do not create a separate principles file.
+- Do not use postmortems as task, review, or release state.

package/lib/compiler/__tests__/skills-registry.test.js

@@ -159,9 +159,9 @@ describe('Skills Registry Generator', () => {
       expect(execute.writes).toEqual(
         expect.arrayContaining([
           expect.objectContaining({
-            path: 'devflow/changes/<change-key>/execution/tasks/<task-id>/events.jsonl',
+            path: 'devflow/changes/<change-key>/task.md',
             durability: 'durable',
-            required: false
+            required: true
           })
         ])
       );
@@ -183,13 +183,14 @@ describe('Skills Registry Generator', () => {
         expect.arrayContaining([
           expect.objectContaining({
             path: 'devflow/changes/<change-key>/handoff/pr-brief.md',
-            required: false,
-            exclusiveGroup: 'handoff'
-          }),
+            required: false
+          })
+        ])
+      );
+      expect(act.writes).not.toEqual(
+        expect.arrayContaining([
           expect.objectContaining({
-            path: 'devflow/changes/<change-key>/handoff/release-note.md',
-            required: false,
-            exclusiveGroup: 'handoff'
+            path: expect.stringContaining('release')
           })
         ])
       );