sdd-agent-platform 0.4.0 → 0.4.2

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

@@ -123,12 +123,36 @@ function validateAgentSkillTeamRuntimeInspection(inspection: AgentSkillTeamRunti
     if (!source.attribution.trim()) {
       issues.push(contractIssue(`${source.id}.attribution`, 'Capability source has no attribution.', 'Declare attribution before external material can enter the runtime registry.'));
     }
-    if (source.quarantineRequired && source.reuseDecision === 'reuse_direct') {
-      issues.push(contractIssue(`${source.id}.reuseDecision`, 'Quarantined source cannot be reused directly.', 'Use adapt_via_host_adapter or borrow_mechanism until quarantine evidence promotes the source.'));
+    if (source.permissionModel.length === 0) {
+      issues.push(contractIssue(`${source.id}.permissionModel`, 'Capability source has no permission model.', 'Declare how host/tool permissions are bounded before routing this source.'));
     }
-    if (source.quarantineRequired && sourceDeclaresUnsafeAuthority(source)) {
+    if (source.provenanceRequirements.length === 0) {
+      issues.push(contractIssue(`${source.id}.provenanceRequirements`, 'Capability source has no provenance requirements.', 'Declare source, session, artifact, or tool provenance before external output can be cited.'));
+    }
+    if (source.hostCompatibility.length === 0) {
+      issues.push(contractIssue(`${source.id}.hostCompatibility`, 'Capability source has no host compatibility declaration.', 'Declare supported, future_adapter, or unsupported host compatibility.'));
+    }
+    if (source.allowedEvidenceTypes.length === 0) {
+      issues.push(contractIssue(`${source.id}.allowedEvidenceTypes`, 'Capability source has no allowed evidence type.', 'Declare whether output is none, candidate evidence, command output, browser snapshot, design context, execution record, or external reference.'));
+    }
+    if (source.forbiddenAuthority.length === 0 || !sourceForbidsRuntimeAuthority(source)) {
+      issues.push(contractIssue(`${source.id}.forbiddenAuthority`, 'Capability source does not forbid runtime authority.', 'External sources must forbid lifecycle, completion, truth-alignment, ship, and permission authority.'));
+    }
+    if (!source.quarantineRequired && source.quarantineStatus !== 'not_required') {
+      issues.push(contractIssue(`${source.id}.quarantineStatus`, 'Non-quarantined source has a quarantine status.', 'Use not_required unless quarantine is required.'));
+    }
+    if (source.quarantineRequired && source.quarantineStatus === 'not_required') {
+      issues.push(contractIssue(`${source.id}.quarantineStatus`, 'Quarantined source is missing active quarantine status.', 'Use required, quarantined, or denied for external sources that require quarantine.'));
+    }
+    if ((source.quarantineRequired || source.quarantineStatus === 'quarantined' || source.quarantineStatus === 'denied') && source.reuseDecision === 'reuse_direct') {
+      issues.push(contractIssue(`${source.id}.reuseDecision`, 'Quarantined source cannot be reused directly.', 'Use adapt_via_host_adapter, borrow_mechanism, or avoid until quarantine evidence promotes the source.'));
+    }
+    if ((source.quarantineRequired || source.quarantineStatus === 'quarantined') && sourceDeclaresUnsafeAuthority(source)) {
       issues.push(contractIssue(`${source.id}.allowedUse`, 'Quarantined source requests prompt import, direct execution, or lifecycle authority.', 'Keep external material declarative and route only through validated profiles, capabilities, and adapter mappings.'));
     }
+    if (source.quarantineStatus === 'denied' && source.reuseDecision !== 'avoid') {
+      issues.push(contractIssue(`${source.id}.reuseDecision`, 'Denied capability source is still routable.', 'Set reuse_decision to avoid for denied or unsupported sources.'));
+    }
   }
   for (const capability of inspection.skillCapabilities) {
     const registrySource = inspectionRegistrySource(inspection, 'skill_capability', capability.id);
@@ -226,6 +250,11 @@ function sourceDeclaresUnsafeAuthority(source: CapabilitySourceCatalogEntry): bo
   return /prompt\s*(body|import)|direct\s+execution|execute\s+(third[- ]party|external)|run\s+(agent\s+)?pack|lifecycle\s+authority|completion\s+authority|unscoped\s+write|permission\s+escalation/i.test([source.allowedUse, source.rationale].join('\n'));
 }
 
+function sourceForbidsRuntimeAuthority(source: CapabilitySourceCatalogEntry): boolean {
+  const forbidden = source.forbiddenAuthority.join('\n').toLowerCase();
+  return ['lifecycle', 'stage completion', 'truth-alignment', 'ship', 'permission'].every((term) => forbidden.includes(term));
+}
+
 function builtInProfileAliasTarget(value: string): AgentProfileId | null {
   const normalized = normalizeAgentToken(value);
   if (normalized === 'scout') {

package/node_modules/@sdd-agent-platform/core/src/router/stage-route-binding.ts

@@ -0,0 +1,279 @@
+import type { RuntimeRef, SddStage } from '../contracts.js';
+import { readLifecycleRiskDecisionProjection } from '../risk/kernel.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { parseSddBranch, type SddTask, type SddTaskModel } from '../sdd-docs/task-parser.js';
+import { STAGE_ROUTE_BINDING_PRODUCER_VERSION, STAGE_ROUTE_BINDING_PROJECTION_TYPE, runtimeProjectionStableHash } from '../runtime-projection-p0.js';
+import { recordRuntimeProjectionEnvelope, type RuntimeProjectionEnvelopeWriteResult } from '../storage/runtime-store.js';
+
+export const STAGE_ROUTE_BINDING_CONTRACT_VERSION = 'sdd-stage-route-binding-v1' as const;
+
+export type StageRouteEntry = 'sdd:plan' | 'sdd:tasks' | 'sdd:do' | 'sdd:test' | 'sdd:ship';
+export type SddCommandBundle = 'plan' | 'tasks' | 'do' | 'test' | 'ship';
+export type StageRouteBindingStatus = 'bound' | 'ambiguous' | 'not_found' | 'stale_upstream' | 'boundary_expanding' | 'blocked';
+export type StageRouteTargetKind = 'task' | 'stage' | 'gate' | 'evidence_set' | 'ship_scope';
+export type StageRouteBindingNextAction = 'enter_stage' | 'run_internal_stage' | 'ask_clarification' | 'route_to_lifecycle_decision' | 'runtime_repair_required' | 'blocked';
+
+export interface StageRouteBinding {
+  contract: typeof STAGE_ROUTE_BINDING_CONTRACT_VERSION;
+  branch: string;
+  entry: StageRouteEntry;
+  bundle: SddCommandBundle;
+  targetRuntimeStage: SddStage;
+  userText: string;
+  status: StageRouteBindingStatus;
+  targetKind: StageRouteTargetKind | null;
+  targetId: string | null;
+  matchedRefs: RuntimeRef[];
+  activeLifecycleDecisionRef: string | null;
+  nextAction: StageRouteBindingNextAction;
+  reasons: string[];
+}
+
+interface TaskMatchCandidate {
+  task: SddTask;
+  score: number;
+}
+
+export async function bindStageRoute(projectRoot: string, input: { entry: StageRouteEntry; branch?: string; userText?: string }): Promise<StageRouteBinding> {
+  const context = await resolveSddContext(projectRoot, { branch: input.branch, branchSource: input.branch ? 'cli_option' : undefined });
+  const model = await parseSddBranch(projectRoot, context.partition);
+  return bindStageRouteForModel(projectRoot, {
+    branch: context.partition,
+    model,
+    entry: input.entry,
+    userText: input.userText ?? ''
+  });
+}
+
+export async function bindStageRouteForModel(projectRoot: string, input: { branch: string; model: SddTaskModel; entry: StageRouteEntry; userText?: string }): Promise<StageRouteBinding> {
+  const userText = (input.userText ?? '').trim();
+  const activeLifecycleDecisionRef = (await readLifecycleRiskDecisionProjection(projectRoot, { branch: input.branch }))?.id ?? null;
+  if (input.entry === 'sdd:do') {
+    return bindDoTask(input.branch, input.model, userText, activeLifecycleDecisionRef);
+  }
+  return bindBundleStage(input.branch, input.entry, userText, activeLifecycleDecisionRef);
+}
+
+export function stageRouteBindingScopeKey(binding: Pick<StageRouteBinding, 'branch' | 'entry' | 'userText'>): string {
+  return [binding.branch, binding.entry, runtimeProjectionStableHash(binding.userText || '<empty>').slice(0, 16)].join(':');
+}
+
+export async function recordStageRouteBindingProjection(projectRoot: string, binding: StageRouteBinding): Promise<RuntimeProjectionEnvelopeWriteResult<StageRouteBinding>> {
+  return recordRuntimeProjectionEnvelope(projectRoot, {
+    projectionType: STAGE_ROUTE_BINDING_PROJECTION_TYPE,
+    scopeKey: stageRouteBindingScopeKey(binding),
+    inputHash: runtimeProjectionStableHash(binding),
+    producer: 'phase9.18-stage-route-binding-runtime',
+    producerVersion: STAGE_ROUTE_BINDING_PRODUCER_VERSION,
+    payload: binding
+  });
+}
+
+function bindDoTask(branch: string, model: SddTaskModel, userText: string, activeLifecycleDecisionRef: string | null): StageRouteBinding {
+  const staleReason = doStageStaleReason(model);
+  if (staleReason) {
+    return binding({
+      branch,
+      entry: 'sdd:do',
+      targetRuntimeStage: 'do',
+      userText,
+      status: 'stale_upstream',
+      targetKind: 'task',
+      targetId: null,
+      matchedRefs: [],
+      activeLifecycleDecisionRef,
+      nextAction: 'runtime_repair_required',
+      reasons: [staleReason]
+    });
+  }
+
+  const matches = matchTasks(model.tasks, userText);
+  if (matches.length === 0) {
+    const looksLikeId = looksLikeTaskId(userText);
+    return binding({
+      branch,
+      entry: 'sdd:do',
+      targetRuntimeStage: 'do',
+      userText,
+      status: looksLikeId ? 'not_found' : 'boundary_expanding',
+      targetKind: 'task',
+      targetId: null,
+      matchedRefs: [],
+      activeLifecycleDecisionRef,
+      nextAction: looksLikeId ? 'ask_clarification' : 'route_to_lifecycle_decision',
+      reasons: looksLikeId
+        ? [`Task ${userText || '<empty>'} was not found in the accepted task set.`]
+        : [`No accepted task boundary matched "${userText}"; run /sdd or /sdd:spec if this is new scope, risk, or acceptance.`]
+    });
+  }
+
+  const topScore = matches[0].score;
+  const tied = matches.filter((candidate) => candidate.score === topScore);
+  if (tied.length > 1) {
+    return binding({
+      branch,
+      entry: 'sdd:do',
+      targetRuntimeStage: 'do',
+      userText,
+      status: 'ambiguous',
+      targetKind: 'task',
+      targetId: null,
+      matchedRefs: tied.map((candidate) => taskRuntimeRef(candidate.task)),
+      activeLifecycleDecisionRef,
+      nextAction: 'ask_clarification',
+      reasons: [`Ambiguous task text "${userText}" matched ${tied.map((candidate) => candidate.task.id).join(', ')}; specify a task id or more precise title.`]
+    });
+  }
+
+  const task = matches[0].task;
+  return binding({
+    branch,
+    entry: 'sdd:do',
+    targetRuntimeStage: 'do',
+    userText,
+    status: 'bound',
+    targetKind: 'task',
+    targetId: task.id,
+    matchedRefs: [taskRuntimeRef(task)],
+    activeLifecycleDecisionRef,
+    nextAction: 'enter_stage',
+    reasons: [`Bound "${userText}" to task ${task.id}.`]
+  });
+}
+
+function bindBundleStage(branch: string, entry: Exclude<StageRouteEntry, 'sdd:do'>, userText: string, activeLifecycleDecisionRef: string | null): StageRouteBinding {
+  const targetRuntimeStage = bundleTargetRuntimeStage(entry, userText);
+  return binding({
+    branch,
+    entry,
+    targetRuntimeStage,
+    userText,
+    status: 'bound',
+    targetKind: entry === 'sdd:ship' ? 'ship_scope' : 'stage',
+    targetId: targetRuntimeStage,
+    matchedRefs: [{ kind: entry === 'sdd:ship' ? 'projection' : 'command', ref: `${entry}:${targetRuntimeStage}` }],
+    activeLifecycleDecisionRef,
+    nextAction: targetRuntimeStage === bundleForEntry(entry) ? 'enter_stage' : 'run_internal_stage',
+    reasons: [`Bound ${entry} to runtime stage ${targetRuntimeStage}.`]
+  });
+}
+
+function binding(input: Omit<StageRouteBinding, 'contract' | 'bundle'>): StageRouteBinding {
+  return {
+    contract: STAGE_ROUTE_BINDING_CONTRACT_VERSION,
+    bundle: bundleForEntry(input.entry),
+    ...input
+  };
+}
+
+function bundleForEntry(entry: StageRouteEntry): SddCommandBundle {
+  if (entry === 'sdd:plan') return 'plan';
+  if (entry === 'sdd:tasks') return 'tasks';
+  if (entry === 'sdd:do') return 'do';
+  if (entry === 'sdd:test') return 'test';
+  return 'ship';
+}
+
+function bundleTargetRuntimeStage(entry: Exclude<StageRouteEntry, 'sdd:do'>, userText: string): SddStage {
+  const normalized = normalizeSearchText(userText);
+  if (entry === 'sdd:plan') return 'plan';
+  if (entry === 'sdd:tasks') return normalized.includes('verif') || normalized.includes('verify') ? 'verifies' : 'tasks';
+  if (entry === 'sdd:test') return normalized.includes('goalverify') || normalized.includes('goal') ? 'goal-verify' : 'test';
+  return 'ship';
+}
+
+function doStageStaleReason(model: SddTaskModel): string | null {
+  if (model.documents.tasksStale) {
+    return 'Tasks document is stale; return to the tasks bundle before executing do-stage binding.';
+  }
+  if (model.documents.verifyStale) {
+    return 'Verify document is stale; return to the tasks/verifies bundle before executing do-stage binding.';
+  }
+  return null;
+}
+
+function matchTasks(tasks: SddTask[], userText: string): TaskMatchCandidate[] {
+  const query = normalizeSearchText(userText);
+  if (!query) {
+    return [];
+  }
+  return tasks
+    .map((task) => ({ task, score: scoreTask(task, userText, query) }))
+    .filter((candidate) => candidate.score >= 40)
+    .sort((left, right) => right.score - left.score || left.task.id.localeCompare(right.task.id));
+}
+
+function scoreTask(task: SddTask, rawQuery: string, normalizedQuery: string): number {
+  const normalizedId = normalizeSearchText(task.id);
+  if (normalizedId === normalizedQuery) {
+    return 1000;
+  }
+  if (normalizedId.includes(normalizedQuery) && normalizedQuery.length >= 2) {
+    return 700;
+  }
+
+  let score = 0;
+  score = Math.max(score, scoreTextField(task.title ?? '', rawQuery, normalizedQuery, 600, 360, 80));
+  score = Math.max(score, scoreTextField(task.acceptance.join(' '), rawQuery, normalizedQuery, 260, 180, 35));
+  score = Math.max(score, scoreTextField(task.boundary ?? '', rawQuery, normalizedQuery, 180, 120, 24));
+  score = Math.max(score, scoreTextField(task.affectedFiles.join(' '), rawQuery, normalizedQuery, 120, 80, 12));
+  return score;
+}
+
+function scoreTextField(value: string, rawQuery: string, normalizedQuery: string, exactScore: number, containsScore: number, tokenWeight: number): number {
+  const normalizedValue = normalizeSearchText(value);
+  if (!normalizedValue) {
+    return 0;
+  }
+  if (normalizedValue === normalizedQuery) {
+    return exactScore;
+  }
+  if ((normalizedValue.includes(normalizedQuery) || normalizedQuery.includes(normalizedValue)) && Math.min(normalizedValue.length, normalizedQuery.length) >= 2) {
+    return containsScore;
+  }
+  const queryTokens = searchTokens(rawQuery);
+  const valueTokens = searchTokens(value);
+  let overlap = 0;
+  for (const token of queryTokens) {
+    if (valueTokens.has(token)) {
+      overlap += 1;
+    }
+  }
+  return overlap * tokenWeight;
+}
+
+function normalizeSearchText(value: string): string {
+  return value.toLocaleLowerCase().normalize('NFKC').replace(/[\s\p{P}\p{S}_-]+/gu, '');
+}
+
+const LOW_SIGNAL_SEARCH_TOKENS = new Set(['system', 'systems', 'feature', 'features', '功能', '系统', '模块', '服务', '任务', '实现', '完成', '边界']);
+
+function searchTokens(value: string): Set<string> {
+  const tokens = new Set<string>();
+  const normalized = value.toLocaleLowerCase().normalize('NFKC');
+  for (const match of normalized.matchAll(/[a-z0-9]+/g)) {
+    addSearchToken(tokens, match[0]);
+  }
+  for (const match of normalized.matchAll(/\p{Script=Han}+/gu)) {
+    const text = match[0];
+    addSearchToken(tokens, text);
+    for (let index = 0; index < text.length - 1; index += 1) {
+      addSearchToken(tokens, text.slice(index, index + 2));
+    }
+  }
+  return tokens;
+}
+
+function addSearchToken(tokens: Set<string>, token: string): void {
+  if (token.length >= 2 && !LOW_SIGNAL_SEARCH_TOKENS.has(token)) {
+    tokens.add(token);
+  }
+}
+
+function looksLikeTaskId(value: string): boolean {
+  return /^[a-z][a-z0-9._-]*-?\d+$/i.test(value.trim());
+}
+
+function taskRuntimeRef(task: SddTask): RuntimeRef {
+  return { kind: 'task', ref: `task:${task.id}` };
+}

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

@@ -2,3 +2,5 @@ export * from './router/agent-runtime-config.js';
 export * from './router/agent-runtime.js';
 export * from './router/route-cache.js';
 export * from './router/route-sdd-task.js';
+export * from './router/stage-route-binding.js';
+export * from './router/runtime-import.js';

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

@@ -1,16 +1,18 @@
 import { createHash } from 'node:crypto';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { getArtifactPath, getEvidenceAttachmentPath, getRunRelativeArtifactPath, normalizeArtifactRootRelativePath } from '../runtime-paths.js';
-import { readRuntimeRunState, recordRuntimeEvidenceAttachment, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
-import { exists } from '../storage/json-io.js';
+import { getBranchStageEvidencePathFromRef, getEvidenceAttachmentPath, getLegacyArtifactPath, getRunRelativeArtifactPath, getRuntimeStorePath, isBranchStageEvidenceRef, normalizeArtifactRootRelativePath, normalizeBranchStageEvidenceRef, toBranchStageEvidenceRef } from '../runtime-paths.js';
+import { readRuntimeRunState, recordRuntimeArtifactPayload, recordRuntimeEvidenceAttachment, resolveRuntimeArtifactPayload, runtimeScopedId, withRuntimeStore, type RuntimeArtifactPayloadRecord } from '../storage/runtime-store.js';
+import type { SddStage } from '../contracts.js';
 import { appendArtifactHashLedgerEntry } from './invocation-ledger.js';
 
 export async function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{ absolutePath: string; runRelativePath: string }> {
   const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
   const runRelativePath = getRunRelativeArtifactPath(normalized);
-  const branchSlug = await resolveRunBranchSlug(projectRoot, runId);
-  const absolutePath = getEvidenceAttachmentPath(projectRoot, branchSlug, runRelativePath);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const contentHash = hashDocumentContent(content);
+  const physicalPayloadPath = uniquePhysicalPayloadPath(runRelativePath, runId, contentHash);
+  const absolutePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, physicalPayloadPath);
   await mkdir(path.dirname(absolutePath), { recursive: true });
   await writeFile(absolutePath, content, 'utf8');
   await appendArtifactHashLedgerEntry(projectRoot, {
@@ -19,27 +21,177 @@ export async function writeArtifact(projectRoot: string, runId: string, artifact
     content,
     status: 'written'
   });
-  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written' });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written', taskId: runScope.taskId });
+  await recordRuntimeArtifactPayload(projectRoot, {
+    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
+    runId,
+    sourceRunId: runId,
+    branchSlug: runScope.branchSlug,
+    taskId: runScope.taskId,
+    logicalRef: runRelativePath,
+    physicalPayloadPath,
+    artifactRole: artifactKind(runRelativePath),
+    digest: contentHash,
+    status: 'active',
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, artifactPath: runRelativePath, status: 'written' }
+  });
   await recordRuntimeEvidenceAttachment(projectRoot, {
-    branchSlug,
+    branchSlug: runScope.branchSlug,
     runId,
+    taskId: runScope.taskId,
     kind: artifactKind(runRelativePath),
+    relativePath: physicalPayloadPath,
+    contentHash,
+    bytes: Buffer.byteLength(content, 'utf8'),
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, status: 'written' }
+  });
+  return { absolutePath, runRelativePath };
+}
+
+export async function recordStageEvidenceArtifact(projectRoot: string, runId: string, stageEvidenceRef: string, content: string, options: { taskId?: string | null; artifactRole?: string } = {}): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const runRelativePath = normalizeBranchStageEvidenceRef(stageEvidenceRef);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const taskId = options.taskId ?? runScope.taskId;
+  const contentHash = hashDocumentContent(content);
+  const absolutePath = getBranchStageEvidencePathFromRef(projectRoot, runRelativePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, 'utf8');
+  await appendArtifactHashLedgerEntry(projectRoot, {
+    runId,
+    taskId,
+    branch: runScope.branchSlug,
+    artifactPath: runRelativePath,
+    content,
+    status: 'written'
+  });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written', taskId });
+  await recordRuntimeArtifactPayload(projectRoot, {
+    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
+    runId,
+    sourceRunId: runId,
+    branchSlug: runScope.branchSlug,
+    taskId,
+    logicalRef: runRelativePath,
+    physicalPayloadPath: runRelativePath,
+    artifactRole: options.artifactRole ?? artifactKind(runRelativePath),
+    digest: contentHash,
+    status: 'active',
+    payload: { logicalRef: runRelativePath, physicalPayloadPath: runRelativePath, storage: 'stage-evidence', status: 'written' }
+  });
+  await recordRuntimeEvidenceAttachment(projectRoot, {
+    branchSlug: runScope.branchSlug,
+    runId,
+    taskId,
+    kind: options.artifactRole ?? artifactKind(runRelativePath),
     relativePath: runRelativePath,
-    contentHash: hashDocumentContent(content),
+    contentHash,
     bytes: Buffer.byteLength(content, 'utf8'),
-    payload: { artifactPath: runRelativePath, status: 'written' }
+    payload: { logicalRef: runRelativePath, physicalPayloadPath: runRelativePath, storage: 'stage-evidence', status: 'written' }
   });
   return { absolutePath, runRelativePath };
 }
 
