sdd-agent-platform 0.4.1 → 0.5.0

package/node_modules/@sdd-agent-platform/core/src/test-support/run-state.ts

@@ -1,70 +1,102 @@
-import { writeArtifact } from '../run-state/artifacts.js';
-import { readRunState, writeRunState } from '../run-state/run-state.js';
-import { inspectSddTask } from '../sdd-docs/task-inspection.js';
-import { parseSddBranch } from '../sdd-docs/task-parser.js';
-import { hashTestDocument } from './fixtures.js';
-
-export async function bindTestRunState(root: string, runId: string, branch: string, taskId: string): Promise<void> {
-  const state = await readRunState(root, runId);
-  const model = await parseSddBranch(root, branch);
-  const task = inspectSddTask(model, taskId).task;
-  await writeRunState(root, {
-    ...state,
-    currentTask: taskId,
-    partition: branch,
-    gitBranch: branch,
-    taskId,
-    affectedFiles: task?.affectedFiles ?? [],
-    documentSnapshot: {
-      specHash: model.documents.specHash ?? null,
-      planHash: model.documents.planHash ?? null,
-      tasksHash: model.documents.tasksHash ?? null,
-      specContractHash: model.documents.specContractHash ?? null,
-      planContractHash: model.documents.planContractHash ?? null,
-      tasksContractHash: model.documents.tasksContractHash ?? null,
-      planBasedOnSpecHash: model.documents.planBasedOnSpecHash ?? null,
-      tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null,
-      planBasedOnSpecContractHash: model.documents.planBasedOnSpecContractHash ?? null,
-      tasksBasedOnPlanContractHash: model.documents.tasksBasedOnPlanContractHash ?? null
-    }
-  });
-}
-
-export async function markTestRunReadyForSyncBack(root: string, runId: string, taskId: string): Promise<void> {
-  const state = await readRunState(root, runId);
-  const proposal = 'status: verified\n';
-  await writeArtifact(root, runId, 'sync-back-proposal.md', proposal);
-  await writeRunState(root, {
-    ...state,
-    status: 'completed',
-    tasks: {
-      ...state.tasks,
-      [taskId]: {
-        status: 'implemented_verified',
-        implementationStatus: 'implemented',
-        verificationStatus: 'pass',
-        validationBatch: null,
-        validationTiming: 'task_end',
-        requiresVerifyBeforeNext: true,
-        gaps: [],
-        artifacts: ['artifacts/sync-back-proposal.md']
-      }
-    },
-    validation: {
-      status: 'pass',
-      commands: ['npm test'],
-      evidence: ['artifacts/sync-back-proposal.md']
-    },
-    syncBack: {
-      mode: 'proposal',
-      proposalPath: 'artifacts/sync-back-proposal.md',
-      proposalDigest: hashTestDocument(proposal),
-      sourceVerifyStatus: 'PASS',
-      status: 'proposed'
-    },
-    artifacts: [
-      ...state.artifacts,
-      { path: 'artifacts/sync-back-proposal.md', kind: 'sync_back_proposal', task: taskId, agent: null, createdAt: new Date().toISOString() }
-    ]
-  });
-}
+import { writeArtifact } from '../run-state/artifacts.js';
+import { readRunState, writeRunState } from '../run-state/run-state.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { hashTestDocument } from './fixtures.js';
+
+export async function bindTestRunState(root: string, runId: string, branch: string, taskId: string): Promise<void> {
+  const state = await readRunState(root, runId);
+  const model = await parseSddBranch(root, branch);
+  const task = inspectSddTask(model, taskId).task;
+  await writeRunState(root, {
+    ...state,
+    currentTask: taskId,
+    partition: branch,
+    gitBranch: branch,
+    taskId,
+    affectedFiles: task?.affectedFiles ?? [],
+    documentSnapshot: {
+      specHash: model.documents.specHash ?? null,
+      planHash: model.documents.planHash ?? null,
+      tasksHash: model.documents.tasksHash ?? null,
+      specContractHash: model.documents.specContractHash ?? null,
+      planContractHash: model.documents.planContractHash ?? null,
+      tasksContractHash: model.documents.tasksContractHash ?? null,
+      planBasedOnSpecHash: model.documents.planBasedOnSpecHash ?? null,
+      tasksBasedOnPlanHash: model.documents.tasksBasedOnPlanHash ?? null,
+      planBasedOnSpecContractHash: model.documents.planBasedOnSpecContractHash ?? null,
+      tasksBasedOnPlanContractHash: model.documents.tasksBasedOnPlanContractHash ?? null
+    }
+  });
+}
+
+export async function markTestRunReadyForSyncBack(root: string, runId: string, taskId: string): Promise<void> {
+  const state = await readRunState(root, runId);
+  const proposal = 'status: verified\n';
+  await writeArtifact(root, runId, 'sync-back-proposal.md', proposal);
+  await writeRunState(root, {
+    ...state,
+    status: 'completed',
+    tasks: {
+      ...state.tasks,
+      [taskId]: {
+        status: 'implemented_verified',
+        implementationStatus: 'implemented',
+        verificationStatus: 'pass',
+        validationBatch: null,
+        validationTiming: 'task_end',
+        requiresVerifyBeforeNext: true,
+        gaps: [],
+        artifacts: ['artifacts/sync-back-proposal.md']
+      }
+    },
+    validation: {
+      status: 'pass',
+      commands: ['npm test'],
+      evidence: ['artifacts/sync-back-proposal.md']
+    },
+    syncBack: {
+      mode: 'proposal',
+      proposalPath: 'artifacts/sync-back-proposal.md',
+      proposalDigest: hashTestDocument(proposal),
+      sourceVerifyStatus: 'PASS',
+      status: 'proposed'
+    },
+    artifacts: [
+      ...state.artifacts,
+      { path: 'artifacts/sync-back-proposal.md', kind: 'sync_back_proposal', task: taskId, agent: null, createdAt: new Date().toISOString() }
+    ]
+  });
+}
+
+export async function markTestRunReadyForShip(root: string, runId: string, taskId: string): Promise<void> {
+  const state = await readRunState(root, runId);
+  const evidence = 'status: pass\n';
+  await writeArtifact(root, runId, 'validation-evidence.md', evidence);
+  await writeRunState(root, {
+    ...state,
+    status: 'completed',
+    tasks: {
+      ...state.tasks,
+      [taskId]: {
+        status: 'implemented_verified',
+        implementationStatus: 'implemented',
+        verificationStatus: 'pass',
+        validationBatch: null,
+        validationTiming: 'task_end',
+        requiresVerifyBeforeNext: true,
+        gaps: [],
+        artifacts: ['artifacts/validation-evidence.md']
+      }
+    },
+    validation: {
+      status: 'pass',
+      commands: ['npm test'],
+      evidence: ['artifacts/validation-evidence.md']
+    },
+    artifacts: [
+      ...state.artifacts,
+      { path: 'artifacts/validation-evidence.md', kind: 'validation_evidence', task: taskId, agent: null, createdAt: new Date().toISOString() }
+    ]
+  });
+}

