cc-devflow 4.3.0 → 4.4.1

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

@@ -0,0 +1,207 @@
+const { parseManifest } = require('../schemas');
+
+describe('Manifest schema hard constraints', () => {
+  test('accepts a tasks.md manifest with review and context metadata', () => {
+    const manifest = parseManifest({
+      changeId: 'REQ-555',
+      goal: 'Validate schema contract',
+      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: 'TEST',
+          phase: 1,
+          parallel: false,
+          dependsOn: [],
+          touches: ['src/counter.test.ts'],
+          files: ['src/counter.test.ts'],
+          run: ['echo "[TASK T001] Counter behavior"'],
+          checks: ['npm test -- src/counter.test.ts'],
+          acceptance: ['Prove counter behavior fails first'],
+          verification: ['npm test -- src/counter.test.ts'],
+          evidence: ['failing test output'],
+          context: {
+            readFiles: ['design.md', 'tasks.md'],
+            commands: ['npm test -- src/counter.test.ts'],
+            notes: ['Start from red']
+          },
+          reviews: {
+            spec: 'pending',
+            code: 'pending'
+          },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        },
+        {
+          id: 'T002',
+          title: '[IMPL] Counter behavior',
+          type: 'IMPL',
+          phase: 1,
+          parallel: false,
+          dependsOn: ['T001'],
+          touches: ['src/counter.ts'],
+          files: ['src/counter.ts'],
+          run: ['echo "[TASK T002] Counter behavior"'],
+          checks: ['npm test -- src/counter.test.ts'],
+          acceptance: ['Make counter behavior pass'],
+          verification: ['npm test -- src/counter.test.ts'],
+          evidence: ['passing test output'],
+          context: {
+            readFiles: ['design.md', 'src/counter.test.ts'],
+            commands: ['npm test -- src/counter.test.ts'],
+            notes: ['Smallest green implementation']
+          },
+          reviews: {
+            spec: 'pending',
+            code: 'pending'
+          },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'tasks.md',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    expect(manifest.currentTaskId).toBe('T001');
+    expect(manifest.activePhase).toBe(1);
+  });
+
+  test('rejects invalid currentTaskId for tasks.md manifest', () => {
+    expect(() => parseManifest({
+      changeId: 'REQ-556',
+      goal: 'Reject invalid current task',
+      createdAt: '2026-04-10T01:00:00.000Z',
+      updatedAt: '2026-04-10T01:05:00.000Z',
+      currentTaskId: 'T999',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: '[TEST] Counter behavior',
+          type: 'TEST',
+          phase: 1,
+          dependsOn: [],
+          run: ['echo ok'],
+          checks: ['npm test -- src/counter.test.ts'],
+          acceptance: ['Prove failure'],
+          verification: ['npm test -- src/counter.test.ts'],
+          evidence: ['failing test output'],
+          context: {
+            readFiles: ['design.md'],
+            commands: ['npm test -- src/counter.test.ts'],
+            notes: []
+          },
+          reviews: {
+            spec: 'pending',
+            code: 'pending'
+          },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'tasks.md',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    })).toThrow(/currentTaskId T999 is not present/);
+  });
+
+  test('accepts FIX ids and rejects legacy BUG ids', () => {
+    const baseManifest = {
+      goal: 'Validate fix id',
+      createdAt: '2026-04-10T01:00:00.000Z',
+      updatedAt: '2026-04-10T01:05:00.000Z',
+      currentTaskId: 'T001',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Bootstrap fix',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: [],
+          run: ['echo ok'],
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    };
+
+    expect(parseManifest({ ...baseManifest, changeId: 'FIX-556' }).changeId).toBe('FIX-556');
+    expect(() => parseManifest({ ...baseManifest, changeId: 'BUG-556' })).toThrow(/Invalid changeId format/);
+  });
+
+  test('rejects conflicting parallel tasks that share touches in same phase', () => {
+    expect(() => parseManifest({
+      changeId: 'REQ-557',
+      goal: 'Reject bad 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: ['src/shared.ts'],
+          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: ['src/shared.ts'],
+          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/);
+  });
+});

package/lib/skill-runtime/__tests__/team-state.test.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  getTeamStatePath,
+  readTeamState,
+  writeTeamState
+} = require('../team-state');
+
+describe('team-state', () => {
+  test('writes and reads the canonical truth state', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-team-state-'));
+    fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ name: 'team-state-smoke', version: '1.0.0' }, null, 2));
+
+    await writeTeamState(repoRoot, 'REQ-123', {
+      status: 'delegated',
+      phase: 'delegate',
+      branch: 'main',
+      planVersion: 4,
+      team: {
+        mode: 'parallel',
+        lead: 'main-agent',
+        teammates: [
+          {
+            id: 'delegate-01',
+            role: 'dev-implementer',
+            status: 'idle',
+            currentTask: null,
+            completedTasks: [],
+            lastActiveAt: '2026-03-26T00:00:00.000Z'
+          }
+        ],
+        taskAssignments: {
+          T001: 'delegate-01'
+        },
+        createdAt: '2026-03-26T00:00:00.000Z',
+        updatedAt: '2026-03-26T00:00:00.000Z'
+      }
+    });
+
+    const truth = JSON.parse(fs.readFileSync(getTeamStatePath(repoRoot, 'REQ-123'), 'utf8'));
+    const state = await readTeamState(repoRoot, 'REQ-123');
+
+    expect(truth.changeId).toBe('REQ-123');
+    expect(truth.team.taskAssignments.T001).toBe('delegate-01');
+    expect(state.changeId).toBe('REQ-123');
+    expect(state.planVersion).toBe(4);
+    expect(state.phase).toBe('delegate');
+  });
+});

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