+export async function recordRuntimeOnlyArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string, options: { logicalRef?: string; branch?: string | null; taskId?: string | null; artifactRole?: string } = {}): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = options.logicalRef ?? getRunRelativeArtifactPath(normalized);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const branchSlug = options.branch ?? runScope.branchSlug;
+  const taskId = options.taskId ?? runScope.taskId;
+  const contentHash = hashDocumentContent(content);
+  const physicalPayloadPath = `runtime.sqlite:${runId}:${runRelativePath}`;
+  await appendArtifactHashLedgerEntry(projectRoot, {
+    runId,
+    taskId,
+    branch: branchSlug,
+    artifactPath: runRelativePath,
+    content,
+    status: 'recorded'
+  });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'recorded', taskId });
+  await recordRuntimeArtifactPayload(projectRoot, {
+    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
+    runId,
+    sourceRunId: runId,
+    branchSlug,
+    taskId,
+    logicalRef: runRelativePath,
+    physicalPayloadPath,
+    artifactRole: options.artifactRole ?? artifactKind(runRelativePath),
+    digest: contentHash,
+    status: 'active',
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, storage: 'runtime.sqlite', content }
+  });
+  await recordRuntimeEvidenceAttachment(projectRoot, {
+    branchSlug,
+    runId,
+    taskId,
+    kind: options.artifactRole ?? artifactKind(runRelativePath),
+    relativePath: physicalPayloadPath,
+    contentHash,
+    bytes: Buffer.byteLength(content, 'utf8'),
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, storage: 'runtime.sqlite' }
+  });
+  return { absolutePath: `${getRuntimeStorePath(projectRoot)}#${runRelativePath}`, runRelativePath };
+}
+
 export async function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string> {
   const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
   const runRelativePath = getRunRelativeArtifactPath(normalized);
-  const evidencePath = getEvidenceAttachmentPath(projectRoot, await resolveRunBranchSlug(projectRoot, runId), runRelativePath);
-  if (await exists(evidencePath)) {
-    return readFile(evidencePath, 'utf8');
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const payload = await resolveRuntimeArtifactPayload(projectRoot, runId, runRelativePath)
+    ?? await resolveRuntimeArtifactPayload(projectRoot, runId, runtimeStageEvidenceRef(runScope.branchSlug, normalized));
+  const payloadContent = runtimePayloadContent(payload);
+  if (payloadContent !== null) {
+    return payloadContent;
+  }
+  if (payload) {
+    if (isBranchStageEvidenceRef(payload.physicalPayloadPath)) {
+      return readFile(getBranchStageEvidencePathFromRef(projectRoot, payload.physicalPayloadPath), 'utf8');
+    }
+    return readFile(getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, payload.physicalPayloadPath), 'utf8');
+  }
+  const stageEvidenceRef = runtimeStageEvidenceRef(runScope.branchSlug, normalized);
+  try {
+    return await readFile(getBranchStageEvidencePathFromRef(projectRoot, stageEvidenceRef), 'utf8');
+  } catch {
+    try {
+      return await readFile(getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, runRelativePath), 'utf8');
+    } catch {
+      return readFile(getLegacyArtifactPath(projectRoot, runId, normalized), 'utf8');
+    }
+  }
+}
+
+function runtimePayloadContent(payload: RuntimeArtifactPayloadRecord | null): string | null {
+  if (!payload || !payload.payload || typeof payload.payload !== 'object' || Array.isArray(payload.payload)) {
+    return null;
   }
-  return readFile(getArtifactPath(projectRoot, runId, normalized), 'utf8');
+  const content = (payload.payload as { content?: unknown }).content;
+  return typeof content === 'string' ? content : null;
+}
+
+function runtimeStageEvidenceRef(branch: string, artifactRootRelativePath: string): string {
+  const fileName = path.posix.basename(artifactRootRelativePath.replace(/\\/g, '/'));
+  return toBranchStageEvidenceRef(branch, runtimeStageForArtifact(fileName), fileName);
+}
+
+function runtimeStageForArtifact(fileName: string): SddStage {
+  if (fileName.startsWith('acceptance-coverage-')) {
+    return 'goal-verify';
+  }
+  if (fileName.startsWith('test-') || fileName.startsWith('validation-')) {
+    return 'test';
+  }
+  if (fileName.startsWith('ship-') || fileName.startsWith('release-')) {
+    return 'ship';
+  }
+  return 'do';
+}
+
+function uniquePhysicalPayloadPath(logicalRef: string, runId: string, digest: string): string {
+  const parsed = path.posix.parse(logicalRef.replace(/\\/g, '/'));
+  const suffix = `${runId}-${digest.slice(0, 12)}`;
+  return path.posix.join(parsed.dir, `${parsed.name}-${suffix}${parsed.ext}`);
 }
 
 export function artifactKind(artifactPath: string): string {
@@ -53,15 +205,15 @@ export function artifactKind(artifactPath: string): string {
   if (fileName.startsWith('debug-')) {
     return 'debug';
   }
+  if (fileName.startsWith('test-validation-')) {
+    return 'test-validation';
+  }
   if (fileName.startsWith('validation-')) {
     return 'validation';
   }
   if (fileName.startsWith('gap-report-')) {
     return 'gap-report';
   }
-  if (fileName === 'sync-back-proposal.md') {
-    return 'sync-back-proposal';
-  }
   return 'artifact';
 }
 
@@ -75,9 +227,12 @@ async function recordRuntimeArtifact(projectRoot: string, input: { runId: string
   });
 }
 
