cc-devflow 4.5.8 → 4.5.9

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.2",
+    "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",
@@ -194,45 +142,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 +209,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 +280,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,7 @@
 
 - Requirement version: `REQ-001.v1`
 - Design version: `design.v1`
-- CC-Plan skill version: `3.8.2`
+- CC-Plan skill version: `3.8.5`
 - Source roadmap item: `RM-001`
 - Source roadmap version: `roadmap.v1`
 

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,12 +100,16 @@ 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"

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

package/lib/skill-runtime/__tests__/planner.tdd.test.js

@@ -120,7 +120,7 @@ describe('TDD Order Validation', () => {
       });
     });
 
-    test('should write currentTaskId and activePhase into manifest', async () => {
+    test('should write currentTaskId while deriving activePhase from the task graph', async () => {
       const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-planner-'));
       const changeId = 'REQ-321';
       const tasksPath = path.join(repoRoot, 'devflow', 'changes', `${changeId}-change`, 'planning', 'tasks.md');
@@ -146,7 +146,7 @@ describe('TDD Order Validation', () => {
         overwrite: true
       });
 
-      expect(manifest.activePhase).toBe(1);
+      expect(manifest.activePhase).toBeUndefined();
       expect(manifest.currentTaskId).toBe('T002');
       expect(manifest.tasks[1].reviews).toEqual({ spec: 'pending', code: 'pending' });
     });

package/lib/skill-runtime/__tests__/schemas.test.js

@@ -8,7 +8,6 @@ describe('Manifest schema hard constraints', () => {
       createdAt: '2026-04-10T01:00:00.000Z',
       updatedAt: '2026-04-10T01:05:00.000Z',
       currentTaskId: 'T001',
-      activePhase: 1,
       tasks: [
         {
           id: 'T001',
@@ -73,7 +72,39 @@ describe('Manifest schema hard constraints', () => {
     });
 
     expect(manifest.currentTaskId).toBe('T001');
-    expect(manifest.activePhase).toBe(1);
+    expect(manifest.activePhase).toBeUndefined();
+  });
+
+  test('accepts legacy activePhase input without preserving the retired field', () => {
+    const manifest = parseManifest({
+      changeId: 'REQ-560',
+      goal: 'Validate legacy manifest compatibility',
+      createdAt: '2026-04-10T01:00:00.000Z',
+      updatedAt: '2026-04-10T01:05:00.000Z',
+      currentTaskId: 'T001',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: '[TEST] Counter behavior',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: [],
+          run: ['echo ok'],
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    expect(manifest.currentTaskId).toBe('T001');
+    expect(manifest.activePhase).toBeUndefined();
   });
 
   test('rejects invalid currentTaskId for tasks.md manifest', () => {

package/lib/skill-runtime/planner.js

@@ -480,7 +480,7 @@ function deriveManifestExecutionState(tasks) {
 function applyManifestExecutionState(manifest, updatedAt = nowIso()) {
   const executionState = deriveManifestExecutionState(manifest.tasks || []);
   manifest.currentTaskId = executionState.currentTaskId;
-  manifest.activePhase = executionState.activePhase;
+  delete manifest.activePhase;
   manifest.updatedAt = updatedAt;
   return manifest;
 }
@@ -504,7 +504,6 @@ async function createTaskManifest({ repoRoot, changeId, goal, overwrite = false
     createdAt: previous?.createdAt || nowIso(),
     updatedAt: nowIso(),
     currentTaskId: null,
-    activePhase: null,
     tasks,
     metadata: {
       source: hasTasksFile ? 'tasks.md' : 'default',

package/lib/skill-runtime/query.js

@@ -81,7 +81,7 @@ async function getNextTask(repoRoot, changeId, options = {}) {
   const manifestPath = getTaskManifestPath(repoRoot, changeId, options);
   const manifest = await readQueryArtifact(manifestPath);
   const executionState = deriveManifestExecutionState(manifest.tasks || []);
-  const activePhase = manifest.activePhase ?? executionState.activePhase;
+  const activePhase = executionState.activePhase;
   const completedIds = new Set(
     (manifest.tasks || [])
       .filter((task) => isTaskCompletedStatus(task.status))

package/lib/skill-runtime/schemas.js

@@ -107,7 +107,7 @@ const ManifestSchema = z.object({
   createdAt: z.string().datetime(),
   updatedAt: z.string().datetime(),
   currentTaskId: z.string().regex(TASK_ID_PATTERN).nullable().default(null),
-  activePhase: z.number().int().min(1).nullable().default(null),
+  activePhase: z.number().int().min(1).nullable().optional(),
   tasks: z.array(TaskSchema),
   metadata: z.object({
     source: z.enum(['tasks.md', 'default']).default('default'),
@@ -161,7 +161,7 @@ const ManifestSchema = z.object({
     ? Math.min(...unfinished.map((task) => task.phase || 1))
     : null;
 
-  if (manifest.activePhase !== null && manifest.activePhase !== derivedActivePhase) {
+  if (manifest.activePhase !== undefined && manifest.activePhase !== null && manifest.activePhase !== derivedActivePhase) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
       path: ['activePhase'],
@@ -542,7 +542,9 @@ function parseWithSchema(schema, input, label) {
 }
 
 function parseManifest(input) {
-  return parseWithSchema(ManifestSchema, input, 'Manifest');
+  const manifest = parseWithSchema(ManifestSchema, input, 'Manifest');
+  delete manifest.activePhase;
+  return manifest;
 }
 
 function parseCheckpoint(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "cc-devflow",
-    "version": "4.5.8",
+    "version": "4.5.9",
     "description": "Multi-platform CLI and skill pack for agent coding",
     "main": "bin/cc-devflow.js",
     "bin": {