cc-devflow 4.5.8 → 4.5.10

package/docs/examples/pdca-loop/changes/REQ-001-copy-invite-link/planning/task-manifest.json

@@ -3,63 +3,34 @@
   "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.2",
+    "reqPlanSkillVersion": "3.9.0",
     "designVersion": "design.v1",
+    "workBranch": "REQ/001-copy-invite-link",
     "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 +76,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",
@@ -194,45 +143,7 @@
         "type": "automated-test",
         "determinism": "deterministic",
         "expectedFailure": "Fails before the behavior exists"
-      },
-      "allowedMocks": [
-        "clipboard boundary"
-      ],
-      "testQuality": {
-        "usesPublicInterface": true,
-        "describesBehavior": true,
-        "specStyleName": true,
-        "oneLogicalBehavior": true,
-        "verifiesThroughPublicPath": true,
-        "survivesInternalRefactor": true,
-        "mocksOnlySystemBoundaries": true,
-        "noBulkRed": true
-      },
-      "greenMinimality": {
-        "guard": "Keep the task scoped to its stated verification evidence",
-        "noSpeculativeBranches": true
-      },
-      "completion": {
-        "command": "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",
-        "requiredBeforeCompletion": [
-          "verification evidence captured",
-          "checkpoint written",
-          "spec review gate recorded",
-          "code review gate recorded"
-        ],
-        "forbiddenShortcuts": [
-          "manual checkbox edit",
-          "manual manifest status edit",
-          "leaving currentTaskId stale"
-        ]
-      },
-      "refactorCandidates": [
-        "duplication",
-        "long method",
-        "primitive obsession",
-        "naming",
-        "more than three nested branches"
-      ]
+      }
     },
     {
       "id": "T002",
@@ -299,45 +210,7 @@
         "type": "automated-test",
         "determinism": "deterministic",
         "expectedFailure": ""
-      },
-      "allowedMocks": [
-        "clipboard boundary"
-      ],
-      "testQuality": {
-        "usesPublicInterface": true,
-        "describesBehavior": true,
-        "specStyleName": true,
-        "oneLogicalBehavior": true,
-        "verifiesThroughPublicPath": true,
-        "survivesInternalRefactor": true,
-        "mocksOnlySystemBoundaries": true,
-        "noBulkRed": true
-      },
-      "greenMinimality": {
-        "guard": "Implement only the code needed to pass the current red behavior",
-        "noSpeculativeBranches": true
-      },
-      "completion": {
-        "command": "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",
-        "requiredBeforeCompletion": [
-          "verification evidence captured",
-          "checkpoint written",
-          "spec review gate recorded",
-          "code review gate recorded"
-        ],
-        "forbiddenShortcuts": [
-          "manual checkbox edit",
-          "manual manifest status edit",
-          "leaving currentTaskId stale"
-        ]
-      },
-      "refactorCandidates": [
-        "duplication",
-        "long method",
-        "primitive obsession",
-        "naming",
-        "more than three nested branches"
-      ]
+      }
     },
     {
       "id": "T003",
@@ -408,87 +281,12 @@
         "type": "automated-test",
         "determinism": "deterministic",
         "expectedFailure": ""
-      },
-      "allowedMocks": [
-        "clipboard boundary"
-      ],
-      "testQuality": {
-        "usesPublicInterface": true,
-        "describesBehavior": true,
-        "specStyleName": true,
-        "oneLogicalBehavior": true,
-        "verifiesThroughPublicPath": true,
-        "survivesInternalRefactor": true,
-        "mocksOnlySystemBoundaries": true,
-        "noBulkRed": true
-      },
-      "greenMinimality": {
-        "guard": "Keep the task scoped to its stated verification evidence",
-        "noSpeculativeBranches": true
-      },
-      "completion": {
-        "command": "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",
-        "requiredBeforeCompletion": [
-          "verification evidence captured",
-          "checkpoint written",
-          "spec review gate recorded",
-          "code review gate recorded"
-        ],
-        "forbiddenShortcuts": [
-          "manual checkbox edit",
-          "manual manifest status edit",
-          "leaving currentTaskId stale"
-        ]
-      },
-      "refactorCandidates": [
-        "duplication",
-        "long method",
-        "primitive obsession",
-        "naming",
-        "more than three nested branches"
-      ]
+      }
     }
   ],
   "metadata": {
     "source": "tasks.md",
     "generatedBy": "docs-example",
     "planVersion": 1
-  },
-  "deferredQuestions": [
-    "If users still miss the copied-state confirmation, open RM-002 for richer feedback."
-  ],
-  "executionProtocol": {
-    "templateCompliance": {
-      "required": true,
-      "sourceTemplate": "assets/TASKS_TEMPLATE.md",
-      "taskBlockMustInclude": [
-        "Goal",
-        "TDD phase",
-        "Files",
-        "Read first",
-        "Verification",
-        "Evidence",
-        "Test seam",
-        "Public verification path",
-        "Allowed mocks",
-        "Completion"
-      ],
-      "titleOnlyTasks": "forbidden"
-    },
-    "selection": {
-      "sourceOfTruth": "planning/task-manifest.json.currentTaskId",
-      "commandTemplate": "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"
-    },
-    "completion": {
-      "manualStatusEdit": "forbidden",
-      "commandTemplate": "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 <task-id>",
-      "failurePolicy": "Do not hand-edit status; fix missing checkpoint, review gate, or dependency evidence and rerun the script.",
-      "updates": [
-        "planning/task-manifest.json.tasks[].status",
-        "planning/task-manifest.json.currentTaskId",
-        "planning/task-manifest.json.status",
-        "planning/tasks.md checkbox"
-      ]
-    }
   }
 }

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