-async function resolveRunBranchSlug(projectRoot: string, runId: string): Promise<string> {
+async function resolveRunScope(projectRoot: string, runId: string): Promise<{ branchSlug: string; taskId: string | null }> {
   const state = await readRuntimeRunState(projectRoot, runId);
-  return state?.gitBranch ?? state?.partition ?? 'unscoped';
+  return {
+    branchSlug: state?.gitBranch ?? state?.partition ?? 'unscoped',
+    taskId: state?.taskId ?? state?.currentTask ?? null
+  };
 }
 
 function hashDocumentContent(raw: string): string {

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

@@ -1,7 +1,7 @@
 
 import path from 'node:path';
 import { EVENT_LOG_CONTRACT } from '../contracts.js';
-import { getRunDir } from '../runtime-paths.js';
+import { getLegacyRunDir } from '../runtime-paths.js';
 
 import { importLegacyRunEventsIfNeeded, readRuntimeRunEvents, recordRuntimeEvent } from '../storage/runtime-store.js';
 import type { RuntimeEvent } from './model.js';
@@ -21,7 +21,7 @@ export async function readRunEvents(projectRoot: string, runId: string): Promise
   if (storedEvents.length > 0) {
     return storedEvents;
   }
-  const eventPath = path.join(getRunDir(projectRoot, runId), 'events.jsonl');
+  const eventPath = path.join(getLegacyRunDir(projectRoot, runId), 'events.jsonl');
   await importLegacyRunEventsIfNeeded(projectRoot, runId, eventPath);
   return readRuntimeRunEvents(projectRoot, runId);
 }