sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/phase8-projection-compat.test.ts

@@ -0,0 +1,153 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { initProject } from './config/init-project.js';
+import { evaluateLifecycleDecisionGate } from './lifecycle/decision-gate.js';
+import { buildTaskRiskProfile } from './task-risk-profile.js';
+import { evaluateLifecycleRiskDecisionFromProfile, legacyLifecycleDecisionToRiskDecision, taskRiskProfileToCodingRiskProfile, taskRiskProfileToCodingRiskSignals } from './risk.js';
+import { readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness } from './storage/runtime-store.js';
+
+test('Phase 8 projection envelope writes are deterministic and stale-aware', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-projection-'));
+  try {
+    await initProject(root);
+    const first = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-a',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-01T00:00:00.000Z',
+      payload: { status: 'one' }
+    });
+    const second = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-a',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-02T00:00:00.000Z',
+      payload: { status: 'one' }
+    });
+
+    assert.equal(first.status, 'created');
+    assert.equal(first.staleness, 'unknown');
+    assert.equal(second.status, 'unchanged');
+    assert.equal(second.envelope.id, first.envelope.id);
+    assert.equal(second.envelope.generatedAt, '2026-05-01T00:00:00.000Z');
+    assert.equal(runtimeProjectionStaleness(second.envelope, { inputHash: 'input-b', producerVersion: 'v1' }), 'stale');
+    assert.equal(runtimeProjectionStaleness(second.envelope, { inputHash: 'input-a', producerVersion: 'v2' }), 'incompatible');
+
+    const third = await recordRuntimeProjectionEnvelope(root, {
+      projectionType: 'phase8-test-risk',
+      scopeKey: 'branch:master',
+      inputHash: 'input-b',
+      producer: 'phase8-test',
+      producerVersion: 'v1',
+      generatedAt: '2026-05-03T00:00:00.000Z',
+      payload: { status: 'two' }
+    });
+    const restored = await readRuntimeProjectionEnvelope<{ status: string }>(root, 'phase8-test-risk', 'branch:master');
+
+    assert.equal(third.status, 'updated');
+    assert.equal(third.staleness, 'stale');
+    assert.equal(restored?.inputHash, 'input-b');
+    assert.deepEqual(restored?.payload, { status: 'two' });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('legacy task risk profiles map to Phase 8 coding risk signals', () => {
+  const scope = { branch: 'master', taskId: 'PHASE8-2' };
+  const sourceProfile = buildTaskRiskProfile({
+    id: 'PHASE8-2',
+    risk: ['security', 'external', 'context', 'token', 'performance'],
+    affectedFiles: ['packages/core/src/storage/runtime-store.ts', '.sdd/run-index.json'],
+    validation: ['npm test']
+  });
+  const docsProfile = buildTaskRiskProfile({
+    id: 'DOCS-1',
+    risk: [],
+    affectedFiles: ['specs/master/phase8-spec.md'],
+    validation: ['npm run typecheck']
+  });
+
+  const sourceSignals = taskRiskProfileToCodingRiskSignals(sourceProfile, scope);
+  const docsSignals = taskRiskProfileToCodingRiskSignals(docsProfile, { branch: 'master', taskId: 'DOCS-1' });
+  const dimensions = sourceSignals.map((signal) => signal.dimension);
+  const docsDimensions = docsSignals.map((signal) => signal.dimension);
+  const profile = taskRiskProfileToCodingRiskProfile(sourceProfile, scope, '2026-05-01T00:00:00.000Z');
+
+  assert.equal(dimensions.includes('source'), true);
+  assert.equal(dimensions.includes('runtime-state'), true);
+  assert.equal(dimensions.includes('security'), true);
+  assert.equal(dimensions.includes('external'), true);
+  assert.equal(dimensions.includes('context'), true);
+  assert.equal(dimensions.includes('performance'), true);
+  assert.equal(docsDimensions.includes('workflow'), true);
+  assert.equal(docsDimensions.includes('evidence'), true);
+  assert.equal(profile.contract, 'sdd-coding-risk-profile-v1');
+  assert.equal(profile.level, 'high');
+  assert.equal(profile.dimensions.includes('source'), true);
+});
+
+test('known external risk stays distinct from unknown external risk', () => {
+  const known = buildTaskRiskProfile({
+    id: 'KNOWN-EXTERNAL',
+    risk: ['external', 'third-party'],
+    affectedFiles: ['docs/integration.md'],
+    validation: ['npm test']
+  });
+  const unknown = buildTaskRiskProfile({
+    id: 'UNKNOWN-EXTERNAL',
+    risk: ['external-unknown'],
+    affectedFiles: ['docs/integration.md'],
+    validation: ['npm test']
+  });
+  const knownRisk = taskRiskProfileToCodingRiskProfile(known, { branch: 'master', taskId: 'KNOWN-EXTERNAL' }, '2026-05-01T00:00:00.000Z');
+  const unknownRisk = taskRiskProfileToCodingRiskProfile(unknown, { branch: 'master', taskId: 'UNKNOWN-EXTERNAL' }, '2026-05-01T00:00:00.000Z');
+  const knownDecision = evaluateLifecycleRiskDecisionFromProfile(knownRisk);
+  const unknownDecision = evaluateLifecycleRiskDecisionFromProfile(unknownRisk);
+
+  assert.deepEqual(known.normalizedTags, ['external']);
+  assert.equal(known.externalKnown, true);
+  assert.equal(known.externalUnknown, false);
+  assert.equal(unknown.externalUnknown, true);
+  assert.equal(knownRisk.signals.some((signal) => signal.id.endsWith(':external-known') && signal.level === 'medium' && signal.confidence === 'high'), true);
+  assert.equal(unknownRisk.signals.some((signal) => signal.id.endsWith(':external-unknown') && signal.level === 'high' && signal.confidence === 'low'), true);
+  assert.notEqual(knownDecision.profile, 'research');
+  assert.equal(unknownDecision.profile, 'research');
+  assert.equal(unknownDecision.approvalPolicy, 'human-required');
+});
+
+test('legacy lifecycle decisions map to Phase 8 comparison decisions', () => {
+  const legacy = evaluateLifecycleDecisionGate({
+    intent_clarity: 'high',
+    acceptance_clarity: 'high',
+    impact_confidence: 'high',
+    validation_clarity: 'clear',
+    validation_available: true,
+    validation_cost: 'cheap',
+    reversibility: 'reversible',
+    affected_contracts: ['public-api'],
+    risk_tags: ['security']
+  }, new Date('2026-05-01T00:00:00.000Z')).record;
+  const decision = legacyLifecycleDecisionToRiskDecision(legacy, { branch: 'master', taskId: 'PHASE8-2' }, { inputHash: 'legacy-input' });
+
+  assert.equal(decision.contract, 'sdd-lifecycle-risk-decision-v1');
+  assert.equal(decision.profile, 'full');
+  assert.equal(decision.requiredStages.includes('test'), true);
+  assert.equal(decision.requiredStages.includes('verifies'), true);
+  assert.equal(decision.requiredStages.includes('goal-verify'), true);
+  assert.equal(decision.requiredEvidence.length, 1);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'security'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'source-boundary'), true);
+  assert.equal(decision.approvalPolicy, 'review-required');
+  assert.equal(decision.reasons[0], 'Mapped from legacy lifecycle decision for comparison only.');
+  assert.equal(Object.hasOwn(decision, 'ownerAgent'), false);
+  assert.equal(Object.hasOwn(decision, 'subagent'), false);
+});