@@ -0,0 +1,253 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { syncDelegationRuntime, buildWorkerHandoff, getMessageBusPath, getWorkerAssignmentPath } = require('../delegation');
+const {
+  buildProviderPrompt,
+  buildProviderCommand,
+  runWorkerCommand
+} = require('../operations/worker-run');
+const {
+  getRuntimeStatePath,
+  getTaskManifestPath,
+  getCheckpointPath,
+  getEventsPath
+} = require('../store');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function createManifest() {
+  return {
+    changeId: 'REQ-123',
+    goal: 'Run delegated worker command',
+    createdAt: '2026-03-25T01:00:00.000Z',
+    updatedAt: '2026-03-25T01:01:00.000Z',
+    tasks: [
+      {
+        id: 'T002',
+        title: 'Delegated task',
+        type: 'IMPL',
+        dependsOn: [],
+        touches: ['src/a.ts', 'src/b.ts'],
+        run: ['echo delegated'],
+        checks: [],
+        status: 'pending',
+        attempts: 0,
+        maxRetries: 1
+      }
+    ],
+    metadata: {
+      source: 'default',
+      generatedBy: 'test',
+      planVersion: 2
+    }
+  };
+}
+
+function createSharedWorkerManifest() {
+  return {
+    changeId: 'REQ-123',
+    goal: 'Run delegated worker command',
+    createdAt: '2026-03-25T01:00:00.000Z',
+    updatedAt: '2026-03-25T01:01:00.000Z',
+    tasks: [
+      {
+        id: 'T002',
+        title: 'Delegated task one',
+        type: 'IMPL',
+        dependsOn: [],
+        touches: ['src/a.ts', 'src/b.ts'],
+        run: ['echo delegated-one'],
+        checks: [],
+        status: 'pending',
+        attempts: 0,
+        maxRetries: 1
+      },
+      {
+        id: 'T003',
+        title: 'Delegated task two',
+        type: 'IMPL',
+        dependsOn: [],
+        touches: ['src/a.ts', 'src/b.ts'],
+        run: ['echo delegated-two'],
+        checks: [],
+        status: 'pending',
+        attempts: 0,
+        maxRetries: 1
+      }
+    ],
+    metadata: {
+      source: 'default',
+      generatedBy: 'test',
+      planVersion: 2
+    }
+  };
+}
+
+function setupRepoRoot(prefix) {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  fs.writeFileSync(
+    path.join(repoRoot, 'package.json'),
+    JSON.stringify({ name: 'worker-run-test', version: '1.0.0' }, null, 2)
+  );
+  writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+    changeId: 'REQ-123',
+    changeKey: 'REQ-123-run-delegated-worker-command',
+    slug: 'run-delegated-worker-command',
+    createdAt: '2026-03-25T01:00:00.000Z',
+    goal: 'Run delegated worker command',
+    status: 'planned',
+    initializedAt: '2026-03-25T01:00:00.000Z',
+    plannedAt: '2026-03-25T01:01:00.000Z',
+    updatedAt: '2026-03-25T01:01:00.000Z'
+  });
+  return repoRoot;
+}
+
+function writeManifest(repoRoot, manifest) {
+  writeJson(getTaskManifestPath(repoRoot, manifest.changeId), manifest);
+}
+
+describe('runWorkerCommand', () => {
+  test('builds thin provider launch commands for codex and claude', () => {
+    const codexCommand = buildProviderCommand({
+      provider: 'codex',
+      providerPromptPath: '/tmp/provider.md',
+      providerLastMessagePath: '/tmp/last-message.md',
+      providerTranscriptPath: '/tmp/transcript.jsonl',
+      workspace: '/tmp/worktree',
+      providerArgs: '--model gpt-5'
+    });
+    const claudeCommand = buildProviderCommand({
+      provider: 'claude',
+      providerPromptPath: '/tmp/provider.md',
+      providerLastMessagePath: '/tmp/last-message.md',
+      providerTranscriptPath: '/tmp/transcript.jsonl',
+      workspace: '/tmp/worktree',
+      providerArgs: '--model sonnet --permission-mode bypassPermissions'
+    });
+
+    expect(codexCommand).toContain('codex exec');
+    expect(codexCommand).toContain('--dangerously-bypass-approvals-and-sandbox');
+    expect(codexCommand).toContain('/tmp/transcript.jsonl');
+    expect(claudeCommand).toContain('claude -p');
+    expect(claudeCommand).toContain('--dangerously-skip-permissions');
+  });
+
+  test('runs local worker command and records only checkpoint truth by default', async () => {
+    const repoRoot = setupRepoRoot('cc-devflow-worker-run-pass-');
+    const manifest = createManifest();
+    writeManifest(repoRoot, manifest);
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+
+    const result = await runWorkerCommand({
+      repoRoot,
+      changeId: 'REQ-123',
+      workerId,
+      command: 'printf "worker-ok"'
+    });
+
+    const state = fs.readFileSync(result.sessionLogPath.replace('session.log', 'state.md'), 'utf8');
+    const journal = fs.readFileSync(result.sessionLogPath.replace('session.log', 'journal.md'), 'utf8');
+    const log = fs.readFileSync(result.sessionLogPath, 'utf8');
+    const bus = fs.readFileSync(getMessageBusPath(repoRoot, 'REQ-123'), 'utf8');
+    const assignment = fs.readFileSync(getWorkerAssignmentPath(repoRoot, 'REQ-123', workerId), 'utf8');
+    const checkpoint = JSON.parse(fs.readFileSync(getCheckpointPath(repoRoot, 'REQ-123', 'T002'), 'utf8'));
+    const nextManifest = JSON.parse(fs.readFileSync(getTaskManifestPath(repoRoot, 'REQ-123'), 'utf8'));
+    const runtimeState = JSON.parse(fs.readFileSync(getRuntimeStatePath(repoRoot, 'REQ-123'), 'utf8'));
+
+    expect(result.status).toBe('completed');
+    expect(state).toContain('Status: `completed`');
+    expect(journal).toContain('completed (exit 0)');
+    expect(log).toContain('worker-ok');
+    expect(bus).toContain(`${workerId} completed T002`);
+    expect(assignment).toContain('`T002` status=`completed`');
+    expect(checkpoint.status).toBe('passed');
+    expect(checkpoint.outputExcerpt).toContain('worker-ok');
+    expect(checkpoint.error).toBe('');
+    expect(fs.existsSync(getEventsPath(repoRoot, 'REQ-123', 'T002'))).toBe(false);
+    expect(fs.existsSync(path.join(repoRoot, 'devflow/changes/REQ-123-run-delegated-worker-command/execution/workers'))).toBe(false);
+    expect(nextManifest.tasks[0].status).toBe('passed');
+    expect(runtimeState.status).toBe('in_progress');
+  });
+
+  test('builds provider prompt from assignment plus live manifest task brief', async () => {
+    const repoRoot = setupRepoRoot('cc-devflow-worker-run-provider-');
+    const manifest = createManifest();
+    writeManifest(repoRoot, manifest);
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+    const handoff = await buildWorkerHandoff(repoRoot, 'REQ-123', workerId);
+
+    const providerPrompt = await buildProviderPrompt(repoRoot, handoff, 'T002');
+
+    expect(providerPrompt).toContain('## Worker Assignment');
+    expect(providerPrompt).toContain('## Selected Task Brief');
+    expect(providerPrompt).toContain('Task: `T002`');
+    expect(providerPrompt).toContain('Delegated task');
+  });
+
+  test('writes failure events and checkpoint error when local command exits non-zero', async () => {
+    const repoRoot = setupRepoRoot('cc-devflow-worker-run-fail-');
+    const manifest = createManifest();
+    writeManifest(repoRoot, manifest);
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+
+    const result = await runWorkerCommand({
+      repoRoot,
+      changeId: 'REQ-123',
+      workerId,
+      command: 'echo boom >&2 && exit 7'
+    });
+
+    const state = fs.readFileSync(result.sessionLogPath.replace('session.log', 'state.md'), 'utf8');
+    const log = fs.readFileSync(result.sessionLogPath, 'utf8');
+    const assignment = fs.readFileSync(getWorkerAssignmentPath(repoRoot, 'REQ-123', workerId), 'utf8');
+    const failedManifest = JSON.parse(fs.readFileSync(getTaskManifestPath(repoRoot, 'REQ-123'), 'utf8'));
+    const checkpoint = JSON.parse(fs.readFileSync(getCheckpointPath(repoRoot, 'REQ-123', 'T002'), 'utf8'));
+    const events = fs.readFileSync(getEventsPath(repoRoot, 'REQ-123', 'T002'), 'utf8');
+
+    expect(result.status).toBe('failed');
+    expect(result.result.code).toBe(7);
+    expect(state).toContain('Status: `failed`');
+    expect(log).toContain('boom');
+    expect(assignment).toContain('`T002` status=`failed`');
+    expect(checkpoint.status).toBe('failed');
+    expect(checkpoint.error).toContain('boom');
+    expect(events).toContain('worker_run_failed');
+    expect(failedManifest.tasks[0].status).toBe('failed');
+  });
+
+  test('updates only the selected task when a worker owns multiple assignments', async () => {
+    const repoRoot = setupRepoRoot('cc-devflow-worker-run-multi-');
+    const manifest = createSharedWorkerManifest();
+    writeManifest(repoRoot, manifest);
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+
+    expect(delegation.assignments.find((item) => item.taskId === 'T003').workerId).toBe(workerId);
+
+    const result = await runWorkerCommand({
+      repoRoot,
+      changeId: 'REQ-123',
+      workerId,
+      taskId: 'T003',
+      command: 'printf "worker-t003"'
+    });
+
+    const assignment = fs.readFileSync(getWorkerAssignmentPath(repoRoot, 'REQ-123', workerId), 'utf8');
+
+    expect(result.taskId).toBe('T003');
+    expect(assignment).toContain('`T003` status=`completed`');
+    expect(assignment).not.toContain('`T002` status=`completed`');
+    const nextManifest = JSON.parse(fs.readFileSync(getTaskManifestPath(repoRoot, 'REQ-123'), 'utf8'));
+    expect(nextManifest.tasks.find((task) => task.id === 'T002').status).toBe('pending');
+    expect(nextManifest.tasks.find((task) => task.id === 'T003').status).toBe('passed');
+  });
+});

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

