sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/runtime-projection-p0.ts

@@ -0,0 +1,314 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import type { RuntimeProjectionEnvelope, RuntimeProjectionStaleness, RuntimeRef } from './contracts.js';
+import { branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import { hashDocumentContent } from './sdd-docs/document-hashes.js';
+import { listRuntimeProjections, readRuntimeProjectionEnvelope, recordRuntimeProjectionEnvelope, runtimeProjectionStaleness, type RuntimeProjectionEnvelopeWriteResult } from './storage/runtime-store.js';
+import {
+  NEXT_INTENT_PROJECTION_TYPE,
+  TASK_ORCHESTRATION_PROJECTION_TYPE,
+  VALIDATION_UNIT_PROJECTION_TYPE,
+  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE
+} from './workflow-state/runtime-projections.js';
+import {
+  DIAGNOSTIC_PROJECTION_TYPE,
+  EVIDENCE_SELECTION_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+  LIFECYCLE_ROUTE_PROJECTION_TYPE,
+  STAGE_WORK_ORDER_PROJECTION_TYPE
+} from './lifecycle-graph.js';
+
+export const RUNTIME_PROJECTION_P0_CONTRACT_VERSION = 'phase9.19-runtime-sqlite-contract-projection-p0-v1' as const;
+export const RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE = 'phase9_19_ref_hash_registry';
+export const RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION = 'phase9.19-ref-hash-registry-v1';
+export const STAGE_ROUTE_BINDING_PROJECTION_TYPE = 'phase9_18_stage_route_binding';
+export const STAGE_ROUTE_BINDING_PRODUCER_VERSION = 'phase9.18-stage-route-binding-v1';
+export const TRUTH_RECONCILIATION_PROJECTION_TYPE = 'phase9_21_truth_reconciliation';
+
+export type RuntimeProjectionP0Key =
+  | 'lifecycleDecisions'
+  | 'riskSignals'
+  | 'stageRuns'
+  | 'stageHandoffs'
+  | 'gates'
+  | 'gapBlockers'
+  | 'evidenceItems'
+  | 'evidenceSets'
+  | 'selectionPointers'
+  | 'workflowCurrentState'
+  | 'taskOrchestration'
+  | 'validationUnits'
+  | 'truthAlignment'
+  | 'truthReconciliation'
+  | 'stageRouteBindings'
+  | 'nextIntent'
+  | 'lifecycleGraphInstances'
+  | 'lifecycleRoutes'
+  | 'stageWorkOrders'
+  | 'evidenceSelections'
+  | 'diagnosticProjections'
+  | 'auditEvents';
+
+export type RuntimeProjectionP0Storage = 'sqlite' | 'sqlite-ref-hash-only' | 'sqlite-projection';
+export type RuntimeProjectionP0HealthStatus = 'pass' | 'warn' | 'blocked';
+export type RuntimeRefFreshnessStatus = 'fresh' | 'stale' | 'missing' | 'unhashed' | 'unsafe' | 'not_file_backed';
+
+export interface RuntimeProjectionP0InventoryItem {
+  key: RuntimeProjectionP0Key;
+  storage: RuntimeProjectionP0Storage;
+  primitive: string;
+  writer: 'runtime';
+  responsibility: string;
+  consumers: string[];
+  markdownBodyAuthority: false;
+}
+
+export interface RuntimeRefFreshness {
+  ref: RuntimeRef;
+  normalizedRef: string;
+  expectedHash: string | null;
+  currentHash: string | null;
+  status: RuntimeRefFreshnessStatus;
+  reason: string;
+}
+
+export interface RuntimeRefHashRegistryProjection {
+  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
+  branch: string;
+  refs: RuntimeRefFreshness[];
+  status: 'fresh' | 'blocked';
+  staleRefs: RuntimeRef[];
+  reasons: string[];
+}
+
+export interface RuntimeProjectionP0Diagnostic {
+  contract: typeof RUNTIME_PROJECTION_P0_CONTRACT_VERSION;
+  branch: string;
+  status: RuntimeProjectionP0HealthStatus;
+  inventory: RuntimeProjectionP0InventoryItem[];
+  projectionCounts: Record<string, number>;
+  refHashRegistry: {
+    projectionType: typeof RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE;
+    envelopeStaleness: RuntimeProjectionStaleness;
+    status: RuntimeRefHashRegistryProjection['status'] | 'missing';
+    staleRefs: RuntimeRef[];
+    reasons: string[];
+  };
+  reasons: string[];
+}
+
+export const RUNTIME_PROJECTION_P0_INVENTORY: readonly RuntimeProjectionP0InventoryItem[] = [
+  inventoryItem('lifecycleDecisions', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Lifecycle/risk authority created only by /sdd or /sdd:spec.', ['router', 'stage-close', 'status', 'doctor']),
+  inventoryItem('riskSignals', 'sqlite', 'projections:phase8_lifecycle_risk_decision', 'Risk signal snapshot and lifecycle policy output for routing and gates.', ['router', 'workflow-gate', 'status']),
+  inventoryItem('stageRuns', 'sqlite', 'projections:phase8_stage_run', 'Runtime-owned stage run state and terminal health.', ['status', 'stage-close', 'ship']),
+  inventoryItem('stageHandoffs', 'sqlite', 'projections:phase8_workflow_handoff', 'Runtime handoff packet between completed stages and next runtime stage.', ['status', 'stage-close']),
+  inventoryItem('gates', 'sqlite', 'workflow_gate_decisions', 'Hard gate decisions and policy outcomes.', ['workflow-gate', 'status', 'ship']),
+  inventoryItem('gapBlockers', 'sqlite', 'durable_gaps', 'Mutable gap/blocker lifecycle with runtime status authority.', ['doctor', 'status', 'stage-close']),
+  inventoryItem('evidenceItems', 'sqlite-ref-hash-only', 'stage_artifacts/artifact_payloads', 'Agent-authored Markdown evidence registered by ref, hash, contract, producer, and status.', ['workflow-gate', 'stage-close', 'doctor']),
+  inventoryItem('evidenceSets', 'sqlite-ref-hash-only', 'evidence_sets/evidence_set_items', 'Accepted evidence sets selected by refs and digests, not Markdown bodies.', ['workflow-gate', 'ship', 'status']),
+  inventoryItem('selectionPointers', 'sqlite', 'selection_pointers', 'Active accepted evidence pointer for downstream consumers.', ['workflow-gate', 'latest-eligible-run', 'ship']),
+  inventoryItem('workflowCurrentState', 'sqlite-projection', `projections:${WORKFLOW_CURRENT_STATE_PROJECTION_TYPE}`, 'Runtime-owned lifecycle, task, and validation-unit current state projection.', ['status', 'router', 'ai-tool-entry']),
+  inventoryItem('taskOrchestration', 'sqlite-projection', `projections:${TASK_ORCHESTRATION_PROJECTION_TYPE}`, 'Parsed task orchestration read model with task-level hashes, dependencies, validation unit binding, and capability signals.', ['status', 'do-manager', 'tasks-manager']),
+  inventoryItem('validationUnits', 'sqlite-projection', `projections:${VALIDATION_UNIT_PROJECTION_TYPE}`, 'Runtime validation-unit read model derived from verify contracts and task orchestration.', ['status', 'test-manager', 'workflow-gate']),
+  inventoryItem('truthAlignment', 'sqlite', 'projections:phase9_12_truth_alignment', 'Goal-verify truth alignment projection for ship readiness.', ['ship', 'status']),
+  inventoryItem('truthReconciliation', 'sqlite', `projections:${TRUTH_RECONCILIATION_PROJECTION_TYPE}`, 'Owner-stage reconciliation decision slot for minimal rerun frontier.', ['orchestrator', 'status', 'ship']),
+  inventoryItem('stageRouteBindings', 'sqlite', `projections:${STAGE_ROUTE_BINDING_PROJECTION_TYPE}`, 'Stage-local command input binding to an accepted runtime target.', ['router', 'status']),
+  inventoryItem('nextIntent', 'sqlite-projection', `projections:${NEXT_INTENT_PROJECTION_TYPE}`, 'Advisory runtime next-action read model; execution still checks readiness and gates.', ['status', 'ai-tool-entry']),
+  inventoryItem('lifecycleGraphInstances', 'sqlite-projection', `projections:${LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE}`, 'Runtime-owned lifecycle graph instance derived from active lifecycle risk authority.', ['status', 'instructions', 'doctor', 'router', 'stage-close']),
+  inventoryItem('lifecycleRoutes', 'sqlite-projection', `projections:${LIFECYCLE_ROUTE_PROJECTION_TYPE}`, 'Graph-owned legal next action and blocker route projection.', ['status', 'instructions', 'doctor', 'router']),
+  inventoryItem('stageWorkOrders', 'sqlite-projection', `projections:${STAGE_WORK_ORDER_PROJECTION_TYPE}`, 'Stage-local work order schemas, required refs, and closure commands.', ['instructions', 'stage-close', 'do-manager', 'test-manager']),
+  inventoryItem('evidenceSelections', 'sqlite-projection', `projections:${EVIDENCE_SELECTION_PROJECTION_TYPE}`, 'Runtime-selected evidence obligations and selected accepted refs.', ['status', 'stage-close', 'workflow-gate', 'doctor']),
+  inventoryItem('diagnosticProjections', 'sqlite-projection', `projections:${DIAGNOSTIC_PROJECTION_TYPE}`, 'Blocker-specific diagnostics and recovery commands for lifecycle graph consumers.', ['doctor', 'status', 'instructions', 'router']),
+  inventoryItem('auditEvents', 'sqlite', 'events/activities', 'Append-only runtime events and activity records for auditability.', ['doctor', 'run-inspect'])
+];
+
+export const RUNTIME_PROJECTION_P0_PROJECTION_TYPES = [
+  'phase8_lifecycle_risk_decision',
+  'phase8_stage_run',
+  'phase8_workflow_handoff',
+  'phase9_12_truth_alignment',
+  TRUTH_RECONCILIATION_PROJECTION_TYPE,
+  STAGE_ROUTE_BINDING_PROJECTION_TYPE,
+  WORKFLOW_CURRENT_STATE_PROJECTION_TYPE,
+  TASK_ORCHESTRATION_PROJECTION_TYPE,
+  VALIDATION_UNIT_PROJECTION_TYPE,
+  NEXT_INTENT_PROJECTION_TYPE,
+  LIFECYCLE_GRAPH_INSTANCE_PROJECTION_TYPE,
+  LIFECYCLE_ROUTE_PROJECTION_TYPE,
+  STAGE_WORK_ORDER_PROJECTION_TYPE,
+  EVIDENCE_SELECTION_PROJECTION_TYPE,
+  DIAGNOSTIC_PROJECTION_TYPE,
+  RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE
+] as const;
+
+export async function inspectRuntimeProjectionP0(projectRoot: string, branch: string): Promise<RuntimeProjectionP0Diagnostic> {
+  const partition = branchToSafePartition(branch);
+  const projections = await listRuntimeProjections(projectRoot, [...RUNTIME_PROJECTION_P0_PROJECTION_TYPES]);
+  const projectionCounts = Object.fromEntries(RUNTIME_PROJECTION_P0_PROJECTION_TYPES.map((projectionType) => [projectionType, projections.filter((projection) => projection.projectionType === projectionType).length]));
+  const envelope = await readRuntimeRefHashRegistryProjection(projectRoot, partition);
+  const refHashRegistry = await inspectRefHashRegistry(projectRoot, partition, envelope);
+  const status: RuntimeProjectionP0HealthStatus = refHashRegistry.status === 'blocked' ? 'blocked' : envelope ? 'pass' : 'warn';
+  const reasons = runtimeProjectionP0Reasons(status, refHashRegistry.reasons);
+  return {
+    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
+    branch: partition,
+    status,
+    inventory: [...RUNTIME_PROJECTION_P0_INVENTORY],
+    projectionCounts,
+    refHashRegistry,
+    reasons
+  };
+}
+
+export async function recordRuntimeRefHashRegistryProjection(projectRoot: string, input: { branch: string; refs: RuntimeRef[]; generatedAt?: string }): Promise<RuntimeProjectionEnvelopeWriteResult<RuntimeRefHashRegistryProjection>> {
+  const branch = branchToSafePartition(input.branch);
+  const refs = await inspectRuntimeRefFreshness(projectRoot, input.refs);
+  const staleRefs = refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
+  const projection: RuntimeRefHashRegistryProjection = {
+    contract: RUNTIME_PROJECTION_P0_CONTRACT_VERSION,
+    branch,
+    refs,
+    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
+    staleRefs,
+    reasons: refHashRegistryReasons(staleRefs, refs)
+  };
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+    scopeKey: runtimeRefHashRegistryScopeKey(branch),
+    inputHash: runtimeProjectionStableHash(projection),
+    producer: 'phase9.19-runtime-projection-p0',
+    producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION,
+    generatedAt: input.generatedAt,
+    payload: projection
+  });
+}
+
+export async function readRuntimeRefHashRegistryProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null> {
+  return readRuntimeProjectionEnvelope(projectRoot, RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE, runtimeRefHashRegistryScopeKey(branchToSafePartition(branch)));
+}
+
+export async function inspectRuntimeRefFreshness(projectRoot: string, refs: RuntimeRef[]): Promise<RuntimeRefFreshness[]> {
+  return Promise.all(refs.map((ref) => inspectRuntimeRef(projectRoot, ref)));
+}
+
+export function runtimeRefHashRegistryScopeKey(branch: string): string {
+  return [branchToSafePartition(branch), 'ref-hash-registry'].join(':');
+}
+
+export function runtimeProjectionStableHash(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+async function inspectRefHashRegistry(projectRoot: string, branch: string, envelope: RuntimeProjectionEnvelope<RuntimeRefHashRegistryProjection> | null): Promise<RuntimeProjectionP0Diagnostic['refHashRegistry']> {
+  if (!envelope) {
+    return {
+      projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+      envelopeStaleness: 'unknown',
+      status: 'missing',
+      staleRefs: [],
+      reasons: ['Runtime ref/hash registry projection is missing; register accepted Markdown refs before relying on freshness diagnostics.']
+    };
+  }
+  const currentRefs = await inspectRuntimeRefFreshness(projectRoot, envelope.payload.refs.map((entry) => entry.ref));
+  const staleRefs = currentRefs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.ref);
+  const currentProjection: RuntimeRefHashRegistryProjection = {
+    ...envelope.payload,
+    refs: currentRefs,
+    status: staleRefs.length === 0 ? 'fresh' : 'blocked',
+    staleRefs,
+    reasons: refHashRegistryReasons(staleRefs, currentRefs)
+  };
+  return {
+    projectionType: RUNTIME_REF_HASH_REGISTRY_PROJECTION_TYPE,
+    envelopeStaleness: runtimeProjectionStaleness(envelope, {
+      inputHash: runtimeProjectionStableHash(currentProjection),
+      producerVersion: RUNTIME_REF_HASH_REGISTRY_PRODUCER_VERSION
+    }),
+    status: currentProjection.status,
+    staleRefs,
+    reasons: currentProjection.reasons
+  };
+}
+
+async function inspectRuntimeRef(projectRoot: string, ref: RuntimeRef): Promise<RuntimeRefFreshness> {
+  const normalizedRef = normalizePortablePath(ref.ref);
+  if (!isFileBackedRef(ref)) {
+    return freshness(ref, normalizedRef, null, null, 'not_file_backed', `Runtime ref kind ${ref.kind} is not file-backed.`);
+  }
+  if (!ref.hash) {
+    return freshness(ref, normalizedRef, null, null, 'unhashed', `File-backed ref ${ref.ref} has no expected hash.`);
+  }
+  const safePath = safeProjectRelativePath(projectRoot, normalizedRef);
+  if (!safePath) {
+    return freshness(ref, normalizedRef, ref.hash, null, 'unsafe', `File-backed ref ${ref.ref} is not a safe project-relative path.`);
+  }
+  try {
+    const currentHash = hashDocumentContent(await readFile(safePath, 'utf8'));
+    return hashMatches(ref.hash, currentHash)
+      ? freshness(ref, normalizedRef, ref.hash, currentHash, 'fresh', `File-backed ref ${normalizedRef} is fresh.`)
+      : freshness(ref, normalizedRef, ref.hash, currentHash, 'stale', `File-backed ref ${normalizedRef} hash is stale: expected ${ref.hash}, actual ${currentHash}.`);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return freshness(ref, normalizedRef, ref.hash, null, 'missing', `File-backed ref ${normalizedRef} is missing.`);
+    }
+    throw error;
+  }
+}
+
+function inventoryItem(key: RuntimeProjectionP0Key, storage: RuntimeProjectionP0Storage, primitive: string, responsibility: string, consumers: string[]): RuntimeProjectionP0InventoryItem {
+  return { key, storage, primitive, writer: 'runtime', responsibility, consumers, markdownBodyAuthority: false };
+}
+
+function runtimeProjectionP0Reasons(status: RuntimeProjectionP0HealthStatus, refHashReasons: string[]): string[] {
+  if (status === 'blocked') {
+    return refHashReasons;
+  }
+  if (status === 'warn') {
+    return ['Runtime projection P0 inventory is available; ref/hash freshness registry has not been recorded yet.'];
+  }
+  return ['Runtime projection P0 inventory is available and registered file-backed refs are fresh.'];
+}
+
+function refHashRegistryReasons(staleRefs: RuntimeRef[], refs: RuntimeRefFreshness[]): string[] {
+  if (staleRefs.length === 0) {
+    return ['Registered file-backed refs are fresh; non-file-backed refs remain metadata-only.'];
+  }
+  return refs.filter((ref) => blocksRefHashRegistry(ref.status)).map((ref) => ref.reason);
+}
+
+function blocksRefHashRegistry(status: RuntimeRefFreshnessStatus): boolean {
+  return status === 'stale' || status === 'missing' || status === 'unhashed' || status === 'unsafe';
+}
+
+function isFileBackedRef(ref: RuntimeRef): boolean {
+  if (ref.kind === 'document' || ref.kind === 'artifact' || ref.kind === 'evidence') {
+    return true;
+  }
+  return /^(specs|runs)\//.test(normalizePortablePath(ref.ref));
+}
+
+function safeProjectRelativePath(projectRoot: string, normalizedRef: string): string | null {
+  if (path.isAbsolute(normalizedRef) || normalizedRef.startsWith('../') || normalizedRef === '..') {
+    return null;
+  }
+  const projectPath = path.resolve(projectRoot);
+  const absolutePath = path.resolve(projectPath, normalizedRef);
+  return absolutePath === projectPath || absolutePath.startsWith(`${projectPath}${path.sep}`) ? absolutePath : null;
+}
+
+function freshness(ref: RuntimeRef, normalizedRef: string, expectedHash: string | null, currentHash: string | null, status: RuntimeRefFreshnessStatus, reason: string): RuntimeRefFreshness {
+  return { ref: { ...ref, ref: normalizedRef }, normalizedRef, expectedHash, currentHash, status, reason };
+}
+
+function hashMatches(expected: string, actual: string): boolean {
+  return expected.replace(/^sha256:/, '') === actual.replace(/^sha256:/, '');
+}
+
+function isMissingFileError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+  return 'code' in error && (error as { code?: unknown }).code === 'ENOENT';
+}

