cc-devflow 4.3.0 → 4.5.0

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

@@ -0,0 +1,250 @@
+/**
+ * TDD Order Validation Tests
+ *
+ * Tests for Constitution Article VI enforcement in planner.js
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { parseTasksMarkdown, createTaskManifest, deriveManifestExecutionState } = require('../planner');
+
+describe('TDD Order Validation', () => {
+  describe('Rich task metadata parsing', () => {
+    test('should preserve phase, files, acceptance, verification, evidence and context', () => {
+      const markdown = `
+## Phase 1: Foundation
+
+- [ ] T001 [TEST] Counter behavior (dependsOn:none) \`src/counter.test.ts\`
+  Goal: prove the current behavior is broken first
+  Files: \`src/counter.test.ts\`
+  Read first: \`design.md\`, \`tasks.md\`
+  Verification: npm test -- src/counter.test.ts
+  Evidence: failing output, screenshot
+
+- [ ] T002 [P] [IMPL] Counter behavior (dependsOn:T001) \`src/counter.ts\`
+  Goal: make the counter test pass
+  Files: \`src/counter.ts\`
+  Read first: \`design.md\`, \`src/counter.test.ts\`
+  Verification: npm test -- src/counter.test.ts
+  Evidence: passing output, review notes
+      `.trim();
+
+      const tasks = parseTasksMarkdown(markdown);
+
+      expect(tasks).toHaveLength(2);
+      expect(tasks[0]).toMatchObject({
+        id: 'T001',
+        phase: 1,
+        parallel: false,
+        type: 'TEST',
+        files: ['src/counter.test.ts'],
+        touches: ['src/counter.test.ts'],
+        acceptance: ['prove the current behavior is broken first'],
+        verification: ['npm test -- src/counter.test.ts'],
+        evidence: ['failing output', 'screenshot'],
+        reviews: { spec: 'pending', code: 'pending' }
+      });
+      expect(tasks[0].checks).toContain('npm test -- src/counter.test.ts');
+      expect(tasks[0].context.readFiles).toEqual(['design.md', 'tasks.md']);
+      expect(tasks[0].context.commands).toContain('npm test -- src/counter.test.ts');
+
+      expect(tasks[1]).toMatchObject({
+        id: 'T002',
+        phase: 1,
+        parallel: true,
+        type: 'IMPL',
+        files: ['src/counter.ts'],
+        touches: ['src/counter.ts'],
+        acceptance: ['make the counter test pass'],
+        verification: ['npm test -- src/counter.test.ts'],
+        evidence: ['passing output', 'review notes']
+      });
+      expect(tasks[1].context.readFiles).toEqual(['design.md', 'src/counter.test.ts']);
+    });
+
+    test('should backfill minimum metadata for TEST and IMPL tasks from plain TASKS lines', () => {
+      const markdown = `
+## Phase 1: Build
+
+- [ ] T001 [TEST] Counter behavior \`src/counter.test.ts\`
+- [ ] T002 [IMPL] Counter behavior (dependsOn:T001) \`src/counter.ts\`
+      `.trim();
+
+      const tasks = parseTasksMarkdown(markdown);
+
+      expect(tasks[0].acceptance).toEqual(['Prove Counter behavior fails before implementation']);
+      expect(tasks[0].verification).toEqual(['npm test -- src/counter.test.ts']);
+      expect(tasks[0].evidence).toEqual(['failing test output']);
+      expect(tasks[0].context.readFiles).toEqual(['design.md', 'tasks.md', 'src/counter.test.ts']);
+
+      expect(tasks[1].acceptance).toEqual(['Make Counter behavior pass with the smallest implementation']);
+      expect(tasks[1].verification).toEqual(['echo "verify T002"']);
+      expect(tasks[1].evidence).toEqual(['passing test output']);
+      expect(tasks[1].context.readFiles).toEqual(['design.md']);
+    });
+  });
+
+  describe('Manifest execution state', () => {
+    test('should derive active phase and current task from ready tasks', () => {
+      const state = deriveManifestExecutionState([
+        { id: 'T001', phase: 1, status: 'passed', dependsOn: [] },
+        { id: 'T002', phase: 2, status: 'pending', dependsOn: ['T001'] },
+        { id: 'T003', phase: 2, status: 'pending', dependsOn: ['T002'] }
+      ]);
+
+      expect(state).toEqual({
+        currentTaskId: 'T002',
+        activePhase: 2
+      });
+    });
+
+    test('should write currentTaskId and activePhase into manifest', 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');
+      fs.mkdirSync(path.dirname(tasksPath), { recursive: true });
+      fs.writeFileSync(
+        tasksPath,
+        [
+          '## Phase 1: Foundation',
+          '',
+          '- [x] T001 [TEST] Setup smoke test `src/setup.test.ts`',
+          '- [ ] T002 [IMPL] Setup smoke test (dependsOn:T001) `src/setup.ts`',
+          '',
+          '## Phase 2: Verify',
+          '',
+          '- [ ] T003 Run final verification'
+        ].join('\n')
+      );
+
+      const manifest = await createTaskManifest({
+        repoRoot,
+        changeId,
+        goal: 'Exercise manifest execution state',
+        overwrite: true
+      });
+
+      expect(manifest.activePhase).toBe(1);
+      expect(manifest.currentTaskId).toBe('T002');
+      expect(manifest.tasks[1].reviews).toEqual({ spec: 'pending', code: 'pending' });
+    });
+  });
+
+  describe('Valid TDD sequences', () => {
+    test('should accept TEST before IMPL with correct dependency', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录功能测试
+- [ ] T002 [IMPL] 用户登录功能实现 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should accept multiple TEST-IMPL pairs', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+- [ ] T003 [TEST] 用户注册测试 [P]
+- [ ] T004 [IMPL] 用户注册实现 (dependsOn:T003)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should accept tasks without TEST/IMPL markers', () => {
+      const markdown = `
+- [ ] T001 初始化项目结构
+- [ ] T002 配置开发环境
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+  });
+
+  describe('TDD violations', () => {
+    test('should reject IMPL without corresponding TEST', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 用户登录功能实现
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /missing corresponding TEST task/
+      );
+    });
+
+    test('should reject IMPL not depending on TEST', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户登录功能测试
+- [ ] T002 [IMPL] 用户登录功能实现 [P]
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /must depend on T001/
+      );
+    });
+
+    test('should reject TEST depending on IMPL', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 用户登录功能实现
+- [ ] T002 [TEST] 用户登录功能测试 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /Tests must be written BEFORE implementation/
+      );
+    });
+
+    test('should reject IMPL depending on wrong TEST', () => {
+      const markdown = `
+- [ ] T001 [TEST] 用户注册测试
+- [ ] T002 [IMPL] 用户登录实现 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).toThrow(
+        /missing corresponding TEST task/
+      );
+    });
+  });
+
+  describe('Feature name extraction', () => {
+    test('should match TEST and IMPL with same feature name', () => {
+      const markdown = `
+- [ ] T001 [TEST] 实现用户认证功能
+- [ ] T002 [IMPL] 实现用户认证功能 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+
+    test('should handle case-insensitive markers', () => {
+      const markdown = `
+- [ ] T001 [test] 用户登录
+- [ ] T002 [impl] 用户登录 (dependsOn:T001)
+      `.trim();
+
+      expect(() => parseTasksMarkdown(markdown)).not.toThrow();
+    });
+  });
+
+  describe('Error messages', () => {
+    test('should provide clear violation details', () => {
+      const markdown = `
+- [ ] T001 [IMPL] 功能A
+- [ ] T002 [TEST] 功能B
+- [ ] T003 [IMPL] 功能B
+      `.trim();
+
+      try {
+        parseTasksMarkdown(markdown);
+        fail('Should have thrown TDD violation error');
+      } catch (error) {
+        expect(error.message).toContain('TDD Order Validation Failed');
+        expect(error.message).toContain('Constitution Article VI');
+        expect(error.message).toContain('T001');
+        expect(error.message).toContain('missing corresponding TEST task');
+      }
+    });
+  });
+});

package/lib/skill-runtime/__tests__/prepare-pr.test.js

@@ -0,0 +1,139 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { runPreparePr } = require('../operations/prepare-pr');
+const {
+  getRuntimeStatePath,
+  getTaskManifestPath,
+  getReportCardPath,
+  getCheckpointPath
+} = require('../store');
+const {
+  getIntentPrBriefPath,
+  getIntentHandoffArtifactPaths
+} = require('../artifacts');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeText(filePath, content = 'stale\n') {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+}
+
+describe('runPreparePr', () => {
+  test('generates pr brief and keeps it as the only handoff artifact', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-prepare-pr-'));
+    const prBriefPath = getIntentPrBriefPath(repoRoot, 'REQ-123');
+
+    writeJson(path.join(repoRoot, 'package.json'), {
+      name: 'prepare-pr-test',
+      version: '1.0.0'
+    });
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      changeKey: 'REQ-123-prepare-a-pr-ready-brief',
+      slug: 'prepare-a-pr-ready-brief',
+      createdAt: '2026-03-25T01:00:00.000Z',
+      goal: 'Prepare a PR-ready brief',
+      status: 'verified',
+      initializedAt: '2026-03-25T01:00:00.000Z',
+      plannedAt: '2026-03-25T01:05:00.000Z',
+      verifiedAt: '2026-03-25T01:10:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z'
+    });
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Prepare a PR-ready brief',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Finish delivery',
+          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',
+      overall: 'pass',
+      quickGates: [
+        { name: 'lint', status: 'pass', command: 'npm run lint', durationMs: 10, details: '' }
+      ],
+      strictGates: [
+        { name: 'test', status: 'pass', command: 'npm test', durationMs: 20, details: '' }
+      ],
+      review: {
+        status: 'pass',
+        summary: 'review-ok',
+        details: '',
+        findings: [],
+        taskReviews: { status: 'pass', required: true, summary: '', reviewers: [], findings: [] },
+        diffReview: { status: 'pass', required: true, summary: '', reviewers: [], findings: [] }
+      },
+      blockingFindings: [],
+      timestamp: '2026-03-25T01:11:00.000Z'
+    });
+
+    writeJson(getCheckpointPath(repoRoot, 'REQ-123', 'T001'), {
+      changeId: 'REQ-123',
+      taskId: 'T001',
+      sessionId: 'task-session',
+      planVersion: 1,
+      status: 'passed',
+      summary: 'Task passed after 1 attempt',
+      error: '',
+      outputExcerpt: 'ok',
+      timestamp: '2026-03-25T01:09:00.000Z',
+      attempt: 1
+    });
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      ...JSON.parse(fs.readFileSync(getRuntimeStatePath(repoRoot, 'REQ-123'), 'utf8')),
+      approval: {
+        status: 'approved',
+        executionMode: 'direct',
+        planVersion: 1,
+        approvedAt: '2026-03-25T01:06:00.000Z'
+      }
+    });
+
+    for (const filePath of getIntentHandoffArtifactPaths(repoRoot, 'REQ-123')) {
+      if (filePath !== prBriefPath) {
+        writeText(filePath);
+      }
+    }
+
+    const result = await runPreparePr({ repoRoot, changeId: 'REQ-123' });
+
+    const prBrief = fs.readFileSync(prBriefPath, 'utf8');
+
+    expect(result.status).toBe('prepared');
+    expect(result.suggestedTitle).toBe('feat(req-123): Prepare a PR-ready brief');
+    expect(prBrief).toContain('PR Brief: REQ-123');
+    expect(prBrief).toContain('execution/tasks/T001/checkpoint.json');
+    expect(prBrief).not.toContain('result.md');
+    for (const filePath of getIntentHandoffArtifactPaths(repoRoot, 'REQ-123')) {
+      expect(fs.existsSync(filePath)).toBe(filePath === prBriefPath);
+    }
+  });
+});

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

@@ -0,0 +1,284 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { getFullState, getNextTask, getProgress } = require('../query');
+const {
+  getRuntimeStatePath,
+  getTaskManifestPath,
+  getReportCardPath
+} = require('../store');
+const { getIntentPrBriefPath } = require('../artifacts');
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+describe('query helpers', () => {
+  test('reuses shared lifecycle progress semantics', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-progress-'));
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-122'), {
+      changeId: 'REQ-122',
+      goal: 'Expose shared progress summary',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      tasks: [
+        { id: 'T001', status: 'pending' },
+        { id: 'T002', status: 'running' },
+        { id: 'T003', status: 'passed' },
+        { id: 'T004', status: 'failed' },
+        { id: 'T005', status: 'skipped' },
+        { id: 'T006', status: 'legacy' }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    await expect(getProgress(repoRoot, 'REQ-122')).resolves.toEqual({
+      totalTasks: 6,
+      completedTasks: 1,
+      failedTasks: 1,
+      pendingTasks: 1,
+      runningTasks: 1,
+      skippedTasks: 1
+    });
+  });
+
+  test('reports approve stage when a planned manifest exists without approval', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-approve-'));
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Expose approval gate',
+      status: 'planned',
+      initializedAt: '2026-03-25T01:00:00.000Z',
+      plannedAt: '2026-03-25T01:05:00.000Z',
+      approval: {
+        status: 'pending',
+        executionMode: 'delegate'
+      },
+      updatedAt: '2026-03-25T01:05:00.000Z'
+    });
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Expose approval gate',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Pending',
+          type: 'IMPL',
+          dependsOn: [],
+          touches: ['src/a.ts'],
+          run: ['echo ok'],
+          checks: [],
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    const state = await getFullState(repoRoot, 'REQ-123');
+
+    expect(state.lifecycle.stage).toBe('approve');
+    expect(state.lifecycle.approval).toMatchObject({
+      status: 'pending',
+      executionMode: 'delegate',
+      planVersion: 1
+    });
+  });
+
+  test('reports prepare-pr stage and pr brief path when PR-ready artifact exists', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-'));
+
+    writeJson(getRuntimeStatePath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Expose query stage',
+      status: 'verified',
+      initializedAt: '2026-03-25T01:00:00.000Z',
+      plannedAt: '2026-03-25T01:05:00.000Z',
+      verifiedAt: '2026-03-25T01:10:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z'
+    });
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-123'), {
+      changeId: 'REQ-123',
+      goal: 'Expose query stage',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Done',
+          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',
+      overall: 'pass',
+      quickGates: [],
+      strictGates: [],
+      review: { status: 'pass', details: '' },
+      blockingFindings: [],
+      timestamp: '2026-03-25T01:11:00.000Z'
+    });
+
+    fs.mkdirSync(path.dirname(getIntentPrBriefPath(repoRoot, 'REQ-123')), { recursive: true });
+    fs.writeFileSync(getIntentPrBriefPath(repoRoot, 'REQ-123'), '# PR Brief: REQ-123\n');
+
+    const state = await getFullState(repoRoot, 'REQ-123');
+
+    expect(state.lifecycle.stage).toBe('prepare-pr');
+    expect(state.delivery.prBriefPath).toBe(getIntentPrBriefPath(repoRoot, 'REQ-123'));
+  });
+
+  test('returns the ready task instead of the first pending task', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-next-'));
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-124'), {
+      changeId: 'REQ-124',
+      goal: 'Expose dependency-aware next task',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      currentTaskId: 'T002',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Blocked task',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: ['T999'],
+          touches: ['src/a.ts'],
+          files: [],
+          run: ['echo blocked'],
+          checks: [],
+          acceptance: [],
+          verification: [],
+          evidence: [],
+          context: { readFiles: [], commands: [], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        },
+        {
+          id: 'T002',
+          title: 'Ready task',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: [],
+          touches: ['src/b.ts'],
+          files: [],
+          run: ['echo ready'],
+          checks: [],
+          acceptance: [],
+          verification: [],
+          evidence: [],
+          context: { readFiles: [], commands: [], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    const next = await getNextTask(repoRoot, 'REQ-124');
+
+    expect(next.id).toBe('T002');
+  });
+
+  test('treats legacy passed aliases as completed dependencies via shared lifecycle semantics', async () => {
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-devflow-query-legacy-next-'));
+
+    writeJson(getTaskManifestPath(repoRoot, 'REQ-125'), {
+      changeId: 'REQ-125',
+      goal: 'Reuse shared task completion aliases',
+      createdAt: '2026-03-25T01:05:00.000Z',
+      updatedAt: '2026-03-25T01:10:00.000Z',
+      activePhase: 1,
+      tasks: [
+        {
+          id: 'T001',
+          title: 'Legacy completed prerequisite',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: [],
+          touches: ['src/a.ts'],
+          files: [],
+          run: ['echo done'],
+          checks: [],
+          acceptance: [],
+          verification: [],
+          evidence: [],
+          context: { readFiles: [], commands: [], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'verified',
+          attempts: 1,
+          maxRetries: 1
+        },
+        {
+          id: 'T002',
+          title: 'Ready after legacy prerequisite',
+          type: 'OTHER',
+          phase: 1,
+          dependsOn: ['T001'],
+          touches: ['src/b.ts'],
+          files: [],
+          run: ['echo ready'],
+          checks: [],
+          acceptance: [],
+          verification: [],
+          evidence: [],
+          context: { readFiles: [], commands: [], notes: [] },
+          reviews: { spec: 'pending', code: 'pending' },
+          status: 'pending',
+          attempts: 0,
+          maxRetries: 1
+        }
+      ],
+      metadata: {
+        source: 'default',
+        generatedBy: 'test',
+        planVersion: 1
+      }
+    });
+
+    const next = await getNextTask(repoRoot, 'REQ-125');
+
+    expect(next.id).toBe('T002');
+  });
+});