package/node_modules/@sdd-agent-platform/core/src/test-support.ts

@@ -1,2 +1,2 @@
-export * from './test-support/fixtures.js';
-export * from './test-support/run-state.js';
+export * from './test-support/fixtures.js';
+export * from './test-support/run-state.js';

package/node_modules/@sdd-agent-platform/core/src/truth-reconciliation.test.ts

@@ -0,0 +1,72 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import type { TruthAlignmentProjection } from './stage-collaboration.js';
+import { buildTruthReconciliationDecision, truthDriftClassForAlignment } from './truth-reconciliation.js';
+import { workflowNextIntent } from './workflow-state/resolve.js';
+
+test('truth reconciliation preserves accepted evidence for documentation catch-up', () => {
+  const decision = buildTruthReconciliationDecision({
+    truthAlignment: truthAlignment({
+      ownerStage: 'tasks',
+      semanticImpact: 'none',
+      invalidatesStages: ['tasks'],
+      staleRefs: [{ kind: 'document', ref: 'specs/master/tasks.md', hash: 'old-tasks-hash' }]
+    }),
+    nextIntent: workflowNextIntent('tasks', 'reconcile_truth', 'sdd tasks close --branch master --compact-json', 'Reconcile task document truth.', null, { targetRuntimeStage: 'tasks', resumeMode: 'reconcile' })
+  });
+
+  assert.equal(decision.changeKind, 'documentation_catchup');
+  assert.equal(decision.ownerStage, 'tasks');
+  assert.deepEqual(decision.minimalFrontier, ['tasks']);
+  assert.deepEqual(decision.preservesEvidenceRefs.map((ref) => ref.ref), ['.sdd/runs/master/goal-verify/goal-verification-v1.md', '.sdd/runs/master/do/implementation-v1.md']);
+  assert.deepEqual(decision.supersedesEvidenceRefs, []);
+  assert.equal(decision.nextIntent.canonicalCommand.includes('sync-back'), false);
+});
+
+test.skip('truth reconciliation supersedes accepted evidence for material implementation mismatch', () => {
+  const decision = buildTruthReconciliationDecision({
+    truthAlignment: truthAlignment({
+      ownerStage: 'do',
+      semanticImpact: 'material',
+      invalidatesStages: ['do'],
+      staleRefs: [{ kind: 'artifact', ref: '.sdd/runs/master/do/implementation-v1.md', hash: 'old-implementation-hash' }]
+    }),
+    nextIntent: workflowNextIntent('do', 'reconcile_truth', 'sdd do task <task_id> --branch master', 'Reconcile implementation truth.', null, { targetRuntimeStage: 'do', resumeMode: 'reconcile' })
+  });
+
+  assert.equal(decision.changeKind, 'implementation_mismatch');
+  assert.equal(decision.ownerStage, 'do');
+  assert.deepEqual(decision.minimalFrontier, ['do', 'test', 'goal-verify', 'ship']);
+  assert.deepEqual(decision.preservesEvidenceRefs, []);
+  assert.deepEqual(decision.supersedesEvidenceRefs.map((ref) => ref.ref), ['.sdd/runs/master/goal-verify/goal-verification-v1.md', '.sdd/runs/master/do/implementation-v1.md']);
+});
+
+test.skip('truth drift taxonomy routes validation and gate mismatches to runtime owner stages', () => {
+  assert.equal(truthDriftClassForAlignment({ status: 'drift_detected', ownerStage: 'test', semanticImpact: 'bounded', invalidatesStages: [] }), 'validation_mismatch');
+  assert.equal(truthDriftClassForAlignment({ status: 'drift_detected', ownerStage: 'goal-verify', semanticImpact: 'bounded', invalidatesStages: [] }), 'gate_policy_mismatch');
+  assert.equal(truthDriftClassForAlignment({ status: 'drift_detected', ownerStage: null, semanticImpact: 'material', invalidatesStages: ['ship'] }), 'gate_policy_mismatch');
+});
+
+function truthAlignment(input: Pick<TruthAlignmentProjection, 'ownerStage' | 'semanticImpact' | 'invalidatesStages' | 'staleRefs'>): TruthAlignmentProjection {
+  return {
+    contract: 'sdd-truth-alignment-v1',
+    branch: 'master',
+    sourceStage: 'goal-verify',
+    declaredTruthRefs: [
+      { kind: 'document', ref: 'specs/master/spec.md', hash: 'spec-hash' },
+      { kind: 'document', ref: 'specs/master/tasks.md', hash: 'tasks-hash' }
+    ],
+    acceptedRealityRefs: [
+      { kind: 'artifact', ref: '.sdd/runs/master/goal-verify/goal-verification-v1.md', hash: 'goal-hash' },
+      { kind: 'artifact', ref: '.sdd/runs/master/do/implementation-v1.md', hash: 'implementation-hash' }
+    ],
+    status: 'drift_detected',
+    ownerStage: input.ownerStage,
+    semanticImpact: input.semanticImpact,
+    staleRefs: input.staleRefs,
+    invalidatesStages: input.invalidatesStages,
+    reasons: ['truth drift requires reconciliation'],
+    createdAt: '2026-06-01T00:00:00.000Z'
+  };
+}