@@ -0,0 +1,56 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { syncDelegationRuntime } = require('../delegation');
+const { runWorkerSession } = require('../operations/worker');
+
+describe('runWorkerSession', () => {
+  test('returns stable handoff bundle for a delegated worker', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-worker-session-'));
+    fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ name: 'worker-session', version: '1.0.0' }, null, 2));
+
+    const manifest = {
+      changeId: 'REQ-123',
+      goal: 'Prepare worker session',
+      createdAt: '2026-03-25T01:00:00.000Z',
+      updatedAt: '2026-03-25T01:01:00.000Z',
+      tasks: [
+        {
+          id: 'T002',
+          title: 'Multi file delegated task',
+          type: 'IMPL',
+          dependsOn: [],
+          touches: ['src/a.ts', 'src/b.ts'],
+          run: ['echo delegated'],
+          checks: [],
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 2
+      }
+    };
+
+    const delegation = await syncDelegationRuntime(repoRoot, 'REQ-123', manifest);
+    const workerId = delegation.assignments.find((item) => item.taskId === 'T002').workerId;
+    const handoff = await runWorkerSession({
+      repoRoot,
+      changeId: 'REQ-123',
+      workerId
+    });
+
+    const journal = fs.readFileSync(handoff.journalPath, 'utf8');
+    const state = fs.readFileSync(handoff.statePath, 'utf8');
+
+    expect(handoff.workerId).toBe(workerId);
+    expect(handoff.assignmentPath).toContain('assignment.md');
+    expect(handoff.taskIds).toEqual(['T002']);
+    expect(journal).toContain('handoff prepared');
+    expect(state).toContain('Status: `handoff_ready`');
+  });
+});