package/node_modules/@sdd-agent-platform/core/src/phase8-risk-kernel.test.ts

@@ -0,0 +1,277 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { initProject } from './config/init-project.js';
+import type { CodingRiskSignal } from './risk.js';
+import { evaluateLifecycleRiskDecision, evaluateLifecycleRiskDecisionForModel, evaluateLifecycleRiskDecisionFromProfile, inspectLifecycleRiskDecisionForModel, LIFECYCLE_RISK_DECISION_PROJECTION_TYPE, LIFECYCLE_RISK_POLICY_VERSION, lifecycleRiskDecisionScopeKey, recordLifecycleRiskDecisionProjection, readLifecycleRiskDecisionProjection, taskRiskProfileToCodingRiskProfile } from './risk.js';
+import { buildTaskRiskProfile } from './task-risk-profile.js';
+import type { SddTask, SddTaskModel } from './sdd-docs/task-parser.js';
+import { recordRuntimeProjectionEnvelope } from './storage/runtime-store.js';
+
+const scope = { branch: 'master', taskId: 'PHASE8-3' };
+
+test('lifecycle risk kernel allows direct for low-risk known work', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('workflow', 'low', 'high')],
+    factSet: knownFacts(),
+    generatedAt: '2026-05-01T00:00:00.000Z'
+  });
+
+  assert.equal(decision.profile, 'direct');
+  assert.deepEqual(decision.requiredStages, ['do', 'test']);
+  assert.equal(decision.approvalPolicy, 'auto-allow');
+  assert.equal(decision.humanCheckpointRequired, false);
+  assert.equal(decision.requiredEvidence.length, 1);
+  assert.equal(Object.hasOwn(decision, 'agent'), false);
+  assert.equal(Object.hasOwn(decision, 'subagent'), false);
+});
+
+test('lifecycle risk kernel selects compact for bounded context and evidence signals', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('context', 'medium', 'medium'), signal('evidence', 'low', 'high')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(decision.profile, 'compact');
+  assert.deepEqual(decision.requiredStages, ['tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back']);
+  assert.equal(decision.approvalPolicy, 'review-required');
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'evidence'), true);
+});
+
+test('lifecycle risk kernel selects full for source runtime and security risks', () => {
+  const profile = taskRiskProfileToCodingRiskProfile(buildTaskRiskProfile({
+    id: 'PHASE8-3',
+    risk: ['security'],
+    affectedFiles: ['packages/core/src/risk/kernel.ts', '.sdd/runtime.sqlite']
+  }), scope, '2026-05-01T00:00:00.000Z');
+  const decision = evaluateLifecycleRiskDecisionFromProfile(profile, knownFacts(), '2026-05-01T00:00:00.000Z');
+
+  assert.equal(decision.profile, 'full');
+  assert.deepEqual(decision.requiredStages, ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back']);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'source-boundary'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'runtime-state'), true);
+  assert.equal(decision.requiredReviews.some((review) => review.kind === 'security'), true);
+  assert.equal(decision.approvalPolicy, 'human-required');
+});
+
+test('lifecycle risk kernel selects research for low-confidence external impact', () => {
+  const decision = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('external', 'high', 'low')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(decision.profile, 'research');
+  assert.deepEqual(decision.requiredStages, ['spec', 'plan', 'verifies']);
+  assert.equal(decision.requiredEvidence.length, 0);
+  assert.equal(decision.humanCheckpointRequired, true);
+  assert.equal(decision.approvalPolicy, 'human-required');
+});
+
+test('lifecycle risk kernel blocks unknown intent or blocked signals first', () => {
+  const unknownIntent = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('workflow', 'low', 'high')],
+    factSet: {
+      request: { intentKnown: false, acceptanceKnown: true, validationKnown: true },
+      documents: { specExists: false, planExists: false, tasksExists: false, verifiesExists: false }
+    }
+  });
+  const blockedSignal = evaluateLifecycleRiskDecision({
+    scope,
+    signals: [signal('security', 'blocked', 'high'), signal('source', 'high', 'high')],
+    factSet: knownFacts()
+  });
+
+  assert.equal(unknownIntent.profile, 'blocked');
+  assert.deepEqual(unknownIntent.requiredStages, []);
+  assert.deepEqual(unknownIntent.blockedStages, ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'sync-back', 'ship']);
+  assert.equal(unknownIntent.approvalPolicy, 'blocked');
+  assert.equal(blockedSignal.profile, 'blocked');
+  assert.equal(blockedSignal.approvalPolicy, 'blocked');
+});
+
+test('lifecycle risk decision projection can be written and read', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-kernel-'));
+  try {
+    await initProject(root);
+    const decision = evaluateLifecycleRiskDecision({
+      scope,
+      signals: [signal('source', 'high', 'high')],
+      factSet: knownFacts(),
+      inputHash: 'risk-input-a',
+      generatedAt: '2026-05-01T00:00:00.000Z'
+    });
+    const write = await recordLifecycleRiskDecisionProjection(root, decision);
+    const restored = await readLifecycleRiskDecisionProjection(root, scope);
+
+    assert.equal(write.status, 'created');
+    assert.equal(restored?.projectionType, 'phase8_lifecycle_risk_decision');
+    assert.equal(restored?.payload.profile, 'full');
+    assert.equal(restored?.payload.inputHash, 'risk-input-a');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports missing projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-missing-'));
+  try {
+    await initProject(root);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', taskModel());
+
+    assert.equal(diagnostic.status, 'missing');
+    assert.equal(diagnostic.profile, null);
+    assert.equal(diagnostic.producerVersion, null);
+    assert.equal(diagnostic.expectedProducerVersion, LIFECYCLE_RISK_POLICY_VERSION);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports stale projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-stale-'));
+  try {
+    await initProject(root);
+    const model = taskModel();
+    const decision = {
+      ...evaluateLifecycleRiskDecisionForModel('master', model),
+      inputHash: 'old-risk-input'
+    };
+    await recordLifecycleRiskDecisionProjection(root, decision);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'stale');
+    assert.equal(diagnostic.inputHash, 'old-risk-input');
+    assert.notEqual(diagnostic.inputHash, diagnostic.expectedInputHash);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports blocked fresh projections', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-blocked-'));
+  try {
+    await initProject(root);
+    const model = taskModel({ specExists: false, tasks: [] });
+    const decision = evaluateLifecycleRiskDecisionForModel('master', model);
+    await recordLifecycleRiskDecisionProjection(root, decision);
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'blocked');
+    assert.equal(diagnostic.profile, 'blocked');
+    assert.equal(diagnostic.approvalPolicy, 'blocked');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('lifecycle risk consumer diagnostic reports incompatible producer versions', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase8-risk-diagnostic-incompatible-'));
+  try {
+    await initProject(root);
+    const model = taskModel();
+    const decision = evaluateLifecycleRiskDecisionForModel('master', model);
+    await recordRuntimeProjectionEnvelope(root, {
+      projectionType: LIFECYCLE_RISK_DECISION_PROJECTION_TYPE,
+      scopeKey: lifecycleRiskDecisionScopeKey(decision.scope),
+      inputHash: decision.inputHash,
+      producer: 'phase8-risk-kernel',
+      producerVersion: 'phase8-risk-kernel-v0',
+      payload: {
+        ...decision,
+        policyVersion: 'phase8-risk-kernel-v0'
+      },
+      generatedAt: '2026-05-01T00:00:00.000Z'
+    });
+    const diagnostic = await inspectLifecycleRiskDecisionForModel(root, 'master', model);
+
+    assert.equal(diagnostic.status, 'incompatible');
+    assert.equal(diagnostic.producerVersion, 'phase8-risk-kernel-v0');
+    assert.equal(diagnostic.expectedProducerVersion, LIFECYCLE_RISK_POLICY_VERSION);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+function signal(dimension: CodingRiskSignal['dimension'], level: CodingRiskSignal['level'], confidence: CodingRiskSignal['confidence']): CodingRiskSignal {
+  return {
+    id: `test:${dimension}:${level}:${confidence}`,
+    dimension,
+    level,
+    scope,
+    confidence,
+    inputRefs: [{ kind: 'task', ref: 'PHASE8-3' }],
+    reasons: [`${dimension} ${level} test signal`]
+  };
+}
+
+function knownFacts() {
+  return {
+    request: { intentKnown: true, acceptanceKnown: true, validationKnown: true },
+    documents: { specExists: true, planExists: true, tasksExists: true, verifiesExists: false }
+  };
+}
+
+function taskModel(options: { specExists?: boolean; tasks?: SddTask[] } = {}): SddTaskModel {
+  const tasks = options.tasks ?? [task()];
+  const specExists = options.specExists ?? true;
+  return {
+    branch: 'master',
+    specPath: 'specs/master/spec.md',
+    planPath: 'specs/master/plan.md',
+    tasksPath: 'specs/master/tasks.md',
+    verifyPath: 'specs/master/verify.md',
+    documents: {
+      specExists,
+      planExists: true,
+      tasksExists: tasks.length > 0,
+      verifyExists: true
+    },
+    tasks,
+    gaps: []
+  };
+}
+
+function task(): SddTask {
+  return {
+    id: 'PHASE8-4',
+    title: 'Integrate lifecycle risk diagnostics',
+    status: 'pending',
+    wave: null,
+    implementationWave: null,
+    validationBatch: null,
+    validationTiming: 'task_end',
+    requiresVerifyBeforeNext: true,
+    changeSurface: 'unknown',
+    dependsOn: [],
+    affectedFiles: ['packages/core/src/status/project-status.ts'],
+    validation: ['npm test'],
+    validationCommands: [],
+    risk: [],
+    acceptanceRefs: [],
+    planRefs: [],
+    fileOwnership: [],
+    agentFit: [],
+    verificationAvailability: [],
+    autonomy: null,
+    allowedAgents: [],
+    requiredArtifacts: [],
+    gapState: null,
+    boundary: null,
+    acceptance: [],
+    implementationNotes: null,
+    rawMetadata: {},
+    source: {
+      filePath: 'specs/master/tasks.md',
+      heading: null,
+      lineStart: 1,
+      lineEnd: 1
+    }
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/planning/task-graph.test.ts

@@ -0,0 +1,88 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { doctor } from '../doctor/doctor.js';
+import { graphTaskMarkdown, harnessTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { inspectTaskGraph } from './task-graph.js';
+
+test('task graph planner builds dependency and file overlap graph', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-valid-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('G1', [], ['src/a.ts'], [])}\n${graphTaskMarkdown('G2', ['G1'], ['./src/a.ts', 'src/b.ts'], ['security'])}`);
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+
+    assert.equal(graph.version, 'phase-3.9-task-graph-planner-v1');
+    assert.equal(graph.valid, true);
+    assert.equal(graph.nodes.length, 2);
+    assert.deepEqual(graph.dependencyEdges, [{ from: 'G1', to: 'G2', type: 'depends_on', files: [] }]);
+    assert.deepEqual(graph.fileOverlapEdges, [{ from: 'G1', to: 'G2', type: 'file_overlap', files: ['src/a.ts'] }]);
+    assert.deepEqual(graph.summary.highRiskTasks, ['G2']);
+    assert.deepEqual(graph.summary.validationCommands, ['npm test']);
+    assert.deepEqual(graph.summary.riskNotes, ['G2:high:security']);
+    assert.equal(graph.contract, 'phase-5.3-task-graph-v1');
+    assert.deepEqual(graph.nodes[1].agentFit, []);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('task graph parses Phase 5.3 harness metadata fields', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-phase53-task-graph-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${harnessTaskMarkdown('H1')}`);
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+    const node = graph.nodes[0];
+
+    assert.equal(graph.contract, 'phase-5.3-task-graph-v1');
+    assert.deepEqual(node.fileOwnership, ['packages/core/src/index.ts']);
+    assert.deepEqual(node.agentFit, ['implementer', 'validator']);
+    assert.deepEqual(node.verificationAvailability, ['unit-test', 'cli-smoke']);
+    assert.equal(node.autonomy, 'foreground_write');
+    assert.deepEqual(node.allowedAgents, ['implementer', 'validator']);
+    assert.deepEqual(node.requiredArtifacts, ['artifacts/implementer-H1.md', 'artifacts/validation-H1.md']);
+    assert.equal(node.gapState, 'none');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('task graph planner blocks missing dependency and cycle diagnostics', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-blocked-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', `# Tasks\n\n${graphTaskMarkdown('C1', ['C2'], ['src/c1.ts'], [])}\n${graphTaskMarkdown('C2', ['C1'], ['src/c2.ts'], [])}\n${graphTaskMarkdown('M1', ['M404'], ['src/m1.ts'], [])}`);
+
+    const graph = await inspectTaskGraph(root, { branch: 'master' });
+
+    assert.equal(graph.valid, false);
+    assert.equal(graph.diagnostics.some((diagnostic) => /unknown task M404/.test(diagnostic.message)), true);
+    assert.equal(graph.diagnostics.some((diagnostic) => /Task dependency cycle detected: C1 -> C2 -> C1|Task dependency cycle detected: C2 -> C1 -> C2/.test(diagnostic.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('doctor reports task graph planner contract visibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-graph-doctor-'));
+  try {
+    await initProject(root);
+
+    const report = await doctor(root, { latestOnly: true });
+    const check = report.checks.find((item) => item.check === 'task_graph_planner_contract');
+
+    assert.equal(check?.level, 'PASS');
+    assert.match(check?.message ?? '', /phase-3\.9-task-graph-planner-v1/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});