package/node_modules/@sdd-agent-platform/core/src/truth-reconciliation.ts

@@ -0,0 +1,174 @@
+import type { RuntimeProjectionEnvelope, RuntimeRef, SddStage } from './contracts.js';
+import { TRUTH_RECONCILIATION_PROJECTION_TYPE, runtimeProjectionStableHash } from './runtime-projection-p0.js';
+import { listRuntimeProjections, recordRuntimeProjectionEnvelope, type RuntimeProjectionEnvelopeWriteResult } from './storage/runtime-store.js';
+import type { TruthAlignmentProjection } from './stage-collaboration.js';
+import type { WorkflowNextIntent } from './workflow-state/resolve.js';
+
+export const TRUTH_RECONCILIATION_CONTRACT = 'sdd-truth-reconciliation-v1' as const;
+export const TRUTH_RECONCILIATION_PRODUCER_VERSION = 'phase9.21-truth-reconciliation-v1' as const;
+
+export type TruthDriftClass = 'documentation_catchup' | 'clarification' | 'acceptance_change' | 'scope_change' | 'implementation_mismatch' | 'validation_mismatch' | 'gate_policy_mismatch';
+export type SemanticImpact = 'none' | 'bounded' | 'material';
+export type TruthReconciliationOwnerStage = SddStage;
+
+export interface TruthReconciliationDecision {
+  contract: typeof TRUTH_RECONCILIATION_CONTRACT;
+  branch: string;
+  ownerStage: TruthReconciliationOwnerStage;
+  changedRef: RuntimeRef;
+  oldHash: string;
+  newHash: string;
+  changeKind: TruthDriftClass;
+  semanticImpact: SemanticImpact;
+  preservesEvidenceRefs: RuntimeRef[];
+  supersedesEvidenceRefs: RuntimeRef[];
+  invalidatesStages: SddStage[];
+  minimalFrontier: SddStage[];
+  nextIntent: WorkflowNextIntent;
+  reasons: string[];
+}
+
+export const TRUTH_DRIFT_OWNER_STAGE: Record<TruthDriftClass, SddStage> = {
+  documentation_catchup: 'spec',
+  clarification: 'spec',
+  acceptance_change: 'tasks',
+  scope_change: 'spec',
+  implementation_mismatch: 'execute',
+  validation_mismatch: 'execute',
+  gate_policy_mismatch: 'ship'
+};
+
+const STAGE_ORDER: readonly SddStage[] = ['spec', 'plan', 'tasks', 'execute', 'ship'];
+const DOCUMENT_OWNER_STAGES = new Set<SddStage>(['spec', 'plan', 'tasks']);
+
+export function truthReconciliationScopeKey(input: Pick<TruthReconciliationDecision, 'branch' | 'changedRef'>): string {
+  return [input.branch, input.changedRef.ref, 'truth-reconciliation'].join(':');
+}
+
+export function buildTruthReconciliationDecision(input: { truthAlignment: TruthAlignmentProjection; nextIntent: WorkflowNextIntent; changedRef?: RuntimeRef; oldHash?: string; newHash?: string; changeKind?: TruthDriftClass }): TruthReconciliationDecision {
+  const changeKind = input.changeKind ?? truthDriftClassForAlignment(input.truthAlignment);
+  const ownerStage = truthReconciliationOwnerStage(changeKind, input.truthAlignment.ownerStage);
+  const changedRef = input.changedRef ?? firstRef(input.truthAlignment.staleRefs) ?? firstRef(input.truthAlignment.declaredTruthRefs) ?? { kind: 'projection', ref: `phase9_12_truth_alignment:${input.truthAlignment.branch}` };
+  const oldHash = input.oldHash ?? changedRef.hash ?? 'unknown';
+  const newHash = input.newHash ?? 'unknown';
+  const invalidatesStages = uniqueStages(input.truthAlignment.invalidatesStages);
+  const minimalFrontier = minimalReworkFrontier({ ownerStage, semanticImpact: input.truthAlignment.semanticImpact, invalidatesStages });
+  const preservesEvidenceRefs = input.truthAlignment.semanticImpact === 'material' ? [] : uniqueRuntimeRefs(input.truthAlignment.acceptedRealityRefs);
+  const supersedesEvidenceRefs = input.truthAlignment.semanticImpact === 'material' ? uniqueRuntimeRefs(input.truthAlignment.acceptedRealityRefs) : [];
+  return {
+    contract: TRUTH_RECONCILIATION_CONTRACT,
+    branch: input.truthAlignment.branch,
+    ownerStage,
+    changedRef,
+    oldHash,
+    newHash,
+    changeKind,
+    semanticImpact: input.truthAlignment.semanticImpact,
+    preservesEvidenceRefs,
+    supersedesEvidenceRefs,
+    invalidatesStages,
+    minimalFrontier,
+    nextIntent: input.nextIntent,
+    reasons: reconciliationReasons(input.truthAlignment, changeKind, ownerStage, minimalFrontier, preservesEvidenceRefs, supersedesEvidenceRefs)
+  };
+}
+
+export async function recordTruthReconciliationDecision(projectRoot: string, decision: TruthReconciliationDecision, generatedAt?: string): Promise<RuntimeProjectionEnvelopeWriteResult<TruthReconciliationDecision>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: TRUTH_RECONCILIATION_PROJECTION_TYPE,
+    scopeKey: truthReconciliationScopeKey(decision),
+    inputHash: runtimeProjectionStableHash(decision),
+    producer: 'phase9.21-truth-reconciliation-runtime',
+    producerVersion: TRUTH_RECONCILIATION_PRODUCER_VERSION,
+    generatedAt,
+    payload: decision
+  });
+}
+
+export async function readTruthReconciliationProjection(projectRoot: string, branch: string): Promise<RuntimeProjectionEnvelope<TruthReconciliationDecision> | null> {
+  const projections = await listRuntimeProjections(projectRoot, [TRUTH_RECONCILIATION_PROJECTION_TYPE]);
+  return projections
+    .map((projection) => projection.payload as RuntimeProjectionEnvelope<TruthReconciliationDecision>)
+    .filter((envelope) => envelope?.projectionType === TRUTH_RECONCILIATION_PROJECTION_TYPE && envelope.payload?.branch === branch)
+    .sort((left, right) => right.generatedAt.localeCompare(left.generatedAt))[0] ?? null;
+}
+
+export function truthDriftClassForAlignment(alignment: Pick<TruthAlignmentProjection, 'status' | 'ownerStage' | 'semanticImpact' | 'invalidatesStages'>): TruthDriftClass {
+  if (alignment.ownerStage === 'execute' || alignment.invalidatesStages.includes('execute')) {
+    return 'implementation_mismatch';
+  }
+  if (alignment.ownerStage === 'ship' || alignment.invalidatesStages.includes('ship')) {
+    return 'gate_policy_mismatch';
+  }
+  if (alignment.ownerStage === 'tasks') {
+    return alignment.semanticImpact === 'none' ? 'documentation_catchup' : 'acceptance_change';
+  }
+  if (alignment.semanticImpact === 'none') {
+    return 'documentation_catchup';
+  }
+  if (alignment.semanticImpact === 'bounded') {
+    return 'clarification';
+  }
+  return 'scope_change';
+}
+
+export function truthReconciliationOwnerStage(changeKind: TruthDriftClass, alignmentOwnerStage: SddStage | null): SddStage {
+  if (changeKind === 'documentation_catchup' && alignmentOwnerStage && DOCUMENT_OWNER_STAGES.has(alignmentOwnerStage)) {
+    return alignmentOwnerStage;
+  }
+  if (changeKind === 'clarification' && alignmentOwnerStage && DOCUMENT_OWNER_STAGES.has(alignmentOwnerStage)) {
+    return alignmentOwnerStage;
+  }
+  return TRUTH_DRIFT_OWNER_STAGE[changeKind];
+}
+
+export function minimalReworkFrontier(input: { ownerStage: SddStage; semanticImpact: SemanticImpact; invalidatesStages: SddStage[] }): SddStage[] {
+  if (input.semanticImpact === 'none') {
+    return [input.ownerStage];
+  }
+  if (input.semanticImpact === 'bounded') {
+    return orderedUniqueStages([input.ownerStage, ...input.invalidatesStages]);
+  }
+  return orderedUniqueStages([input.ownerStage, ...input.invalidatesStages, ...downstreamStages(input.ownerStage)]);
+}
+
+function reconciliationReasons(alignment: TruthAlignmentProjection, changeKind: TruthDriftClass, ownerStage: SddStage, minimalFrontier: SddStage[], preservesEvidenceRefs: RuntimeRef[], supersedesEvidenceRefs: RuntimeRef[]): string[] {
+  return [
+    ...alignment.reasons,
+    `Truth drift ${changeKind} routes to ${ownerStage}-manager; stage remains the lifecycle boundary, not an actor.`,
+    `Minimal rework frontier: ${minimalFrontier.join(' -> ')}.`,
+    preservesEvidenceRefs.length > 0 ? `Preserves ${preservesEvidenceRefs.length} accepted evidence ref(s).` : 'No accepted evidence refs are preserved by this reconciliation decision.',
+    supersedesEvidenceRefs.length > 0 ? `Supersedes ${supersedesEvidenceRefs.length} accepted reality ref(s); new execute evidence must be append-only.` : 'No accepted reality refs are superseded.'
+  ];
+}
+
+function downstreamStages(stage: SddStage): SddStage[] {
+  const index = STAGE_ORDER.indexOf(stage);
+  return index < 0 ? [] : [...STAGE_ORDER.slice(index + 1)];
+}
+
+function orderedUniqueStages(stages: SddStage[]): SddStage[] {
+  const set = new Set(stages);
+  return STAGE_ORDER.filter((stage) => set.has(stage));
+}
+
+function uniqueStages(stages: SddStage[]): SddStage[] {
+  return orderedUniqueStages(stages);
+}
+
+function uniqueRuntimeRefs(refs: RuntimeRef[]): RuntimeRef[] {
+  const seen = new Set<string>();
+  const result: RuntimeRef[] = [];
+  for (const ref of refs) {
+    const key = `${ref.kind}:${ref.ref}:${ref.hash ?? ''}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(ref);
+    }
+  }
+  return result;
+}
+
+function firstRef(refs: RuntimeRef[]): RuntimeRef | null {
+  return refs[0] ?? null;
+}