package/lib/skill-runtime/artifacts.js

@@ -0,0 +1,93 @@
+/**
+ * [INPUT]: 依赖 store 的目录创建能力，接收 repoRoot/goalId/taskId 等工件定位参数。
+ * [OUTPUT]: 对外提供 intent artifact 的路径约定与脚手架创建能力，不夹带阶段语义或下一步建议。
+ * [POS]: skill runtime 的纯 artifact 定位层，把路径世界与流程叙事从 intent.js 中拆开。
+ * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
+ */
+
+const { ensureDir, getReleaseNotePath } = require('./store');
+const { getChangePaths, getTaskPaths } = require('./paths');
+
+function getIntentDir(repoRoot, goalId, options = {}) {
+  return getChangePaths(repoRoot, goalId, options).changeDir;
+}
+
+function getIntentArtifactsDir(repoRoot, goalId, options = {}) {
+  return getChangePaths(repoRoot, goalId, options).executionDir;
+}
+
+function getIntentCheckpointsDir(repoRoot, goalId, options = {}) {
+  return getChangePaths(repoRoot, goalId, options).tasksDir;
+}
+
+function getIntentResumeIndexPath(repoRoot, goalId, options = {}) {
+  return `${getChangePaths(repoRoot, goalId, options).handoffDir}/resume-index.md`;
+}
+
+function getIntentPrBriefPath(repoRoot, goalId, options = {}) {
+  return `${getChangePaths(repoRoot, goalId, options).handoffDir}/pr-brief.md`;
+}
+
+function getIntentStatusPath(repoRoot, goalId, options = {}) {
+  return `${getChangePaths(repoRoot, goalId, options).handoffDir}/status.md`;
+}
+
+function getIntentHandoffArtifactPaths(repoRoot, goalId, options = {}) {
+  return [
+    getIntentPrBriefPath(repoRoot, goalId, options),
+    getIntentResumeIndexPath(repoRoot, goalId, options),
+    getReleaseNotePath(repoRoot, goalId, options),
+    getIntentStatusPath(repoRoot, goalId, options)
+  ];
+}
+
+function getLegacyIntentProjectionPaths(repoRoot, goalId, taskIds = [], options = {}) {
+  const change = getChangePaths(repoRoot, goalId, options);
+  const taskFiles = taskIds.flatMap((taskId) => {
+    const task = getTaskPaths(repoRoot, goalId, taskId, options);
+    return [
+      `${task.taskDir}/brief.md`,
+      `${task.taskDir}/checkpoint.md`,
+      `${task.taskDir}/result.md`,
+      `${task.taskDir}/review-spec.md`,
+      `${task.taskDir}/review-code.md`
+    ];
+  });
+
+  return [
+    `${change.metaDir}/index.json`,
+    `${change.planningDir}/planning-snapshot.md`,
+    `${change.planningDir}/facts.md`,
+    `${change.planningDir}/decision-log.md`,
+    `${change.planningDir}/plan.md`,
+    `${change.executionDir}/team-memory.md`,
+    `${change.executionDir}/message-bus.md`,
+    `${change.executionDir}/delegation-map.md`,
+    getIntentStatusPath(repoRoot, goalId, options),
+    ...taskFiles
+  ];
+}
+
+async function ensureIntentScaffold(repoRoot, goalId) {
+  const change = getChangePaths(repoRoot, goalId);
+
+  await ensureDir(change.changeDir);
+  await ensureDir(change.metaDir);
+  await ensureDir(change.planningDir);
+  await ensureDir(change.executionDir);
+  await ensureDir(change.tasksDir);
+  await ensureDir(change.reviewDir);
+  await ensureDir(change.handoffDir);
+}
+
+module.exports = {
+  getIntentDir,
+  getIntentArtifactsDir,
+  getIntentCheckpointsDir,
+  getIntentResumeIndexPath,
+  getIntentPrBriefPath,
+  getIntentStatusPath,
+  getIntentHandoffArtifactPaths,
+  getLegacyIntentProjectionPaths,
+  ensureIntentScaffold
+};