cc-devflow 4.5.3 → 4.5.4

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

@@ -0,0 +1,92 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { runApprove } = require('../operations/approve');
+const {
+  getRuntimeStatePath,
+  getTaskManifestPath
+} = require('../store');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+describe('runApprove', () => {
+  test('throws named error when change-state is missing', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-approve-missing-state-'));
+
+    await expect(runApprove({
+      repoRoot,
+      changeId: 'REQ-123',
+      executionMode: 'direct'
+    })).rejects.toMatchObject({
+      name: 'MissingChangeStateError',
+      artifactRefs: [
+        expect.stringContaining('change-state.json')
+      ],
+      rescueAction: 'run cc-roadmap or cc-plan init before approving execution'
+    });
+  });
+
+  test('throws named error when task manifest is missing', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-approve-missing-manifest-'));
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Approve only concrete plans',
+      status: 'planned',
+      initializedAt: '2026-03-25T01:00:00.000Z',
+      updatedAt: '2026-03-25T01:00:00.000Z'
+    });
+
+    await expect(runApprove({
+      repoRoot,
+      changeId: 'REQ-123',
+      executionMode: 'direct'
+    })).rejects.toMatchObject({
+      name: 'MissingTaskManifestError',
+      artifactRefs: [
+        expect.stringContaining('task-manifest.json')
+      ],
+      rescueAction: 'run cc-plan to create planning/task-manifest.json before approving execution'
+    });
+  });
+
+  test('approves the current manifest plan version', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-approve-pass-'));
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Approve current plan',
+      status: 'planned',
+      initializedAt: '2026-03-25T01:00:00.000Z',
+      updatedAt: '2026-03-25T01:00:00.000Z'
+    });
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Approve current plan',
+      createdAt: '2026-03-25T01:00:00.000Z',
+      updatedAt: '2026-03-25T01:00:00.000Z',
+      tasks: [],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 7
+      }
+    });
+
+    const result = await runApprove({
+      repoRoot,
+      changeId: 'REQ-123',
+      executionMode: 'direct'
+    });
+
+    expect(result).toMatchObject({
+      status: 'approved',
+      executionMode: 'direct',
+      planVersion: 7
+    });
+  });
+});

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

@@ -34,6 +34,10 @@ function markManifestReviewsPassed(repoRoot, changeId) {
       code: 'pass'
     }
   }));
+  manifest.spec = manifest.spec || {
+    primaryCapability: 'autopilot-runtime',
+    specFiles: ['devflow/specs/autopilot-runtime.md']
+  };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 

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

@@ -7,6 +7,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { spawnSync } = require('child_process');
 
 const { parseTasksMarkdown, createTaskManifest, deriveManifestExecutionState } = require('../planner');
 
@@ -64,6 +65,25 @@ describe('TDD Order Validation', () => {
       expect(tasks[1].context.readFiles).toEqual(['design.md', 'src/counter.test.ts']);
     });
 
