agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/test/helpers.ts

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { stableHash } from '../src/core/fs.js';
 import { runCommand } from '../src/core/git.js';
+import type { AopKernel } from '../src/index.js';
 
 async function copyTemplateSubtree(templateRoot, tempRoot, dirName) {
   const sourceDir = path.join(templateRoot, dirName);
@@ -90,3 +91,67 @@ export async function writeFeatureSpec(
   await fs.mkdir(featureDir, { recursive: true });
   await fs.writeFile(path.join(featureDir, 'spec.md'), content, 'utf8');
 }
+
+export async function verifyFeatureIntake(kernel: AopKernel, featureId: string): Promise<void> {
+  const intake = (await kernel.featureIntakeContext(featureId)) as {
+    bootstrap_manifest?: {
+      feature_id?: string;
+      manifest_version?: number;
+      obligations?: unknown[];
+      ambiguities?: Array<{ id: string; summary: string; status: string }>;
+    };
+  };
+  const bootstrapManifest = intake.bootstrap_manifest;
+  if (!bootstrapManifest || typeof bootstrapManifest.manifest_version !== 'number') {
+    throw new Error(`missing_bootstrap_manifest:${featureId}`);
+  }
+
+  const ambiguities = Array.isArray(bootstrapManifest.ambiguities)
+    ? bootstrapManifest.ambiguities
+    : [];
+  if (ambiguities.length > 0) {
+    const created = (await kernel.featureQuestionCreate({
+      feature_id: featureId,
+      role: 'planner',
+      session_id: 'test-planner-session',
+      question_type: 'clarification',
+      prompt: 'Resolve intake ambiguities for test promotion',
+      details: {
+        ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+      },
+      expected_answer: { kind: 'free_text' },
+      blocking: true,
+      phase: 'intake',
+      request_action: 'ask_user_input',
+    })) as { data?: { question_id?: string } };
+    const questionId = created.data?.question_id;
+    if (!questionId) {
+      throw new Error(`missing_intake_question_id:${featureId}`);
+    }
+    await kernel.featureQuestionAnswer({
+      feature_id: featureId,
+      question_id: questionId,
+      answer: 'Resolved for test harness.',
+      answered_by: 'operator:test',
+    });
+  }
+  await kernel.featureIntakeSubmit(featureId, {
+    verified_manifest: {
+      feature_id: bootstrapManifest.feature_id ?? featureId,
+      manifest_version: bootstrapManifest.manifest_version,
+      artifact_type: 'verified',
+      verification_basis: ambiguities.length > 0 ? 'questions_resolved' : 'structured_spec',
+      verified_at: '2026-01-01T00:00:00.000Z',
+      source_bootstrap_version: bootstrapManifest.manifest_version,
+      obligations: Array.isArray(bootstrapManifest.obligations)
+        ? bootstrapManifest.obligations
+        : [],
+    },
+    open_ambiguities: [],
+    resolved_ambiguities: ambiguities.map((ambiguity) => ({
+      ...ambiguity,
+      status: 'resolved',
+    })),
+    requires_user_input: false,
+  });
+}

package/apps/control-plane/test/incremental-gates.spec.ts

@@ -149,6 +149,277 @@ describe('incremental gate execution', () => {
     expect(updatedEvidence['skipped_reason']).toBe('incremental_mode');
     expect(updatedEvidence['base_branch']).toBe('main');
   });
+
+  it('GIVEN_latest_checkpoint_metadata_WHEN_gatesRun_executes_THEN_runGateMode_receives_checkpoint_inputs', async () => {
+    runGateModeMock.mockResolvedValue({
+      overall: 'pass',
+      coverage_status: 'na',
+      evidence_path: path.join(tempDir, 'gate-full.json'),
+      latest_path: path.join(tempDir, 'latest-full.json'),
+      coverage: null,
+      thresholds: {},
+    });
+
+    const profile = {
+      modes: {
+        full: [
+          {
+            name: 'test_full',
+            cmd: ['npm', 'test'],
+            timeout_seconds: 60,
+          },
+        ],
+      },
+      thresholds: {},
+    };
+
+    const port: GateServicePort = {
+      ...buildPort(tempDir, { profiles: { default: profile } }),
+      readState: async () => ({
+        frontMatter: {
+          status: 'qa',
+          version: 2,
+          gate_profile: 'default',
+          checkpoints: [
+            {
+              checkpoint_id: 'cp-123',
+              validation_status: 'skipped',
+              diff_hash: 'diff-abc',
+            },
+          ],
+        },
+      }),
+    };
+    const service = new GateService(port);
+
+    await service.gatesRun('feature-with-checkpoint', 'default', 'full');
+
+    const callArgs = runGateModeMock.mock.calls[0][0] as { inputMetadata: Record<string, unknown> };
+    expect(callArgs.inputMetadata).toEqual({
+      input_diff_hash: 'diff-abc',
+      input_checkpoint_id: 'cp-123',
+      input_head_sha: null,
+      input_workspace_fingerprint: null,
+      input_worktree_validity: 'unknown',
+    });
+  });
+
+  it('GIVEN_blocked_feature_in_merge_mode_WHEN_gate_passes_THEN_status_advances_to_ready_to_merge', async () => {
+    runGateModeMock.mockResolvedValue({
+      overall: 'pass',
+      coverage_status: 'na',
+      evidence_path: path.join(tempDir, 'gate-merge.json'),
+      latest_path: path.join(tempDir, 'latest-merge.json'),
+      coverage: null,
+      thresholds: {},
+    });
+
+    const updateState = vi.fn().mockResolvedValue({});
+    const port: GateServicePort = {
+      ...buildPort(tempDir, {
+        profiles: {
+          default: {
+            modes: {
+              merge: [{ name: 'merge-check', cmd: ['npm', 'test'], timeout_seconds: 60 }],
+            },
+            thresholds: {},
+          },
+        },
+      }),
+      readState: async () => ({
+        frontMatter: { status: 'blocked', version: 7, gate_profile: 'default', gates: {} },
+      }),
+      updateState,
+    };
+    const service = new GateService(port);
+
+    await service.gatesRun('feature-merge-recovery', 'default', 'merge');
+
+    const updater = updateState.mock.calls[0]?.[2] as
+      | ((
+          frontMatter: Record<string, unknown>,
+          body: string,
+        ) => Promise<{ frontMatter?: Record<string, unknown> }>)
+      | undefined;
+    expect(updater).toBeTypeOf('function');
+    const nextState = await updater?.({ status: 'blocked', gates: {} }, 'body');
+    expect(nextState?.frontMatter?.status).toBe('ready_to_merge');
+  });
+
+  it('GIVEN_ready_to_merge_feature_with_exhausted_merge_repair_WHEN_merge_gate_fails_THEN_status_advances_to_failed', async () => {
+    runGateModeMock.mockResolvedValue({
+      overall: 'fail',
+      coverage_status: 'na',
+      evidence_path: path.join(tempDir, 'gate-merge-fail.json'),
+      latest_path: path.join(tempDir, 'latest-merge-fail.json'),
+      coverage: null,
+      thresholds: {},
+    });
+
+    const updateState = vi.fn().mockResolvedValue({});
+    const port: GateServicePort = {
+      ...buildPort(tempDir, {
+        profiles: {
+          default: {
+            modes: {
+              merge: [{ name: 'merge-check', cmd: ['npm', 'test'], timeout_seconds: 60 }],
+            },
+            thresholds: {},
+          },
+        },
+      }),
+      readState: async () => ({
+        frontMatter: {
+          status: 'ready_to_merge',
+          version: 8,
+          gate_profile: 'default',
+          gates: { merge: 'fail' },
+          merge_repair: {
+            attempts: 5,
+            max_attempts: 5,
+            active: true,
+          },
+        },
+      }),
+      updateState,
+    };
+    const service = new GateService(port);
+
+    await service.gatesRun('feature-merge-exhausted', 'default', 'merge');
+
+    const updater = updateState.mock.calls[0]?.[2] as
+      | ((
+          frontMatter: Record<string, unknown>,
+          body: string,
+        ) => Promise<{ frontMatter?: Record<string, unknown> }>)
+      | undefined;
+    const nextState = await updater?.(
+      {
+        status: 'ready_to_merge',
+        gates: { merge: 'fail' },
+        merge_repair: { attempts: 5, max_attempts: 5, active: true },
+      },
+      'body',
+    );
+    expect(nextState?.frontMatter?.status).toBe('failed');
+    expect(nextState?.frontMatter?.merge_repair).toMatchObject({
+      active: false,
+      exhausted_at: expect.any(String),
+    });
+  });
+
+  it('GIVEN_empty_checkpoint_diff_WHEN_gate_passes_THEN_status_does_not_advance', async () => {
+    runGateModeMock.mockResolvedValue({
+      overall: 'pass',
+      coverage_status: 'na',
+      evidence_path: path.join(tempDir, 'gate-fast-empty.json'),
+      latest_path: path.join(tempDir, 'latest-fast-empty.json'),
+      coverage: null,
+      thresholds: {},
+    });
+
+    const updateState = vi.fn().mockResolvedValue({});
+    const port: GateServicePort = {
+      ...buildPort(tempDir, {
+        profiles: {
+          default: {
+            modes: {
+              fast: [{ name: 'fast-check', cmd: ['npm', 'test'], timeout_seconds: 60 }],
+            },
+            thresholds: {},
+          },
+        },
+      }),
+      readState: async () => ({
+        frontMatter: {
+          status: 'building',
+          version: 4,
+          gate_profile: 'default',
+          gates: {},
+          checkpoints: [
+            {
+              checkpoint_id: 'cp-empty',
+              validation_status: 'valid',
+              diff_hash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+              net_new_worktree_change: false,
+            },
+          ],
+        },
+      }),
+      updateState,
+    };
+    const service = new GateService(port);
+
+    await service.gatesRun('feature-empty', 'default', 'fast');
+
+    const updater = updateState.mock.calls[0]?.[2] as
+      | ((
+          frontMatter: Record<string, unknown>,
+          body: string,
+        ) => Promise<{ frontMatter?: Record<string, unknown> }>)
+      | undefined;
+    expect(updater).toBeTypeOf('function');
+    const nextState = await updater?.({ status: 'building', gates: {} }, 'body');
+    expect(nextState?.frontMatter?.status).toBe('building');
+    expect(nextState?.frontMatter?.status_reason).toBe(
+      'Gate mode fast passed but no material worktree diff was present; status unchanged',
+    );
+  });
+
+  it('GIVEN_named_profile_lookup_WHEN_profile_missing_THEN_gatesList_returns_null_config', () => {
+    const service = new GateService(buildPort(tempDir, { profiles: { default: { modes: {} } } }));
+
+    expect(service.gatesList('missing-profile')).toEqual({
+      data: {
+        profile: 'missing-profile',
+        config: null,
+      },
+    });
+  });
+
+  it('GIVEN_mode_specific_evidence_WHEN_latest_file_missing_THEN_evidenceLatest_returns_null', async () => {
+    const evidenceDir = path.join(tempDir, 'evidence-missing');
+    await fs.mkdir(evidenceDir, { recursive: true });
+
+    const port: GateServicePort = {
+      ...buildPort(tempDir, { profiles: { default: { modes: {} } } }),
+      evidencePath: () => evidenceDir,
+    };
+    const service = new GateService(port);
+
+    expect(await service.evidenceLatest('feature-evidence', 'fast')).toEqual({
+      data: {
+        feature_id: 'feature-evidence',
+        latest: null,
+      },
+    });
+  });
+
+  it('GIVEN_mode_specific_evidence_WHEN_latest_file_exists_THEN_evidenceLatest_returns_payload_and_repo_relative_path', async () => {
+    const evidenceDir = path.join(tempDir, 'feature-evidence');
+    await fs.mkdir(evidenceDir, { recursive: true });
+    const latestPath = path.join(evidenceDir, 'latest-fast.json');
+    await fs.writeFile(
+      latestPath,
+      `${JSON.stringify({ overall: 'pass', mode: 'fast' }, null, 2)}\n`,
+      'utf8',
+    );
+
+    const port: GateServicePort = {
+      ...buildPort(tempDir, { profiles: { default: { modes: {} } } }),
+      getRepoRoot: () => tempDir,
+      evidencePath: () => evidenceDir,
+    };
+    const service = new GateService(port);
+
+    expect(await service.evidenceLatest('feature-evidence', 'fast')).toEqual({
+      data: {
+        feature_id: 'feature-evidence',
+        latest: { overall: 'pass', mode: 'fast' },
+        path: 'feature-evidence/latest-fast.json',
+      },
+    });
+  });
 });
 
 function buildPort(tempDir: string, gatesConfig: Record<string, unknown>): GateServicePort {

package/apps/control-plane/test/index-normalizer.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import {
+  emptyRuntimeSessions,
+  isRunLeaseFresh,
+  normalizeIndexShape,
+  normalizeRuntimeSessions,
+} from '../src/core/utils/index-normalizer.js';
+
+describe('index-normalizer', () => {
+  it('normalizes runtime session queues, optional reconciler ids, and epoch values', () => {
+    const result = normalizeRuntimeSessions(
+      {
+        reconciler_active_feature_id: 'feature_active',
+        reconciler_queue: ['feature_b', '', 42, 'feature_a'],
+        orchestrator_epoch: -2.4,
+        feature_sessions: {
+          feature_a: {
+            planner_session_id: 'planner:a',
+            builder_session_id: 'builder:a',
+            qa_session_id: 'qa:a',
+            reconciler_session_id: 'reconciler:a',
+          },
+          feature_b: {
+            planner_session_id: 'planner:b',
+            builder_session_id: 'builder:b',
+            qa_session_id: 'qa:b',
+          },
+        },
+      },
+      '2026-03-16T00:00:00.000Z',
+    );
+
+    expect(result.reconciler_active_feature_id).toBe('feature_active');
+    expect(result.reconciler_queue).toEqual(['feature_b', 'feature_a']);
+    expect(result.orchestrator_epoch).toBe(0);
+    expect(
+      (result.feature_sessions.feature_a as unknown as Record<string, unknown>)
+        .reconciler_session_id,
+    ).toBe('reconciler:a');
+    expect(result.feature_sessions.feature_b).not.toHaveProperty('reconciler_session_id');
+  });
+
+  it('filters index collections to string and object entries only', () => {
+    const result = normalizeIndexShape({
+      version: 3.9,
+      active: ['feature_b', 4, 'feature_a', 'feature_b'],
+      blocked: ['feature_c', null, 'feature_b'],
+      merged: ['feature_m', false, 'feature_a'],
+      blocked_queue: [{ feature_id: 'feature_blocked' }, null, 'skip-me'],
+      collision_records: [{ id: 'collision_1' }, 1],
+      collision_overrides: [{ id: 'override_1' }, 'bad'],
+      dep_blocked: [{ feature_id: 'feature_dep' }, undefined],
+      runtime_sessions: {
+        orchestrator_epoch: 4.7,
+      },
+    });
+
+    expect(result.version).toBe(3);
+    expect(result.active).toEqual(['feature_a', 'feature_b']);
+    expect(result.blocked).toEqual(['feature_b', 'feature_c']);
+    expect(result.merged).toEqual(['feature_a', 'feature_m']);
+    expect(result.blocked_queue).toEqual([{ feature_id: 'feature_blocked' }]);
+    expect(result.collision_records).toEqual([{ id: 'collision_1' }]);
+    expect(result.collision_overrides).toEqual([{ id: 'override_1' }]);
+    expect(result.dep_blocked).toEqual([{ feature_id: 'feature_dep' }]);
+    expect(result.runtime_sessions.orchestrator_epoch).toBe(4);
+  });
+
+  it('provides empty session defaults and lease freshness checks', () => {
+    const empty = emptyRuntimeSessions('2026-03-16T00:00:00.000Z');
+    expect(empty.run_id).toBe('none');
+    expect(empty.owner_instance_id).toBe('none');
+    expect(empty.provider_config_ref_hash).toBeTruthy();
+
+    expect(
+      isRunLeaseFresh({
+        ...empty,
+        lease_expires_at: new Date(Date.now() - 1_000).toISOString(),
+      }),
+    ).toBe(false);
+    expect(
+      isRunLeaseFresh({
+        ...empty,
+        lease_expires_at: new Date(Date.now() + 60_000).toISOString(),
+      }),
+    ).toBe(true);
+    expect(
+      isRunLeaseFresh({
+        ...empty,
+        run_id: 'run:stale',
+        owner_instance_id: 'owner:stale',
+        lease_id: 'lease:stale',
+        last_heartbeat_at: new Date(Date.now() - 180_000).toISOString(),
+        lease_expires_at: new Date(0).toISOString(),
+      }),
+    ).toBe(false);
+  });
+});

package/apps/control-plane/test/init-wizard.spec.ts

@@ -68,6 +68,9 @@ describe('InitCommandHandler', () => {
     expect(result.data.created).toContain('config/agentic/orchestrator/agents.yaml');
     expect(result.data.created).toContain('config/agentic/orchestrator/adapters.yaml');
     expect(result.data.created).toContain('config/agentic/orchestrator/prompts/planner.system.md');
+    expect(result.data.created).toContain(
+      'config/agentic/orchestrator/prompts/planner-intake.system.md',
+    );
     expect(result.data.skipped).toHaveLength(0);
     expect(result.data.updated).toHaveLength(0);
     expect(result.data.validation_warnings).toHaveLength(0);
@@ -98,6 +101,9 @@ describe('InitCommandHandler', () => {
     expect(agentsContent).toContain('default_provider: custom');
     expect(agentsContent).toContain('default_model: local-default');
     expect(agentsContent).toContain('execution_mode: deterministic');
+    expect(agentsContent).toContain(
+      'intake_system_prompt_path: config/agentic/orchestrator/prompts/planner-intake.system.md',
+    );
     expect(agentsContent).toContain('interactive:');
     expect(agentsContent).toContain('checkpoint_interval_ms: 30000');
     expect(agentsContent).not.toContain('provider_config_env:');
@@ -115,6 +121,12 @@ describe('InitCommandHandler', () => {
         'utf8',
       ),
     ).resolves.toContain('planner');
+    await expect(
+      fs.readFile(
+        path.join(cwd, 'config', 'agentic', 'orchestrator', 'prompts', 'planner-intake.system.md'),
+        'utf8',
+      ),
+    ).resolves.toContain('intake');
     await expect(
       fs.stat(path.join(cwd, 'config', 'agentic', 'orchestrator', 'schemas')),
     ).rejects.toThrow();
@@ -942,6 +954,11 @@ describe('InitCommandHandler lean vs advanced policy', () => {
     expect(policyContent).toContain('implementation:');
     expect(policyContent).toContain('testing:');
     expect(policyContent).toContain('framework: vitest');
+    expect(policyContent).toContain('repo.reconcile_mainline');
+    expect(policyContent).toContain('feature.intake_submit');
+    expect(policyContent).toContain('feature.question_create');
+    expect(policyContent).toContain('feature.question_list');
+    expect(policyContent).toContain('feature.question_answer');
   });
 
   it('GIVEN_advanced_policy_flag_WHEN_help_rendered_THEN_flag_is_documented', () => {

package/apps/control-plane/test/intake-artifacts.spec.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'vitest';
+import {
+  normalizeManifestConfidence,
+  obligationsMeetConfidenceThreshold,
+  readPlanTraceEntries,
+  validatePlanTraceAgainstObligationIds,
+} from '../src/core/intake-artifacts.js';
+
+describe('intake artifact helpers', () => {
+  it('normalizes supported confidence values and rejects unsupported ones', () => {
+    expect(normalizeManifestConfidence('high')).toBe('high');
+    expect(normalizeManifestConfidence('medium')).toBe('medium');
+    expect(normalizeManifestConfidence('low')).toBe('low');
+    expect(normalizeManifestConfidence('unknown')).toBeNull();
+  });
+
+  it('checks whether every obligation satisfies the requested confidence threshold', () => {
+    expect(
+      obligationsMeetConfidenceThreshold(
+        [{ confidence: 'high' }, { confidence: 'medium' }],
+        'medium',
+      ),
+    ).toBe(true);
+
+    expect(
+      obligationsMeetConfidenceThreshold([{ confidence: 'high' }, { confidence: 'low' }], 'medium'),
+    ).toBe(false);
+  });
+
+  it('normalizes plan trace entries and drops malformed items', () => {
+    expect(
+      readPlanTraceEntries([
+        null,
+        {
+          obligation_id: 'OBL-001',
+          disposition: 'in_scope',
+          planned_paths: [' src/file.ts ', 42, ''],
+          planned_test_paths: [' test/file.spec.ts ', null],
+          planned_verification: [' qa:full ', false],
+          notes: 'kept',
+        },
+        {
+          obligation_id: 'OBL-002',
+          disposition: 'in_scope',
+          planned_paths: [],
+        },
+      ]),
+    ).toEqual([
+      {
+        obligation_id: 'OBL-001',
+        disposition: 'in_scope',
+        planned_paths: ['src/file.ts'],
+        planned_test_paths: ['test/file.spec.ts'],
+        planned_verification: ['qa:full'],
+        notes: 'kept',
+      },
+    ]);
+  });
+
+  it('returns an empty plan trace list for non-array inputs', () => {
+    expect(readPlanTraceEntries(null)).toEqual([]);
+    expect(readPlanTraceEntries({ plan_trace: [] })).toEqual([]);
+  });
+
+  it('validates plan trace coverage against the verified obligation set', () => {
+    expect(
+      validatePlanTraceAgainstObligationIds(
+        {
+          files: {
+            create: ['src/one.ts'],
+            modify: ['src/two.ts'],
+            delete: [],
+          },
+          plan_trace: [
+            {
+              obligation_id: 'OBL-001',
+              disposition: 'in_scope',
+              planned_paths: ['src/one.ts'],
+              notes: 'valid',
+            },
+            {
+              obligation_id: 'OBL-001',
+              disposition: 'in_scope',
+              planned_paths: ['missing.ts'],
+              notes: 'duplicate invalid mapping',
+            },
+            {
+              obligation_id: 'OBL-999',
+              disposition: 'out_of_scope',
+              planned_paths: ['ignored.ts'],
+              notes: 'unknown but no mapping check',
+            },
+          ],
+        },
+        ['OBL-001', 'OBL-002'],
+      ),
+    ).toEqual({
+      valid: false,
+      missing_obligation_ids: ['OBL-002'],
+      unknown_obligation_ids: ['OBL-999'],
+      duplicate_obligation_ids: ['OBL-001'],
+      invalid_mappings: ['OBL-001'],
+      invalid_mapping_details: [
+        {
+          obligation_id: 'OBL-001',
+          reason: 'planned_paths_outside_plan_files',
+          planned_paths: ['missing.ts'],
+        },
+      ],
+    });
+
+    expect(
+      validatePlanTraceAgainstObligationIds(
+        {
+          files: {
+            create: ['src/one.ts'],
+            modify: [],
+            delete: [],
+          },
+          plan_trace: [
+            {
+              obligation_id: 'OBL-001',
+              disposition: 'in_scope',
+              planned_paths: ['src/one.ts'],
+              notes: 'valid',
+            },
+          ],
+        },
+        ['OBL-001'],
+      ),
+    ).toEqual({
+      valid: true,
+      missing_obligation_ids: [],
+      unknown_obligation_ids: [],
+      duplicate_obligation_ids: [],
+      invalid_mappings: [],
+      invalid_mapping_details: [],
+    });
+  });
+
+  it('treats non-object file manifests and out-of-scope trace entries as non-mapping failures', () => {
+    expect(
+      validatePlanTraceAgainstObligationIds(
+        {
+          files: null,
+          plan_trace: [
+            {
+              obligation_id: 'OBL-001',
+              disposition: 'out_of_scope',
+              planned_paths: ['missing.ts'],
+              notes: 'out of scope',
+            },
+          ],
+        },
+        ['OBL-001'],
+      ),
+    ).toEqual({
+      valid: true,
+      missing_obligation_ids: [],
+      unknown_obligation_ids: [],
+      duplicate_obligation_ids: [],
+      invalid_mappings: [],
+      invalid_mapping_details: [],
+    });
+  });
+
+  it('reports empty in-scope planned path lists as invalid mapping details', () => {
+    expect(
+      validatePlanTraceAgainstObligationIds(
+        {
+          files: {
+            create: ['src/one.ts'],
+            modify: [],
+            delete: [],
+          },
+          plan_trace: [
+            {
+              obligation_id: 'OBL-017',
+              disposition: 'in_scope',
+              planned_paths: [],
+              planned_verification: ['code review only'],
+              notes: 'verification-only trace',
+            },
+          ],
+        },
+        ['OBL-017'],
+      ),
+    ).toEqual({
+      valid: false,
+      missing_obligation_ids: [],
+      unknown_obligation_ids: [],
+      duplicate_obligation_ids: [],
+      invalid_mappings: ['OBL-017'],
+      invalid_mapping_details: [
+        {
+          obligation_id: 'OBL-017',
+          reason: 'missing_planned_paths',
+          planned_paths: [],
+        },
+      ],
+    });
+  });
+});