@@ -4,7 +4,8 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.8.2`
+- CC-Plan skill version: `3.9.0`
+- Work branch: `REQ/001-copy-invite-link`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 
@@ -44,12 +45,14 @@
 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.
 - 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.
+- Completion failure: if the script fails, fix the missing review / dependency evidence and rerun it. Do not bypass it by editing JSON or Markdown.
 
 ```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"
 if [[ ! -d "$SCRIPT_ROOT" && -d ".codex/skills/cc-do/scripts" ]]; then
   SCRIPT_ROOT=".codex/skills/cc-do/scripts"
@@ -67,7 +70,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 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.
+  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.
   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
@@ -79,8 +82,8 @@ bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/cha
   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.
+  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.
   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
@@ -97,7 +100,7 @@ bash "$SCRIPT_ROOT/mark-task-complete.sh" --manifest docs/examples/pdca-loop/cha
   - `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.
+  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.
   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/pdca-loop/changes/REQ-001-copy-invite-link/review/report-card.json

@@ -120,7 +120,7 @@
       "reviewPacket": {
         "baseSha": "example-base",
         "headSha": "example-head",
-        "requirements": "planning/design.md",
+        "requirements": "planning/tasks.md#Contract Summary",
         "implemented": "copy invite link workflow",
         "reviewerContext": "requirement diff, plan completion, scope drift, docs staleness"
       },

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

@@ -100,15 +100,21 @@ 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 and
-    .executionProtocol.templateCompliance.required == true and
-    .executionProtocol.completion.manualStatusEdit == "forbidden" and
-    (.executionProtocol.completion.commandTemplate | contains("mark-task-complete.sh")) and
-    all(.tasks[]; (.completion.command | contains("mark-task-complete.sh")) and (.tddPhase | type == "string") and (.testSeam.publicVerificationPath | type == "string"))
+    (.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:"

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

@@ -68,7 +68,7 @@ lib/skill-runtime
         |
         v
 durable artifacts
-  task-manifest.json / report-card.json / change-state.json / analysis.md
+  planning/tasks.md / task-manifest.json / report-card.json / change-meta.json
 ```
 
 SKILL/PLAYBOOK 拥有 workflow 语义。`lib/skill-runtime` 只拥有 typed reads、
@@ -125,11 +125,11 @@ Codebase Map 七件套只作为按需缓存：
 
 | Contract | Artifact owner | Gate | Tests |
 | --- | --- | --- | --- |
-| 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 |
+| WHAT/WHY ambiguity score | `task-manifest.json.planningMeta` + `planning/tasks.md#Contract Summary` | score above threshold blocks task manifest approval | unit fixture: ambiguous input blocks; clear input passes |
+| Assumptions preview | `planning/tasks.md#Contract Summary` decision log | user-visible assumptions before approval | fixture: hidden assumption fails review |
+| Bounded review loop | `planning/tasks.md#Contract Summary` | max attempts and stall detection reroute to `cc-roadmap` or user question | hostile fixture: repeated issue count blocks |
+| External doc conflict buckets | `planning/tasks.md#Contract Summary` | imported docs classified as auto-resolved, competing, unresolved | fixture: conflicting ADR/PRD creates blocker |
+| Trust boundary | `planning/tasks.md#Contract Summary` | 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.
@@ -140,20 +140,20 @@ No separate GSD-style `.planning/` tree.
 | --- | --- | --- | --- |
 | Wave scheduling | `task-manifest.json.tasks[].phase/parallel/dependsOn/touches` | parallel only when dependencies and touches do not conflict | schema fixture: shared touches rejected |
 | Submodule-aware worktree gate | `task-manifest.json.tasks[].touches` + runtime submodule scan | only tasks touching submodule paths lose isolation | hostile fixture: repo with `.gitmodules` but unrelated touches still parallel |
