cc-devflow 4.5.7 → 4.5.9

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

@@ -5,7 +5,7 @@
   },
   "meta": {
     "roadmapVersion": "roadmap.v2",
-    "skillVersion": "5.2.0",
+    "skillVersion": "5.3.0",
     "status": "active",
     "lastUpdated": "2026-04-19",
     "currentFocusStage": "Stage 2"

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

@@ -5,7 +5,7 @@
 ## Backlog Meta
 
 - Roadmap version: `roadmap.v1`
-- Skill version: `5.2.0`
+- Skill version: `5.3.0`
 - Last synced: `2026-04-19`
 - Current focus stage: `Stage 1`
 - Roadmap state source: `roadmap.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@5.2.0`, `cc-plan@3.8.1`, `cc-do@1.6.2`, `cc-check@1.10.1`, `cc-act@1.8.2`
+- Bound skills: `cc-roadmap@5.3.0`, `cc-plan@3.8.5`, `cc-do@1.6.5`, `cc-check@1.10.1`, `cc-act@1.8.7`
 
 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: `5.2.0`
+- Skill version: `5.3.0`
 - Status: `active`
 - Last updated: `2026-04-15`
 - Owner / decider: `product-owner`

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/handoff/pr-brief.md

@@ -1,5 +1,9 @@
 # PR Brief
 
+## Document Meta
+
+- Output language: en
+
 ## Decision
 
 - Recommended mode: `create-pr`
@@ -39,6 +43,66 @@
 - Documentation release: README and CLAUDE unchanged for this scoped example
 - PR body accuracy: regenerate the PR body from this brief, current report-card, and current diff
 
+## Pull Request Body Contract
+
+- Language source: `Output language: en`
+- PR body language: English
+- Title rule: use English after the Conventional Commits `type(scope)` prefix; keep identifiers, paths, commands, and issue keys unchanged.
+- Body source: current `pr-brief.md`, current diff, current `review/report-card.json`, doc sync output, and roadmap/backlog writeback.
+- Required sections: summary, problem, changes, validation, review/gate evidence, risk/rollback, docs/writeback, and follow-ups.
+- Completeness gate: no empty headings, no stale inherited PR body, no generic "tests passed" without commands or evidence, and no `<placeholder>` text before `gh pr create`.
+
+## Pull Request Body Draft
+
+```markdown
+## Summary
+
+- removes a small but visible sharing friction in the beta flow
+- keeps the patch inside the approved `tiny-design` boundary
+- ships with fresh test, lint, and review proof
+
+## Problem
+
+- Requirement: `RM-001` / `REQ-001`
+- User-visible gap: users can see the invite URL but cannot copy it with one click from the share dialog.
+
+## Changes
+
+- adds a `Copy invite link` action beside the existing invite URL
+- reuses the current invite link source of truth
+- adds copied-state confirmation without redesigning the dialog
+
+## Validation
+
+- `report-card.json` verdict: `pass`
+- `npm test -- src/features/share/ShareDialog.test.tsx`
+- `npm run lint -- src/features/share/ShareDialog.tsx`
+
+## Review / Gate Evidence
+
+- Reviewed base SHA: `example-base`
+- Reviewed head SHA: `example-head`
+- Review packet: `planning/tasks.md#T001-T003`; `planning/design.md`
+- Finding triage: no findings
+- QA / claim evidence: `qa=pass`, `tests-pass=pass`, `requirements-met=pass`
+- Readiness: review freshness=`fresh`; QA coverage has no gaps; browser QA intentionally skipped for this fixture.
+
+## Risk And Rollback
+
+- Main risk: copied-state feedback may still be too subtle for some users.
+- Rollback boundary: revert the share-dialog change and targeted test in one commit; no data migration or external side effect is involved.
+
+## Docs And Writeback
+
+- `CLAUDE.md`: unchanged
+- `README.md`: unchanged
+- Roadmap progress: `RM-001` is ready for PR review after this create-pr handoff.
+
+## Follow-ups
+
+- If users still miss the feedback, lift `RM-002` into the next requirement.
+```
+
 ## Summary
 
 - removes a small but visible sharing friction in the beta flow

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

@@ -3,63 +3,33 @@
   "goal": "Add a one-click copy action to the existing share dialog without changing backend contracts.",
   "createdAt": "2026-04-15T10:00:00.000Z",
   "updatedAt": "2026-04-15T11:10:00.000Z",
-  "status": "verified",
   "requirementId": "REQ-001",
   "requirementVersion": "REQ-001.v1",
-  "sourceRoadmap": {
-    "itemId": "RM-001",
-    "roadmapVersion": "roadmap.v1",
-    "roadmapSkillVersion": "5.2.0",
-    "sourceStage": "Stage 1",
-    "successSignal": "Users can copy the invite link with one click",
-    "killSignal": "The patch requires backend or permission changes",
-    "dependencies": [
-      "Existing share dialog stays intact"
-    ],
-    "nonGoals": [
-      "No invite role redesign",
-      "No share analytics"
-    ]
-  },
   "planningMeta": {
-    "reqPlanSkillVersion": "3.8.1",
+    "reqPlanSkillVersion": "3.8.5",
     "designVersion": "design.v1",
     "approvedAt": "2026-04-15T10:05:00.000Z",
-    "approvedBy": "user",
     "basedOnOption": "Tiny design card",
-    "requirementBrief": {
-      "problemStatement": "Users can see the invite URL, but copying it still requires manual selection.",
-      "solutionSummary": "Add a one-click copy action with lightweight confirmation inside the existing share dialog.",
-      "actors": [
-        "workspace member sharing an invite"
-      ],
-      "userStories": [
-        {
-          "id": "US-001",
-          "actor": "workspace member",
-          "want": "copy the invite link with one click",
-          "benefit": "share it without manually selecting text",
-          "acceptance": [
-            "Dialog behavior test proves the current invite URL is copied"
-          ]
-        }
-      ],
-      "edgeOrRecoveryStories": [],
-      "implementationDecisions": [
-        "Reuse the existing invite URL source and dialog props"
-      ],
-      "testingDecisions": [
-        "Test through the share dialog behavior, not an internal helper"
-      ],
-      "outOfScope": [
-        "invite generation",
-        "role controls",
-        "analytics",
-        "clipboard fallback redesign"
-      ],
-      "furtherNotes": [
-        "Richer copied-state feedback is a separate UX requirement"
-      ]
+    "aiLeverageDecisionLens": {
+      "realUserOrOperator": "workspace member sharing an invite",
+      "statusQuoWorkaround": "manual selection and copy of the visible invite URL",
+      "humanTeamEffortForFullScope": "about half a day for one engineer including test and review",
+      "ccAgentEffortForFullScope": "about 20 minutes for a targeted UI patch plus test update",
+      "aiCompressionRatio": "roughly 10x for this bounded UI slice",
+      "completeLakeBoundary": "copy action, current invite URL source, copied-state feedback, and dialog behavior test",
+      "oceanBoundary": "invite generation, permissions, analytics, or clipboard fallback redesign",
+      "scopeRecommendation": "boil-lake",
+      "costModel": {
+        "agentTime": "low",
+        "humanReviewTime": "low",
+        "verificationCost": "targeted dialog test",
+        "maintenanceCost": "low while scoped to the dialog",
+        "failureCost": "sharing friction remains",
+        "reversibility": "reversible UI patch"
+      },
+      "verdict": "boil-lake",
+      "missingEvidenceOrPivotReason": "",
+      "impactOnApprovedDirection": "cover the full same-dialog copy lake instead of only a happy-path button render"
     },
     "externalBestPractice": {
       "needed": false,
@@ -105,31 +75,9 @@
         "impact": "cc-do keeps implementation inside the share dialog and avoids backend or permission work",
         "status": "answered"
       }
-    ],
-    "aiLeverageDecisionLens": {
-      "realUserOrOperator": "workspace member sharing an invite",
-      "statusQuoWorkaround": "manual selection and copy of the visible invite URL",
-      "humanTeamEffortForFullScope": "about half a day for one engineer including test and review",
-      "ccAgentEffortForFullScope": "about 20 minutes for a targeted UI patch plus test update",
-      "aiCompressionRatio": "roughly 10x for this bounded UI slice",
-      "completeLakeBoundary": "copy action, current invite URL source, copied-state feedback, and dialog behavior test",
-      "oceanBoundary": "invite generation, permissions, analytics, or clipboard fallback redesign",
-      "scopeRecommendation": "boil-lake",
-      "costModel": {
-        "agentTime": "low",
-        "humanReviewTime": "low",
-        "verificationCost": "targeted dialog test",
-        "maintenanceCost": "low while scoped to the dialog",
-        "failureCost": "sharing friction remains",
-        "reversibility": "reversible UI patch"
-      },
-      "verdict": "boil-lake",
-      "missingEvidenceOrPivotReason": "",
-      "impactOnApprovedDirection": "cover the full same-dialog copy lake instead of only a happy-path button render"
-    }
+    ]
   },
   "currentTaskId": null,
-  "activePhase": null,
   "tasks": [
     {
       "id": "T001",
@@ -179,7 +127,22 @@
       },
       "status": "passed",
       "attempts": 1,
-      "maxRetries": 1
+      "maxRetries": 1,
+      "tddPhase": "red",
+      "verticalSlice": "Slice 1",
+      "testSeam": {
+        "entry": "share dialog UI behavior",
+        "behaviorAsserted": "The missing copy action is reproduced as a failing test",
+        "specStyleTestName": "The missing copy action is reproduced as a failing test",
+        "oneLogicalBehavior": true,
+        "publicVerificationPath": "Run the share dialog test and observe the copy action through the rendered dialog",
+        "implementationDetailRisk": "low"
+      },
+      "feedbackLoop": {
+        "type": "automated-test",
+        "determinism": "deterministic",
+        "expectedFailure": "Fails before the behavior exists"
+      }
     },
     {
       "id": "T002",
@@ -231,7 +194,22 @@
       },
       "status": "passed",
       "attempts": 1,
-      "maxRetries": 1
+      "maxRetries": 1,
+      "tddPhase": "green",
+      "verticalSlice": "Slice 2",
+      "testSeam": {
+        "entry": "share dialog UI behavior",
+        "behaviorAsserted": "The dialog exposes a copy button and confirms the copied state",
+        "specStyleTestName": "The dialog exposes a copy button and confirms the copied state",
+        "oneLogicalBehavior": true,
+        "publicVerificationPath": "Run the share dialog test and observe the copy action through the rendered dialog",
+        "implementationDetailRisk": "low"
+      },
+      "feedbackLoop": {
+        "type": "automated-test",
+        "determinism": "deterministic",
+        "expectedFailure": ""
+      }
     },
     {
       "id": "T003",
@@ -287,15 +265,27 @@
       },
       "status": "passed",
       "attempts": 1,
-      "maxRetries": 1
+      "maxRetries": 1,
+      "tddPhase": "evidence",
+      "verticalSlice": "Slice 3",
+      "testSeam": {
+        "entry": "share dialog UI behavior",
+        "behaviorAsserted": "Fresh verification evidence is ready for cc-check",
+        "specStyleTestName": "Fresh verification evidence is ready for cc-check",
+        "oneLogicalBehavior": true,
+        "publicVerificationPath": "Run the share dialog test and observe the copy action through the rendered dialog",
+        "implementationDetailRisk": "low"
+      },
+      "feedbackLoop": {
+        "type": "automated-test",
+        "determinism": "deterministic",
+        "expectedFailure": ""
+      }
     }
   ],
   "metadata": {
     "source": "tasks.md",
     "generatedBy": "docs-example",
     "planVersion": 1
-  },
-  "deferredQuestions": [
-    "If users still miss the copied-state confirmation, open RM-002 for richer feedback."
-  ]
+  }
 }

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.8.1`
+- CC-Plan skill version: `3.8.5`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 
@@ -39,34 +39,68 @@
 
 > 顶部 handoff 只保留执行者必须知道的现实，不重复讲背景故事。
 
+## Execution Protocol
+
+ClaudeCode / Codex 执行本计划时，必须把本文件当成任务模板合同，而不是普通 TODO 列表。
+
+- Template source: `assets/TASKS_TEMPLATE.md`
+- Task selection: read `planning/task-manifest.json.currentTaskId`; if empty, run the ready-task selector before choosing work.
+- 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 checkpoint / review / dependency evidence and rerun it. Do not bypass it by editing JSON or Markdown.
+
+```bash
+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/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>
+```
+
 ## Phase 1: Foundation
 
 - [x] T001 [TEST] Add a failing dialog test for the missing copy action (dependsOn:none) `src/features/share/ShareDialog.test.tsx`
   Goal: 证明当前 share dialog 还不能一键复制 invite link。
+  TDD phase: red
   Files: `src/features/share/ShareDialog.test.tsx`
   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 checkpoint/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.
+  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
   Ready when: 没有上游依赖，且现有 dialog test 已可运行
 
 - [x] T002 [IMPL] Add the copy button and copied-state confirmation (dependsOn:T001) `src/features/share/ShareDialog.tsx`
   Goal: 用最小实现让 T001 转绿，并保持当前 share contract 不变。
+  TDD phase: green
   Files: `src/features/share/ShareDialog.tsx`
   Read first: `design.md`, `src/features/share/ShareDialog.test.tsx`
   Verification: `npm test -- src/features/share/ShareDialog.test.tsx`
   Evidence: passing output + checkpoint + review notes
+  Completion: after verification evidence and required checkpoint/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.
+  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
   Ready when: T001 已经见红，且当前 touched files 没有外部依赖阻塞
 
 ## Phase 2: Verify
 
 - [x] T003 Run targeted checks and collect fresh evidence (dependsOn:T002) `share dialog quality gates`
   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`
   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 checkpoint/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.
+  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
   Ready when: T002 已完成，且 review gate 已可补齐
 
 > `[P]` 只表示“依赖满足后有资格并行”，不表示可以无脑同时开发。

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

@@ -5,7 +5,7 @@
   },
   "meta": {
     "roadmapVersion": "roadmap.v1",
-    "skillVersion": "5.2.0",
+    "skillVersion": "5.3.0",
     "status": "active",
     "lastUpdated": "2026-04-19",
     "currentFocusStage": "Stage 1"

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

@@ -35,19 +35,27 @@ 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
@@ -92,10 +100,24 @@ while IFS= read -r encoded; do
   assert_contains "$planning_dir/tasks.md" "- CC-Plan skill version: \`$REQ_PLAN_VERSION\`"
 
   jq -er --arg roadmap "$ROADMAP_VERSION" --arg reqplan "$REQ_PLAN_VERSION" '
-    (.sourceRoadmap.roadmapSkillVersion // $roadmap) == $roadmap and
-    (.planningMeta.reqPlanSkillVersion // $reqplan) == $reqplan
+    (.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" "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 "$readme" "## Example Meta"
   assert_contains "$readme" "\`cc-roadmap@$ROADMAP_VERSION\`"
   assert_contains "$readme" "\`cc-plan@$REQ_PLAN_VERSION\`"

package/docs/get-shit-done-strategy-audit.md

@@ -127,9 +127,9 @@ Codebase Map 七件套只作为按需缓存：
 | --- | --- | --- | --- |
 | WHAT/WHY ambiguity score | `task-manifest.json.planningMeta` + `planning/design.md` | score above threshold blocks task manifest approval | unit fixture: ambiguous input blocks; clear input passes |
 | Assumptions preview | `planning/design.md` decision log | user-visible assumptions before approval | fixture: hidden assumption fails review |
-| Bounded review loop | `task-manifest.json.planningMeta.reviewLoop` | max attempts and stall detection reroute to `cc-roadmap` or user question | hostile fixture: repeated issue count blocks |
-| External doc conflict buckets | `task-manifest.json.languageAndDecisions` | imported docs classified as auto-resolved, competing, unresolved | fixture: conflicting ADR/PRD creates blocker |
-| Trust boundary | `task-manifest.json.sourceEvidence[]` | external text is evidence/source only, never instruction | hostile fixture: prompt injection remains evidence-only |
+| Bounded review loop | `planning/design.md` | max attempts and stall detection reroute to `cc-roadmap` or user question | hostile fixture: repeated issue count blocks |
+| External doc conflict buckets | `planning/design.md` | imported docs classified as auto-resolved, competing, unresolved | fixture: conflicting ADR/PRD creates blocker |
+| Trust boundary | `planning/design.md` | external text is evidence/source only, never instruction | hostile fixture: prompt injection remains evidence-only |
 
 `cc-plan` must keep design decisions readable in Markdown and machine truth in JSON.
 No separate GSD-style `.planning/` tree.
@@ -209,7 +209,7 @@ default planning path.
 | Data | Owner | Human view | Machine truth |
 | --- | --- | --- | --- |
 | Ambiguity and assumptions | `cc-plan` | `planning/design.md` | `task-manifest.json.planningMeta` |
-| Imported doc trust classification | `cc-plan` | `planning/design.md` | `task-manifest.json.sourceEvidence[]` |
+| Imported doc trust classification | `cc-plan` | `planning/design.md` | `planning/design.md` |
 | Task graph and waves | `cc-plan` / `cc-do` | `planning/tasks.md` | `task-manifest.json.tasks[]` |
 | Quick lane state | `cc-do` | checkpoint summary | `task-manifest.json.metadata`, `checkpoint.json` |
 | Debug hypotheses and probes | `cc-investigate` | `planning/analysis.md` | optional `task-manifest.json.investigation` |

package/docs/guides/artifact-contract.md

@@ -0,0 +1,44 @@
+# Artifact Contract
+
+cc-devflow artifacts follow two rules: progressive disclosure and one state owner.
+
+## Progressive Disclosure
+
+Every skill output should have a default path and deeper layers.
+
+- 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.
+
+If a field has no clear opener and no downstream consumer, remove it.
+
+## State Owners
+
+| 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 checkpoint state | `execution/tasks/<task-id>/checkpoint.json` | `events.jsonl`, 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.
+- 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?

package/docs/guides/getting-started.md

@@ -89,7 +89,7 @@ Typical outputs:
 - `cc-spec-init` writes `devflow/specs/INDEX.md`, capability specs, and `change-meta.json`
 - `cc-plan` writes `planning/design.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
 - `cc-investigate` writes `planning/analysis.md`, `planning/tasks.md`, `task-manifest.json`, and `change-meta.json`
-- `cc-review` writes `cc-review-report.md` and optional structured findings for deep plan or implementation review
+- `cc-review` writes `cc-review-plan.md`, `cc-review-ledger.jsonl`, `cc-review-report.md`, optional `cc-review-agent-results.jsonl`, and optional structured findings for deep plan or implementation review
 - `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`
 

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

@@ -89,7 +89,7 @@ find .codex/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sort
 - `cc-spec-init` 产出 `devflow/specs/INDEX.md`、capability spec 和 `change-meta.json`
 - `cc-plan` 产出 `planning/design.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
 - `cc-investigate` 产出 `planning/analysis.md`、`planning/tasks.md`、`task-manifest.json` 和 `change-meta.json`
-- `cc-review` 产出 `cc-review-report.md`，以及可选的结构化深度 Review findings
+- `cc-review` 产出 `cc-review-plan.md`、`cc-review-ledger.jsonl`、`cc-review-report.md`、可选 `cc-review-agent-results.jsonl`，以及可选的结构化深度 Review findings
 - `cc-check` 产出 `report-card.json`
 - `cc-act` 只产出一个最终 handoff 文件：`handoff/pr-brief.md`、`handoff/resume-index.md` 或 `handoff/release-note.md`
 

package/docs/guides/project-postmortem.md

@@ -0,0 +1,78 @@
+# Project Postmortem Contract
+
+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.
+
+## Storage Layout
+
+Project-level postmortems live under `devflow/postmortems/`:
+
+| 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 |
+
+`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.
+
+## Progressive Disclosure
+
+- 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.