package/node_modules/@sdd-agent-platform/core/src/sdd-docs/artifact-depth.test.ts

@@ -0,0 +1,380 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { evaluatePlanArtifactDepth, evaluateSpecArtifactDepth, evaluateTasksArtifactDepth, formatArtifactDepthBlockingIssues } from './artifact-depth.js';
+
+test('spec artifact depth reports missing evidence targets and unrouted ambiguity', () => {
+  const issues = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Thin Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request: change the report. Reframed problem: clarify the reporting contract. Inferred real intent: reduce downstream ambiguity.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add the report. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Priority |
+|---|---|---|---|
+| AC-1 | It works. | REQ-1 | Must |
+
+## Definitions / Rules
+
+Domain rule: reporting scope is branch-local.
+
+## Open Questions / Ambiguity Ledger
+
+None.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'spec.ambiguity.unrouted',
+    'spec.too_thin.acceptance_evidence_missing'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['spec.ambiguity.unrouted', 'warning'],
+    ['spec.too_thin.acceptance_evidence_missing', 'warning']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('plan artifact depth treats implementation-decided API and SQL as blocker', () => {
+  const issues = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Thin Plan
+
+## Current Implementation Map
+
+Observed \`ReportController\` and \`ReportMapper.xml\`; therefore the design must reuse existing controller ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+The API and SQL will be finalized during implementation. It uses SQL table joins and source fields.
+
+## State / Data / Concurrency Design
+
+The database query reads report tables and aggregates rows.
+
+## Risk Controls
+
+Risk: wrong aggregation. Control: validation hook in scenario tests.
+
+## Validation Strategy
+
+Scenario: query report. Input data: seeded rows. Expected SQL result: exact grouped rows. Command / evidence: integration test. Proves aggregation. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'plan.downstream_guesswork.tasks_or_execute_would_redesign',
+    'plan.too_thin.api_shape_not_decided',
+    'plan.too_thin.sql_mapping_missing_join_keys'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['plan.downstream_guesswork.tasks_or_execute_would_redesign', 'blocker'],
+    ['plan.too_thin.api_shape_not_decided', 'warning'],
+    ['plan.too_thin.sql_mapping_missing_join_keys', 'warning']
+  ]);
+  assert.equal(formatArtifactDepthBlockingIssues(issues).length, 1);
+});
+
+test('plan artifact depth keeps thin but decided mapping as warning-only diagnostics', () => {
+  const issues = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Warning Plan
+
+## Current Implementation Map
+
+Observed 'ReportController' and 'ReportMapper.xml'; therefore the design reuses existing controller ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+The endpoint returns report rows from the existing mapper. SQL uses report joins and source fields selected by the accepted plan.
+
+## State / Data / Concurrency Design
+
+The database query reads report tables and aggregates rows.
+
+## Risk Controls
+
+Risk: wrong aggregation. Control: validation hook in scenario tests.
+
+## Validation Strategy
+
+Scenario: query report. Input data: seeded rows. Expected SQL result: exact grouped rows. Command / evidence: integration test. Proves aggregation. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['plan.too_thin.api_shape_not_decided', 'warning'],
+    ['plan.too_thin.sql_mapping_missing_join_keys', 'warning']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('tasks artifact depth reports missing failure route and leaked execute guesswork', () => {
+  const issues = evaluateTasksArtifactDepth(`---
+contract: sdd-tasks-doc-v2
+---
+
+# Thin Tasks
+
+## Split Basis
+
+Split from plan decisions into implementation and validation tasks.
+
+## Implementation Tasks
+
+### T1 — Implement report
+
+Why this task exists: implements PLAN-1 and execute must not reinterpret scope.
+
+Implementation will determine the final SQL join and response fields.
+
+\`\`\`sdd-task
+id: T1
+status: pending
+taskClass: implementation
+unitType: core
+wave: 1
+validationHandoff:
+  - T2
+\`\`\`
+
+## Validation Tasks
+
+### T2 — Validate report
+
+Expected result: report rows match the accepted plan.
+
+\`\`\`sdd-task
+id: T2
+status: pending
+taskClass: validation
+unitType: validation
+wave: 2
+validatesImplementationTasks:
+  - T1
+\`\`\`
+
+## Task Dependencies and Handoff
+
+T2 depends on T1.
+
+## Open Execution Questions
+
+None.
+
+## Tasks Close Quality Evidence
+
+- downstream_execution_guesswork_remaining: []
+`);
+
+  assert.deepEqual(issues.map((issue) => issue.code).sort(), [
+    'tasks.failure_route.missing',
+    'tasks.plan_repair.design_guesswork_leaked_to_execute'
+  ]);
+  assert.deepEqual(issues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['tasks.failure_route.missing', 'blocker'],
+    ['tasks.plan_repair.design_guesswork_leaked_to_execute', 'blocker']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues).map((item) => item.replace(/:.*/, '')), ['blocker', 'blocker']);
+});
+
+test('tasks artifact depth accepts oversized slice when tasks-manager records keep-together decision', () => {
+  const issues = evaluateTasksArtifactDepth(`---
+contract: sdd-tasks-doc-v2
+---
+
+# Reviewed Tasks
+
+## Split Basis
+
+Tasks-manager reviewed the split decision: keep together as one backend/runtime rollback unit because Controller, Service, Mapper, DTO, VO, XML, and SQL must be reverted together. Internal order: controller route, service read model, mapper XML, SQL filters, DTO/VO wiring.
+
+## Implementation Tasks
+
+### T1 — Implement report read model
+
+Why this task exists: implements PLAN-1. Work-unit context: the backend/runtime rollback unit must stay together. Plan decision: preserve existing controller ownership. Risk: execute must not reinterpret SQL ownership.
+
+Change Controller, Service, Mapper, DTO, VO, mapper XML, SQL, JSP, and UI configuration in one task. Affected surfaces: ReportController, ReportService, ReportMapper, ReportDTO, ReportVO, mapper XML, permission SQL, JSP, and UI route.
+
+\`\`\`sdd-task
+id: T1
+status: pending
+taskClass: implementation
+unitType: core
+wave: 1
+validationHandoff:
+  - T2
+\`\`\`
+
+## Validation Tasks
+
+### T2 — Validate report read model
+
+Expected result: report rows match the accepted plan. Evidence is enough when SQL/API review proves the read model; does not prove release readiness.
+
+\`\`\`sdd-task
+id: T2
+status: pending
+taskClass: validation
+unitType: validation
+wave: 2
+validatesImplementationTasks:
+  - T1
+\`\`\`
+
+## Task Dependencies and Handoff
+
+T2 depends on T1.
+
+## Open Execution Questions
+
+No blocking execution questions. Failure route: tasks repair, plan repair, spec/user decision, or environment diagnostic.
+
+## Tasks Close Quality Evidence
+
+- downstream_execution_guesswork_remaining: []
+`);
+
+  assert.equal(issues.some((issue) => issue.code === 'tasks.review.split_adjudication_missing'), false);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(issues), []);
+});
+
+test('artifact depth keeps advisory and warning diagnostics out of blocking formatter', () => {
+  const specIssues = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Advisory Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request only.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add the report because the branch scope requires it. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Evidence Target |
+|---|---|---|---|
+| AC-1 | Report returns branch-local rows. | REQ-1 | API test evidence target. |
+
+## Definitions / Rules
+
+Domain rule: branch-local report scope is invariant.
+
+## Open Questions / Ambiguity Ledger
+
+No blocking user decisions. Researchable gaps: none. Safe assumptions: none. Deferred: none.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: []
+`);
+
+  assert.deepEqual(specIssues.map((issue) => [issue.code, issue.severity]).sort(), [
+    ['spec.too_thin.problem_reframing_missing', 'advisory']
+  ]);
+  assert.deepEqual(formatArtifactDepthBlockingIssues(specIssues), []);
+});
+
+test('artifact depth treats explicit downstream guesswork as blocker across stages', () => {
+  const specBlockers = evaluateSpecArtifactDepth(`---
+contract: sdd-spec-doc-v3
+---
+
+# Blocked Spec
+
+## Problem Reframing / Intent Discovery
+
+Surface request: change report. Reframed problem: clarify report semantics. Inferred real intent: avoid ambiguity.
+
+## Requirements
+
+| ID | Requirement | Priority | Source |
+|---|---|---|---|
+| REQ-1 | Add report because branch scope requires it. | Must | user |
+
+## Acceptance Criteria / Evidence Targets
+
+| ID | Acceptance | Covers | Evidence Target |
+|---|---|---|---|
+| AC-1 | Report returns branch-local rows. | REQ-1 | API evidence target. |
+
+## Definitions / Rules
+
+Domain rule: branch-local report scope is invariant.
+
+## Open Questions / Ambiguity Ledger
+
+No blocking user decisions. Researchable gaps: none. Safe assumptions: none. Deferred: none.
+
+## Close Quality Evidence
+
+- downstream_business_guesswork_remaining: [\"report ownership undecided\"]
+`);
+  const planBlockers = evaluatePlanArtifactDepth(`---
+contract: sdd-plan-doc-v3
+---
+
+# Blocked Plan
+
+## Current Implementation Map
+
+Observed 'ReportController' and 'ReportMapper.xml'; therefore the design reuses existing ownership and mapper conventions.
+
+## Interface / API / Schema Design
+
+Request field 'branchId'; response DTO 'ReportRowVO'; mapper field 'report.branch_id'; status field 'report.status'. No SQL table ownership changes.
+
+## State / Data / Concurrency Design
+
+Runtime reads 'report.branch_id', 'report.status', 'report.created_at', 'report.asset_id', and 'report.amount'; rollback is not applicable because this is read-only.
+
+## Risk Controls
+
+Risk: wrong branch filter. Control: scenario validation checks SQL evidence.
+
+## Validation Strategy
+
+Scenario: query report. Input data: branch rows. Expected SQL result: exact rows. Command evidence: integration test. Proves branch filter. Does not prove UI styling.
+
+## Plan Close Quality Evidence
+
+- downstream_design_guesswork_remaining: [\"SQL grouping undecided\"]
+`);
+
+  assert.equal(specBlockers.find((issue) => issue.code === 'spec.downstream_guesswork.plan_would_rediscover_requirements')?.severity, 'blocker');
+  assert.equal(planBlockers.find((issue) => issue.code === 'plan.downstream_guesswork.tasks_or_execute_would_redesign')?.severity, 'blocker');
+  assert.equal(formatArtifactDepthBlockingIssues(specBlockers).length, 1);
+  assert.equal(formatArtifactDepthBlockingIssues(planBlockers).length, 1);
+});