+    test('should quote generated run command titles as shell data', () => {
+      const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-planner-shell-'));
+      const markerPath = path.join(repoRoot, 'pwned');
+      const markdown = `
+- [ ] T001 hostile title " && touch ${markerPath} && echo "
+      `.trim();
+
+      const [task] = parseTasksMarkdown(markdown);
+      const result = spawnSync(task.run[0], {
+        cwd: repoRoot,
+        shell: true,
+        encoding: 'utf8'
+      });
+
+      expect(result.status).toBe(0);
+      expect(result.stdout).toContain('hostile title');
+      expect(fs.existsSync(markerPath)).toBe(false);
+    });
+
     test('should backfill minimum metadata for TEST and IMPL tasks from plain TASKS lines', () => {
       const markdown = `
 ## Phase 1: Build

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

@@ -2,7 +2,13 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
-const { getFullState, getNextTask, getProgress } = require('../query');
+const {
+  getFullState,
+  getNextTask,
+  getProgress,
+  listQueryIds,
+  runQuery
+} = require('../query');
 const {
   getRuntimeStatePath,
   getTaskManifestPath,
@@ -281,4 +287,144 @@ describe('query helpers', () => {
 
     expect(next.id).toBe('T002');
   });
+
+  test('dispatches typed query ids with trace metadata', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-registry-'));
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-126'), {
+      changeId: 'REQ-126',
+      goal: 'Expose typed query registry',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      tasks: [
+        { id: 'T001', status: 'pending' }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    await expect(runQuery('progress', { repoRoot, changeId: 'REQ-126' })).resolves.toMatchObject({
+      ok: true,
+      queryId: 'progress',
+      data: {
+        totalTasks: 1,
+        pendingTasks: 1
+      },
+      trace: {
+        artifactRefs: expect.arrayContaining([
+          expect.stringContaining('task-manifest.json')
+        ]),
+        nextAction: 'read-query-result'
+      }
+    });
+
+    expect(listQueryIds()).toEqual(expect.arrayContaining(['full-state', 'next-task', 'progress']));
+  });
+
+  test('returns a named error for unknown query ids', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-unknown-'));
+
+    await expect(runQuery('unknown-query', { repoRoot, changeId: 'REQ-127' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'unknown-query',
+      error: {
+        name: 'UnknownQueryError',
+        rescueAction: 'use one of: full-state, next-task, progress, ship-readiness'
+      },
+      trace: {
+        nextAction: 'choose-supported-query'
+      }
+    });
+  });
+
+  test('returns a named error when typed queries miss required artifacts', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-missing-manifest-'));
+
+    await expect(runQuery('progress', { repoRoot, changeId: 'REQ-130' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'progress',
+      error: {
+        name: 'MissingQueryArtifactError',
+        artifactRefs: [
+          expect.stringContaining('task-manifest.json')
+        ],
+        rescueAction: 'create required runtime artifacts before running this query'
+      },
+      trace: {
+        event: 'query.progress.failed',
+        nextAction: 'create required runtime artifacts before running this query'
+      }
+    });
+  });
+
+  test('returns a named error when required query artifacts are malformed', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-invalid-manifest-'));
+    const manifestPath = getTaskManifestPath(repoRoot, 'REQ-131');
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, '{bad json\n');
+
+    await expect(runQuery('progress', { repoRoot, changeId: 'REQ-131' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'progress',
+      error: {
+        name: 'InvalidQueryArtifactError',
+        artifactRefs: [
+          expect.stringContaining('task-manifest.json')
+        ],
+        rescueAction: 'repair or regenerate the invalid runtime artifact before running this query'
+      },
+      trace: {
+        event: 'query.progress.failed',
+        nextAction: 'repair or regenerate the invalid runtime artifact before running this query'
+      }
+    });
+  });
+
+  test('returns MissingReportCardError for ship readiness without report card', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-missing-report-'));
+
+    await expect(runQuery('ship-readiness', { repoRoot, changeId: 'REQ-128' })).resolves.toMatchObject({
+      ok: false,
+      queryId: 'ship-readiness',
+      error: {
+        name: 'MissingReportCardError',
+        artifactRefs: [
+          expect.stringContaining('report-card.json')
+        ],
+        rescueAction: 'run cc-check and create review/report-card.json before cc-act'
+      },
+      trace: {
+        nextAction: 'run cc-check and create review/report-card.json before cc-act'
+      }
+    });
+  });
+
+  test('reports ship readiness from report-card truth', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-ship-ready-'));
+
+    writeJson(getReportCardPath(repoRoot, 'REQ-129'), {
+      changeId: 'REQ-129',
+      verdict: 'pass',
+      overall: 'pass',
+      reroute: 'none',
+      specSyncReady: true,
+      blockingFindings: [],
+      timestamp: '2026-03-25T01:11:00.000Z'
+    });
+
+    await expect(runQuery('ship-readiness', { repoRoot, changeId: 'REQ-129' })).resolves.toMatchObject({
+      ok: true,
+      queryId: 'ship-readiness',
+      data: {
+        ready: true,
+        verdict: 'pass',
+        reroute: 'none',
+        specSyncReady: true,
+        blockers: []
+      }
+    });
+  });
 });

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

@@ -0,0 +1,53 @@
+const {
+  assertShipReady,
+  deriveShipReadiness
+} = require('../readiness');
+
+describe('ship readiness', () => {
+  test('derives one shared readiness verdict from report-card truth', () => {
+    const report = {
+      verdict: 'pass',
+      overall: 'pass',
+      reroute: 'none',
+      specSyncReady: true,
+      blockingFindings: [],
+      gaps: [],
+      timestamp: '2026-03-25T01:11:00.000Z'
+    };
+
+    expect(deriveShipReadiness(report, { reportPath: '/tmp/report-card.json' })).toEqual({
+      ready: true,
+      verdict: 'pass',
+      reroute: 'none',
+      specSyncReady: true,
+      blockers: [],
+      reportPath: '/tmp/report-card.json',
+      timestamp: '2026-03-25T01:11:00.000Z'
+    });
+  });
+
+  test('throws named release errors from the same readiness blockers', () => {
+    const report = {
+      verdict: 'pass',
+      overall: 'pass',
+      reroute: 'cc-do',
+      specSyncReady: false,
+      blockingFindings: ['review: stale'],
+      gaps: ['spec gap'],
+      timestamp: '2026-03-25T01:11:00.000Z'
+    };
+
+    expect(() => assertShipReady(report, {
+      reportPath: '/tmp/report-card.json',
+      errorName: 'ReleaseReadinessError',
+      rescueAction: 'run cc-check until ship-readiness is ready before release'
+    })).toThrow(expect.objectContaining({
+      name: 'ReleaseReadinessError',
+      artifactRefs: ['/tmp/report-card.json'],
+      rescueAction: 'run cc-check until ship-readiness is ready before release',
+      details: {
+        blockers: ['reroute is cc-do', 'specSyncReady is not true', 'review: stale', 'spec gap']
+      }
+    }));
+  });
+});

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

@@ -0,0 +1,85 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { runRelease } = require('../operations/release');
+const {
+  getRuntimeStatePath,
+  getTaskManifestPath,
+  getReportCardPath,
+  getReleaseNotePath
+} = require('../store');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeReleaseFixture(repoRoot, reportOverrides = {}) {
+  writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+    changeId: 'REQ-123',
+    goal: 'Release only when ship ready',
+    status: 'verified',
+    initializedAt: '2026-03-25T01:00:00.000Z',
+    plannedAt: '2026-03-25T01:01:00.000Z',
+    verifiedAt: '2026-03-25T01:02:00.000Z',
+    updatedAt: '2026-03-25T01:02:00.000Z'
+  });
+
+  writeJson(getTaskManifestPath(repoRoot, 'REQ-123'), {
+    changeId: 'REQ-123',
+    goal: 'Release only when ship ready',
+    createdAt: '2026-03-25T01:00:00.000Z',
+    updatedAt: '2026-03-25T01:02:00.000Z',
+    tasks: [
+      {
+        id: 'T001',
+        title: 'Finish change',
+        type: 'IMPL',
+        dependsOn: [],
+        touches: ['src/a.ts'],
+        run: ['echo ok'],
+        checks: [],
+        status: 'passed',
+        attempts: 1,
+        maxRetries: 1
+      }
+    ],
+    metadata: {
+      source: 'default',
+      generatedBy: 'test',
+      planVersion: 1
+    }
+  });
+
+  writeJson(getReportCardPath(repoRoot, 'REQ-123'), {
+    changeId: 'REQ-123',
+    verdict: 'pass',
+    overall: 'pass',
+    specSyncReady: false,
+    reroute: 'cc-do',
+    quickGates: [],
+    strictGates: [],
+    review: { status: 'pass', summary: 'review-ok', details: '' },
+    blockingFindings: [],
+    gaps: [],
+    timestamp: '2026-03-25T01:03:00.000Z',
+    ...reportOverrides
+  });
+}
+
+describe('runRelease', () => {
+  test('blocks reports that pass verification but are not ship ready', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-release-readiness-'));
+    writeReleaseFixture(repoRoot);
+
+    await expect(runRelease({ repoRoot, changeId: 'REQ-123' })).rejects.toMatchObject({
+      name: 'ReleaseReadinessError',
+      rescueAction: 'run cc-check until ship-readiness is ready before release'
+    });
+
+    const runtimeState = JSON.parse(fs.readFileSync(getRuntimeStatePath(repoRoot, 'REQ-123'), 'utf8'));
+    expect(runtimeState.status).toBe('verified');
+    expect(fs.existsSync(getReleaseNotePath(repoRoot, 'REQ-123'))).toBe(false);
+  });
+});

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

@@ -91,6 +91,16 @@ describe('Skill runtime', () => {
     fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   }
 
+  async function markManifestSpec(changeId) {
+    const manifestPath = getTaskManifestPath(repoRoot, changeId);
+    const manifest = await readJson(manifestPath);
+    manifest.spec = {
+      primaryCapability: 'skill-runtime-pipeline',
+      specFiles: ['devflow/specs/skill-runtime.md']
+    };
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  }
+
   test('runs init -> snapshot -> plan -> dispatch -> verify -> release', async () => {
     const changeId = 'REQ-999';
     await runInit({ repoRoot, changeId, goal: 'Test skill runtime pipeline' });
@@ -121,6 +131,7 @@ describe('Skill runtime', () => {
     const manifest = await readJson(getTaskManifestPath(repoRoot, changeId));
     expect(manifest.tasks.every((task) => task.status === 'passed')).toBe(true);
 
+    await markManifestSpec(changeId);
     await markManifestReviews(changeId, 'pass');
 
     const verifyResult = await runVerify({

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

@@ -204,4 +204,60 @@ describe('Manifest schema hard constraints', () => {
       }
     })).toThrow(/share touches/);
   });
+
+  test('rejects conflicting parallel tasks with nested touches in same phase', () => {
+    expect(() => parseManifest({
+      changeId: 'REQ-558',
+      goal: 'Reject nested parallel plan',
+      createdAt: '2026-04-10T01:00:00.000Z',
+      updatedAt: '2026-04-10T01:05:00.000Z',
+      currentTaskId: 'T001',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: '[TEST] A',
+          type: 'TEST',
+          phase: 1,
+          parallel: true,
+          dependsOn: [],
+          touches: ['packages/billing'],
+          run: ['echo ok'],
+          checks: ['npm test -- a'],
+          acceptance: ['Prove A fails'],
+          verification: ['npm test -- a'],
+          evidence: ['failing output'],
+          context: { readFiles: ['design.md'], commands: ['npm test -- a'], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        },
+        {
+          id: 'T002',
+          title: '[TEST] B',
+          type: 'TEST',
+          phase: 1,
+          parallel: true,
+          dependsOn: [],
+          touches: ['packages/billing/src/invoices.js'],
+          run: ['echo ok'],
+          checks: ['npm test -- b'],
+          acceptance: ['Prove B fails'],
+          verification: ['npm test -- b'],
+          evidence: ['failing output'],
+          context: { readFiles: ['design.md'], commands: ['npm test -- b'], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'tasks.md',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    })).toThrow(/share touches: packages\/billing/);
+  });
 });

package/lib/skill-runtime/__tests__/worker-run.test.js

@@ -250,4 +250,33 @@ describe('runWorkerCommand', () => {
     expect(nextManifest.tasks.find((task) => task.id === 'T002').status).toBe('pending');
     expect(nextManifest.tasks.find((task) => task.id === 'T003').status).toBe('passed');
   });
+
+  test('blocks stale worker assignments when manifest planVersion has moved on', async () => {
+    const repoRoot = setupRepoRoot('cc-devflow-worker-run-stale-plan-');
+    const manifest = createManifest();
+    writeManifest(repoRoot, manifest);
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+
+    writeManifest(repoRoot, {
+      ...manifest,
+      metadata: {
+        ...manifest.metadata,
+        planVersion: 3
+      }
+    });
+
+    await expect(runWorkerCommand({
+      repoRoot,
+      changeId: 'REQ-123',
+      workerId,
+      command: 'printf "should-not-run" > blocked.txt'
+    })).rejects.toMatchObject({
+      name: 'StalePlanVersionError',
+      rescueAction: 'rerun delegation sync for current planVersion before worker-run'
+    });
+
+    expect(fs.existsSync(path.join(repoRoot, 'blocked.txt'))).toBe(false);
+    expect(fs.existsSync(getCheckpointPath(repoRoot, 'REQ-123', 'T002'))).toBe(false);
+  });
 });

package/lib/skill-runtime/errors.js

@@ -0,0 +1,39 @@
+/**
+ * [INPUT]: 接收 runtime/query/compiler 边界抛出的错误或失败字段。
+ * [OUTPUT]: 生成可序列化 named error，保留 artifact refs 与 rescue action。
+ * [POS]: skill runtime 的失败语义层，避免用 null/false/string 表达可恢复失败。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+class SkillRuntimeError extends Error {
+  constructor(name, message, options = {}) {
+    super(message);
+    this.name = name;
+    this.artifactRefs = options.artifactRefs || [];
+    this.rescueAction = options.rescueAction || 'inspect-runtime-artifacts';
+    this.details = options.details || {};
+  }
+}
+
+function namedError(name, message, options = {}) {
+  return new SkillRuntimeError(name, message, options);
+}
+
+function serializeError(error, fallbackName = 'SkillRuntimeError') {
+  const name = error?.name || fallbackName;
+  const message = error?.message || String(error || 'Unknown runtime error');
+
+  return {
+    name,
+    message,
+    artifactRefs: error?.artifactRefs || [],
+    rescueAction: error?.rescueAction || 'inspect-runtime-artifacts',
+    details: error?.details || {}
+  };
+}
+
+module.exports = {
+  SkillRuntimeError,
+  namedError,
+  serializeError
+};

package/lib/skill-runtime/index.js

@@ -9,6 +9,10 @@ const store = require('./store');
 const schemas = require('./schemas');
 const planner = require('./planner');
 const query = require('./query');
+const queryRegistry = require('./query-registry');
+const errors = require('./errors');
+const trace = require('./trace');
+const readiness = require('./readiness');
 const intent = require('./intent');
 const artifacts = require('./artifacts');
 const lifecycle = require('./lifecycle');
@@ -24,6 +28,10 @@ module.exports = {
   ...schemas,
   ...planner,
   ...query,
+  ...queryRegistry,
+  ...errors,
+  ...trace,
+  ...readiness,
   ...artifacts,
   ...intent,
   ...lifecycle,

package/lib/skill-runtime/operations/approve.js

@@ -15,6 +15,7 @@ const {
 const { parseRuntimeState, parseManifest } = require('../schemas');
 const { syncIntentMemory } = require('../intent');
 const { normalizeExecutionMode } = require('../lifecycle');
+const { namedError } = require('../errors');
 
 async function runApprove({ repoRoot, changeId, executionMode }) {
   const statePath = getRuntimeStatePath(repoRoot, changeId);
@@ -23,11 +24,25 @@ async function runApprove({ repoRoot, changeId, executionMode }) {
   const rawManifest = await readJson(manifestPath, null);
 
   if (!rawState) {
-    throw new Error(`Cannot approve ${changeId}: change-state.json is missing`);
+    throw namedError(
+      'MissingChangeStateError',
+      `Cannot approve ${changeId}: change-state.json is missing`,
+      {
+        artifactRefs: [statePath],
+        rescueAction: 'run cc-roadmap or cc-plan init before approving execution'
+      }
+    );
   }
 
   if (!rawManifest) {
-    throw new Error(`Cannot approve ${changeId}: task-manifest.json is missing`);
+    throw namedError(
+      'MissingTaskManifestError',
+      `Cannot approve ${changeId}: task-manifest.json is missing`,
+      {
+        artifactRefs: [manifestPath],
+        rescueAction: 'run cc-plan to create planning/task-manifest.json before approving execution'
+      }
+    );
   }
 
   const state = parseRuntimeState(rawState);

package/lib/skill-runtime/operations/release.js

@@ -17,6 +17,7 @@ const {
 } = require('../store');
 const { parseReportCard, parseManifest } = require('../schemas');
 const { syncIntentMemory } = require('../intent');
+const { assertShipReady } = require('../readiness');
 
 function formatReleaseNote({ changeId, manifest, report }) {
   const passedTasks = manifest.tasks.filter((task) => task.status === 'passed');
@@ -59,9 +60,11 @@ async function runRelease({ repoRoot, changeId }) {
   const manifest = parseManifest(await readJson(manifestPath));
   const previousState = await readJson(statePath, null);
 
-  if (report.overall !== 'pass') {
-    throw new Error('Release blocked: report-card overall is not pass');
-  }
+  assertShipReady(report, {
+    reportPath,
+    errorName: 'ReleaseReadinessError',
+    rescueAction: 'run cc-check until ship-readiness is ready before release'
+  });
 
   const note = formatReleaseNote({ changeId, manifest, report });
   const releaseNotePath = getReleaseNotePath(repoRoot, changeId);