sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { assertSafePathSegment, branchToSafePartition, normalizePortablePath } from './path-safety.js';
+import type { SddStage } from './contracts.js';
 
 export function getWorktreesDir(projectRoot: string): string {
   return path.join(getSddDir(projectRoot), 'worktrees');
@@ -17,6 +18,64 @@ export function getRunsDir(projectRoot: string): string {
   return path.join(getSddDir(projectRoot), 'runs');
 }
 
+export function getRunEvidenceRoot(projectRoot: string): string {
+  return getRunsDir(projectRoot);
+}
+
+export function getBranchStageEvidenceDir(projectRoot: string, branch: string, stage: SddStage): string {
+  return path.join(getRunEvidenceRoot(projectRoot), branchToSafePartition(branch), assertKnownSddStage(stage));
+}
+
+export function getBranchStageEvidencePath(projectRoot: string, branch: string, stage: SddStage, fileName: string): string {
+  return path.join(getBranchStageEvidenceDir(projectRoot, branch, stage), normalizeBranchStageEvidenceFileName(fileName));
+}
+
+export function toBranchStageEvidenceRef(branch: string, stage: SddStage, fileName: string): string {
+  return `.sdd/runs/${branchToSafePartition(branch)}/${assertKnownSddStage(stage)}/${normalizeBranchStageEvidenceFileName(fileName)}`;
+}
+
+export function normalizeBranchStageEvidenceRef(value: string): string {
+  const normalized = normalizePortablePath(value);
+  if (path.isAbsolute(value) || !normalized.startsWith('.sdd/runs/')) {
+    throw new Error(`Stage evidence ref must start with .sdd/runs/: ${value}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.length !== 5) {
+    throw new Error(`Stage evidence ref must be .sdd/runs/<branch>/<stage>/<file>: ${value}`);
+  }
+  assertSafePathSegment(parts[2], 'branch');
+  assertKnownSddStage(parts[3]);
+  normalizeBranchStageEvidenceFileName(parts[4]);
+  return parts.join('/');
+}
+
+export function isBranchStageEvidenceRef(value: string): boolean {
+  try {
+    normalizeBranchStageEvidenceRef(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getBranchStageEvidencePathFromRef(projectRoot: string, ref: string): string {
+  return path.join(projectRoot, ...normalizeBranchStageEvidenceRef(ref).split('/'));
+}
+
+export function normalizeStageEvidenceOrLegacyArtifactRef(value: string): string {
+  if (isBranchStageEvidenceRef(value)) {
+    return normalizeBranchStageEvidenceRef(value);
+  }
+  return getRunRelativeArtifactPath(toArtifactRootRelativePath(value));
+}
+
+export function toEvidencePayloadFileName(value: string): string {
+  if (isBranchStageEvidenceRef(value)) {
+    return normalizeBranchStageEvidenceRef(value).split('/')[4];
+  }
+  return toArtifactRootRelativePath(value);
+}
+
 export function getLocalRunIndexPath(projectRoot: string): string {
   return path.join(getSddDir(projectRoot), 'run-index.json');
 }
@@ -25,11 +84,15 @@ export function getRuntimeStorePath(projectRoot: string): string {
   return path.join(getSddDir(projectRoot), 'runtime.sqlite');
 }
 
-export function getRunDir(projectRoot: string, runId: string): string {
+export function getLegacyRunDir(projectRoot: string, runId: string): string {
   assertSafePathSegment(runId, 'runId');
   return path.join(getRunsDir(projectRoot), runId);
 }
 
+export function getRunDir(projectRoot: string, runId: string): string {
+  return getLegacyRunDir(projectRoot, runId);
+}
+
 export function getBranchRunRoot(projectRoot: string, branchSlug: string): string {
   return path.join(getRunsDir(projectRoot), branchToSafePartition(branchSlug));
 }
@@ -48,24 +111,44 @@ export function getEvidenceAttachmentPath(projectRoot: string, branchSlug: strin
   return resolved;
 }
 
+export function getLegacyArtifactsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'artifacts');
+}
+
 export function getArtifactsDir(projectRoot: string, runId: string): string {
-  return path.join(getRunDir(projectRoot, runId), 'artifacts');
+  return getLegacyArtifactsDir(projectRoot, runId);
+}
+
+export function getLegacyAgentExecutionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'agent-executions');
 }
 
 export function getAgentExecutionsDir(projectRoot: string, runId: string): string {
-  return path.join(getRunDir(projectRoot, runId), 'agent-executions');
+  return getLegacyAgentExecutionsDir(projectRoot, runId);
+}
+
+export function getLegacyTeamSessionsDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'team-sessions');
 }
 
 export function getTeamSessionsDir(projectRoot: string, runId: string): string {
-  return path.join(getRunDir(projectRoot, runId), 'team-sessions');
+  return getLegacyTeamSessionsDir(projectRoot, runId);
+}
+
+export function getLegacyWorkerRuntimesDir(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'worker-runtimes');
 }
 
 export function getWorkerRuntimesDir(projectRoot: string, runId: string): string {
-  return path.join(getRunDir(projectRoot, runId), 'worker-runtimes');
+  return getLegacyWorkerRuntimesDir(projectRoot, runId);
+}
+
+export function getLegacyInvocationLedgerPath(projectRoot: string, runId: string): string {
+  return path.join(getLegacyRunDir(projectRoot, runId), 'invocations.jsonl');
 }
 
 export function getInvocationLedgerPath(projectRoot: string, runId: string): string {
-  return path.join(getRunDir(projectRoot, runId), 'invocations.jsonl');
+  return getLegacyInvocationLedgerPath(projectRoot, runId);
 }
 
 export function getRouteCacheDir(projectRoot: string): string {
@@ -77,23 +160,35 @@ export function getRouteCachePath(projectRoot: string, key: string): string {
   return path.join(getRouteCacheDir(projectRoot), `${key}.json`);
 }
 
-export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+export function getLegacyWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
   assertSafePathSegment(runtimeId, 'runtimeId');
-  return path.join(getWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
+  return path.join(getLegacyWorkerRuntimesDir(projectRoot, runId), `${runtimeId}.json`);
 }
 
-export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+export function getWorkerRuntimeRecordPath(projectRoot: string, runId: string, runtimeId: string): string {
+  return getLegacyWorkerRuntimeRecordPath(projectRoot, runId, runtimeId);
+}
+
+export function getLegacyAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
   assertSafePathSegment(executionId, 'executionId');
-  return path.join(getAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
+  return path.join(getLegacyAgentExecutionsDir(projectRoot, runId), `${executionId}.json`);
 }
 
-export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+export function getAgentExecutionRecordPath(projectRoot: string, runId: string, executionId: string): string {
+  return getLegacyAgentExecutionRecordPath(projectRoot, runId, executionId);
+}
+
+export function getLegacyTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
   assertSafePathSegment(teamId, 'teamId');
-  return path.join(getTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
+  return path.join(getLegacyTeamSessionsDir(projectRoot, runId), `${teamId}.json`);
 }
 
-export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
-  const artifactsDir = getArtifactsDir(projectRoot, runId);
+export function getTeamSessionRecordPath(projectRoot: string, runId: string, teamId: string): string {
+  return getLegacyTeamSessionRecordPath(projectRoot, runId, teamId);
+}
+
+export function getLegacyArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  const artifactsDir = getLegacyArtifactsDir(projectRoot, runId);
   const resolved = path.resolve(artifactsDir, relativeArtifactPath);
   if (!resolved.startsWith(path.resolve(artifactsDir) + path.sep) && resolved !== path.resolve(artifactsDir)) {
     throw new Error(`Artifact path escapes artifacts directory: ${relativeArtifactPath}`);
@@ -101,6 +196,10 @@ export function getArtifactPath(projectRoot: string, runId: string, relativeArti
   return resolved;
 }
 
+export function getArtifactPath(projectRoot: string, runId: string, relativeArtifactPath: string): string {
+  return getLegacyArtifactPath(projectRoot, runId, relativeArtifactPath);
+}
+
 export function getRunRelativeArtifactPath(artifactRootRelativePath: string): string {
   return `artifacts/${normalizeArtifactRootRelativePath(artifactRootRelativePath)}`;
 }
@@ -134,3 +233,21 @@ export function normalizeEvidenceRootRelativePath(value: string): string {
   }
   return normalized;
 }
+
+function assertKnownSddStage(stage: string): SddStage {
+  if (!KNOWN_SDD_STAGES.includes(stage as SddStage)) {
+    throw new Error(`Unknown SDD stage: ${stage}`);
+  }
+  return stage as SddStage;
+}
+
+function normalizeBranchStageEvidenceFileName(fileName: string): string {
+  if (path.isAbsolute(fileName) || fileName.includes('/') || fileName.includes('\\') || fileName.includes('..')) {
+    throw new Error(`Stage evidence file name must be a single safe file name: ${fileName}`);
+  }
+  const normalized = normalizePortablePath(fileName);
+  assertSafePathSegment(normalized, 'stageEvidenceFileName');
+  return normalized;
+}
+
+const KNOWN_SDD_STAGES: SddStage[] = ['spec', 'plan', 'tasks', 'verifies', 'do', 'test', 'goal-verify', 'ship'];

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

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } 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 { hashDocumentContent } from './sdd-docs/document-hashes.js';
+import {
+  RUNTIME_PROJECTION_P0_INVENTORY,
+  inspectRuntimeProjectionP0,
+  recordRuntimeRefHashRegistryProjection
+} from './runtime-projection-p0.js';
+
+const fixedTime = '2026-05-31T00:00:00.000Z';
+
+test('Phase 9.19 P0 inventory keeps mutable runtime state in SQLite primitives', () => {
+  const byKey = new Map(RUNTIME_PROJECTION_P0_INVENTORY.map((item) => [item.key, item]));
+
+  assert.equal(RUNTIME_PROJECTION_P0_INVENTORY.length, 17);
+  assert.equal(byKey.get('lifecycleDecisions')?.primitive, 'projections:phase8_lifecycle_risk_decision');
+  assert.equal(byKey.get('stageRuns')?.primitive, 'projections:phase8_stage_run');
+  assert.equal(byKey.get('stageHandoffs')?.primitive, 'projections:phase8_workflow_handoff');
+  assert.equal(byKey.get('evidenceItems')?.storage, 'sqlite-ref-hash-only');
+  assert.equal(byKey.get('evidenceSets')?.storage, 'sqlite-ref-hash-only');
+  assert.equal(byKey.get('workflowCurrentState')?.primitive, 'projections:phase9_25_workflow_current_state');
+  assert.equal(byKey.get('workflowCurrentState')?.storage, 'sqlite-projection');
+  assert.equal(byKey.get('taskOrchestration')?.primitive, 'projections:phase9_26_task_orchestration');
+  assert.equal(byKey.get('validationUnits')?.primitive, 'projections:phase9_26_validation_unit');
+  assert.equal(byKey.get('truthAlignment')?.primitive, 'projections:phase9_12_truth_alignment');
+  assert.equal(byKey.get('nextIntent')?.storage, 'sqlite-projection');
+  assert.equal(byKey.get('nextIntent')?.primitive, 'projections:phase9_29_next_intent');
+  assert.equal(RUNTIME_PROJECTION_P0_INVENTORY.every((item) => item.writer === 'runtime'), true);
+  assert.equal(RUNTIME_PROJECTION_P0_INVENTORY.every((item) => item.markdownBodyAuthority === false), true);
+});
+
+test('Phase 9.19 ref/hash registry is idempotent and reports stale refs without rewriting Markdown', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-projection-p0-'));
+  try {
+    await initProject(root);
+    const artifactRef = '.sdd/runs/master/do/implementation-v1.md';
+    const artifactPath = path.join(root, artifactRef);
+    await mkdir(path.dirname(artifactPath), { recursive: true });
+    const artifact = [
+      '---',
+      'contract: sdd-do-implementation-v1',
+      'branch: master',
+      'stage: do',
+      'kind: implementation_evidence',
+      'producer: implementer',
+      '---',
+      '',
+      'Implementation evidence.'
+    ].join('\n');
+    await writeFile(artifactPath, artifact, 'utf8');
+    const artifactHash = hashDocumentContent(artifact);
+
+    const first = await recordRuntimeRefHashRegistryProjection(root, {
+      branch: 'master',
+      refs: [{ kind: 'artifact', ref: artifactRef, hash: artifactHash }],
+      generatedAt: fixedTime
+    });
+    const second = await recordRuntimeRefHashRegistryProjection(root, {
+      branch: 'master',
+      refs: [{ kind: 'artifact', ref: artifactRef, hash: artifactHash }],
+      generatedAt: '2026-05-31T00:01:00.000Z'
+    });
+    const beforeInspectHash = hashDocumentContent(await readFile(artifactPath, 'utf8'));
+    const freshDiagnostic = await inspectRuntimeProjectionP0(root, 'master');
+    const afterInspectHash = hashDocumentContent(await readFile(artifactPath, 'utf8'));
+
+    assert.equal(first.status, 'created');
+    assert.equal(first.envelope.payload.status, 'fresh');
+    assert.equal(second.status, 'unchanged');
+    assert.equal(second.envelope.id, first.envelope.id);
+    assert.equal(freshDiagnostic.status, 'pass');
+    assert.equal(freshDiagnostic.refHashRegistry.status, 'fresh');
+    assert.equal(freshDiagnostic.refHashRegistry.envelopeStaleness, 'fresh');
+    assert.equal(beforeInspectHash, afterInspectHash);
+
+    const changedArtifact = `${artifact}\nChanged after registry.\n`;
+    await writeFile(artifactPath, changedArtifact, 'utf8');
+    const changedHashBeforeInspect = hashDocumentContent(await readFile(artifactPath, 'utf8'));
+    const staleDiagnostic = await inspectRuntimeProjectionP0(root, 'master');
+    const changedHashAfterInspect = hashDocumentContent(await readFile(artifactPath, 'utf8'));
+
+    assert.equal(staleDiagnostic.status, 'blocked');
+    assert.equal(staleDiagnostic.refHashRegistry.status, 'blocked');
+    assert.equal(staleDiagnostic.refHashRegistry.envelopeStaleness, 'stale');
+    assert.deepEqual(staleDiagnostic.refHashRegistry.staleRefs.map((ref) => ref.ref), [artifactRef]);
+    assert.match(staleDiagnostic.refHashRegistry.reasons[0], /hash is stale/);
+    assert.equal(changedHashBeforeInspect, changedHashAfterInspect);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,292 @@
+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';
+
+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'
+  | '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('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,
+  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/context.ts

@@ -39,7 +39,7 @@ export async function resolveSddContext(projectRoot: string, options: { branch?:
     return resolvedContext(projectRoot, projectConfigBranch, 'project_config', currentGitBranch);
   }
 
-  throw new Error('Cannot resolve SDD branch. Run from a Git branch, pass --branch <branch>, or set sdd.default_branch in .sdd/project.yml. /sdd:spec is the workflow partition entry.');
+  throw new Error('Cannot resolve SDD branch. Run from a Git branch, pass --branch <branch>, or set sdd.default_branch in .sdd/project.yml. The spec stage is the workflow partition entry.');
 }
 
 export async function resolveRunStateContext(projectRoot: string, state: RunState): Promise<ContextResolverContract> {