cc-devflow 4.5.3 → 4.5.5

package/lib/compiler/inventory.js

@@ -0,0 +1,78 @@
+/**
+ * [INPUT]: 接收 repo root 与 distributable skill 配置。
+ * [OUTPUT]: 校验 managed skill inventory 与 Codex mirror inventory 是否一致。
+ * [POS]: compiler/publish gate 的清单奇偶校验层，防止新增 skill 逃出配置与 mirror 管理。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function listSkillDirs(root, relativeRoot) {
+  const skillsRoot = path.join(root, relativeRoot);
+
+  if (!fs.existsSync(skillsRoot)) {
+    return [];
+  }
+
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => fs.existsSync(path.join(skillsRoot, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function missingFrom(expected, actual) {
+  return expected.filter((item) => !actual.includes(item));
+}
+
+function extraFrom(actual, expected) {
+  return actual.filter((item) => !expected.includes(item));
+}
+
+function validateSkillInventory({
+  root,
+  publicSkills = [],
+  distributedSkills = [],
+  internalSkills = [],
+  codexSkills: expectedCodexSkills = publicSkills
+}) {
+  const errors = [];
+  const configured = [...new Set([...distributedSkills, ...internalSkills])].sort();
+  const sourceSkills = listSkillDirs(root, '.claude/skills');
+
+  for (const skillName of missingFrom(distributedSkills, sourceSkills)) {
+    errors.push(`Missing distributed skill directory: ${skillName}`);
+  }
+
+  for (const skillName of extraFrom(sourceSkills, configured)) {
+    errors.push(`Unconfigured skill directory: ${skillName}`);
+  }
+
+  for (const skillName of publicSkills) {
+    const playbookPath = path.join(root, '.claude/skills', skillName, 'PLAYBOOK.md');
+    if (!fs.existsSync(playbookPath)) {
+      errors.push(`Public skill missing PLAYBOOK.md: ${skillName}`);
+    }
+  }
+
+  const codexRoot = path.join(root, '.codex/skills');
+  if (fs.existsSync(codexRoot)) {
+    const actualCodexSkills = listSkillDirs(root, '.codex/skills');
+
+    for (const skillName of missingFrom(expectedCodexSkills, actualCodexSkills)) {
+      errors.push(`Codex mirror missing public skill: ${skillName}`);
+    }
+
+    for (const skillName of extraFrom(actualCodexSkills, expectedCodexSkills)) {
+      errors.push(`Codex mirror has unconfigured public skill: ${skillName}`);
+    }
+  }
+
+  return errors;
+}
+
+module.exports = {
+  listSkillDirs,
+  validateSkillInventory
+};

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__/cli-bootstrap.integration.test.js

@@ -229,6 +229,11 @@ describe('cc-devflow cli distribution bootstrap', () => {
     );
     expect(codexRoadmapSkill.data.writes).toEqual(
       expect.arrayContaining([
+        expect.objectContaining({
+          path: 'devflow/roadmap.json',
+          durability: 'durable',
+          required: true
+        }),
         expect.objectContaining({
           path: 'devflow/ROADMAP.md',
           durability: 'durable',
@@ -237,10 +242,13 @@ describe('cc-devflow cli distribution bootstrap', () => {
         expect.objectContaining({
           path: 'devflow/BACKLOG.md',
           durability: 'durable',
-          required: true
+          required: false
         })
       ])
     );
+    expect(codexRoadmapSkill.data.writes).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ path: 'devflow/roadmap-tracking.json', required: true })])
+    );
   });
 
   test('adapt mirrors Codex skills without baking project YAML output policy', () => {

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);
+  });
 });