-| Quick lane mini manifest | `task-manifest.json.metadata.lane=quick` | small work still has checkpoint, verification, handoff | fixture: quick lane without verification blocks |
-| Thread/pause/resume | `change-state.json` + one final handoff file | resume query returns stable next action | integration: stale checkpoint restores to pending |
+| Quick lane mini manifest | `task-manifest.json.metadata.lane=quick` | small work still has task-state truth, verification, handoff | fixture: quick lane without verification blocks |
+| Thread/pause/resume | `change-meta.json`, manifest task state, optional CLI logs, and one final handoff file | resume query returns stable next action | integration: stale manifest state restores to pending |
 
-`cc-do` should not invent new task state outside `task-manifest.json` and checkpoints.
+`cc-do` should not invent new task state outside `task-manifest.json`.
 
 ### `cc-investigate`
 
 | Contract | Artifact owner | Gate | Tests |
 | --- | --- | --- | --- |
-| Persistent debug session | `planning/analysis.md` session block, optional machine summary in `task-manifest.json` | hypotheses, probes, symptom match, cleanup recorded | fixture: missing cleanup blocks freeze |
-| Diagnose-only report | `planning/analysis.md` | no code edits required; root cause and next action explicit | fixture: diagnose-only does not mark implementation complete |
-| Workflow forensics | `planning/analysis.md` + trace refs | git/artifact/state failures classified before fixes | hostile fixture: corrupt manifest produces named failure |
+| Persistent debug session | `planning/tasks.md#Root Cause Contract`, optional machine summary in `task-manifest.json` | hypotheses, probes, symptom match, cleanup recorded | fixture: missing cleanup blocks freeze |
+| Diagnose-only report | `planning/tasks.md#Root Cause Contract` | no code edits required; root cause and next action explicit | fixture: diagnose-only does not mark implementation complete |
+| Workflow forensics | `planning/tasks.md#Root Cause Contract` + trace refs | git/artifact/state failures classified before fixes | hostile fixture: corrupt manifest produces named failure |
 
-Prefer extending `planning/analysis.md` over adding `planning/debug-session.md`.
+Prefer extending `planning/tasks.md#Root Cause Contract` over adding `planning/debug-session.md`.
 Only add a new file if the debug transcript becomes too large and has a single owner.
 
 ### `cc-check`
@@ -208,11 +208,11 @@ 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[]` |
+| Ambiguity and assumptions | `cc-plan` | `planning/tasks.md#Contract Summary` | `task-manifest.json.planningMeta` |
+| Imported doc trust classification | `cc-plan` | `planning/tasks.md#Contract Summary` | `planning/tasks.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` |
+| Quick lane state | `cc-do` | task-state summary | `task-manifest.json.metadata`, `planning/tasks.md` |
+| Debug hypotheses and probes | `cc-investigate` | `planning/tasks.md#Root Cause Contract` | optional `task-manifest.json.investigation` |
 | Verification/UAT/facets | `cc-check` | review summary | `report-card.json` |
 | Runtime failures | `cc-check` | review summary | `report-card.json.runtime.failureOwnership[]` |
 | Ship target and rollback | `cc-act` | `handoff/pr-brief.md` / `release-note.md` | structured preflight output |
@@ -243,7 +243,7 @@ owner skill, and next action.
 | --- | --- | --- | --- | --- | --- | --- |
 | external docs -> `cc-plan` | block with missing source | skip with reason | `TrustBoundaryError` | conflict bucket | mark stale source | partial import warning |
 | `tasks.md` -> `task-manifest.json` | block | block | schema error | dependency conflict | plan version mismatch | no manifest approval |
-| manifest -> wave scheduling | block | no runnable task | `InvalidTaskGraphError` | serialize or block | stale checkpoint rejected | reroute resume |
+| manifest -> wave scheduling | block | no runnable task | `InvalidTaskGraphError` | serialize or block | stale manifest state rejected | reroute resume |
 | debug session -> analysis | block freeze | require note | schema/narrative mismatch | competing hypotheses | stale symptom | diagnose-only |
 | query registry -> next action | `MissingArtifactError` | no next action with reason | named parse/schema error | blocked graph | stale state warning | degraded output |
 | inventory -> publish gate | missing inventory blocks | empty inventory blocks | schema error | drift blocks | stale hash blocks | publish blocked |
@@ -320,7 +320,7 @@ Large-file guardrails:
 
 ### Phase 3: `cc-investigate` debug session and forensics
 
-- Extend `planning/analysis.md` and optional machine summary.
+- Extend `planning/tasks.md#Root Cause Contract` and optional machine summary.
 - Required proof: diagnose-only and missing cleanup fixtures.
 
 ### Phase 4: `cc-check` and `cc-act` consumers
@@ -354,7 +354,7 @@ These rules protect cc-devflow's identity:
 | Existing cc-devflow asset | Reuse |
 | --- | --- |
 | `lib/skill-runtime/query.js` | current progress/next/full-state facade |
-| `lib/skill-runtime/schemas.js` | manifest/report/checkpoint schema boundary |
+| `lib/skill-runtime/schemas.js` | manifest/report/runtime schema boundary |
 | `lib/skill-runtime/config.js` | layered config and doctor pattern |
 | `lib/compiler/manifest.js` | hash and drift detection foundation |
 | `scripts/validate-publish.js` | publish validation orchestrator |
@@ -404,7 +404,7 @@ not the cc-devflow implementation order.
 | `ship` | structured ship preflight |
 | `next` | runtime query `route.next-action` |
 | `fast` | TDD exception / quick lane rule |
-| `quick` | mini manifest + checkpoint |
+| `quick` | mini manifest + task-state truth |
 | `ui-review` | conditional frontend `cc-check` facet |
 | `code-review` | finding schema |
 | `code-review-fix` | fix loop and return to `cc-check` |
@@ -433,7 +433,7 @@ not the cc-devflow implementation order.
 | `cleanup` | low priority cleanup |
 | `manager` | skip UI |
 | `workstreams` | active pointer only |
-| `autonomous` | smart-discuss/checkpoint guard only |
+| `autonomous` | smart-discuss/task-state guard only |
 | `undo` | rollback guard |
 
 ### Session And Navigation

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 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.
+- 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

@@ -11,10 +11,10 @@ CC-DevFlow has two entry paths:
 - `cc-devflow init`: install the whole `.claude` pack into your project
 - `cc-devflow adapt`: generate platform outputs such as Codex rules
 
-The core workflow is driven by six visible skills, with `cc-review` available as an optional deep review pass:
+The core workflow can run manually through PDCA/IDCA skills or automatically through the PR harness skills:
 
 ```text
-cc-roadmap
+cc-roadmap -> cc-next -> cc-dev
 
 PDCA: cc-plan -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
 IDCA: cc-investigate -> [cc-review] -> cc-do -> [cc-review] -> cc-check -> cc-act
@@ -36,7 +36,7 @@ The public skills are the visible harness. Each distributed `SKILL.md` now carri
 npx cc-devflow init --dir /path/to/your/project
 ```
 
-The whole-pack install includes the six core workflow skills, optional `cc-review`, plus `cc-spec-init` and `cc-simplify` as maintenance helpers.
+The whole-pack install includes roadmap, next-work selection, autonomous dev, manual PDCA/IDCA, optional `cc-review`, PR review/landing, plus `cc-spec-init` and `cc-simplify` as maintenance helpers.
 
 ### Single Skill Install
 
@@ -87,9 +87,9 @@ 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/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-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-plan` writes `planning/tasks.md#Contract Summary`, CLI-generated `task-manifest.json`, and `change-meta.json`
+- `cc-investigate` writes `planning/tasks.md#Root Cause Contract`, CLI-generated `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`
 
@@ -98,7 +98,8 @@ 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 `change-state.json`, `change-meta.json`, planning docs, `task-manifest.json`, optional `team-state.json`, task `checkpoint.json`, `report-card.json`, and one final handoff file under each `devflow/changes/<change>/`.
+- Keep `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.
+- 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.
 
 Planning handoffs should be evidence-rich before implementation starts:
@@ -154,7 +155,7 @@ npx cc-devflow adapt --cwd /path/to/your/project --platform codex
 
 If your project has no optional `.claude/commands/` input, this is expected: the compiler will still generate the skills registry and mirror the distributed skill set for Codex.
 
-Codex mirrors the distributed skills from `.claude/skills/<skill>/` into `.codex/skills/<skill>/`. That set includes the six core workflow skills, optional `cc-review`, `cc-spec-init`, and `cc-simplify`, and the mirror is additive-only: existing project-owned Codex skills are preserved instead of being deleted.
+Codex mirrors the distributed skills from `.claude/skills/<skill>/` into `.codex/skills/<skill>/`. That set includes the public workflow skills plus maintenance skills `cc-spec-init` and `cc-simplify`, and the mirror is additive-only: existing project-owned Codex skills are preserved instead of being deleted.
 
 ### Keep skills and examples in sync
 
@@ -173,6 +174,7 @@ npm run verify:publish
 - [CLI And Skills](../commands/README.md)
 - [Workflow Guide](./workflow-guide.md)
 - [Best Practices](./best-practices.md)
+- [Minimized Artifact Contract](./minimize-artifacts.md)
 - [Example Entry Page](../examples/START-HERE.md)
 - [Compact Example List](../examples/README.md)
 - [Project README](../../README.md)