sdd-agent-platform 0.4.1 → 0.4.2

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

@@ -88,21 +88,38 @@ Use the local or globally installed \`sdd\` CLI as the source of truth for this
 
 1. Accept the user's natural-language intent, then run \`sdd status\` first and report only workflow state, blocker/current task, and the recommended next command; do not paste or restate full status unless asked.
 2. Run \`sdd instructions overview --json\` only when the next action is unclear or you need the full dynamic command contract.
-3. Dynamic routing comes from CLI/core output, not this skill text; follow the recommended next command before choosing a projected command entry (\`spec\`, \`plan\`, \`tasks\`, \`do\`, \`test\`, \`ship\`, or \`doctor\`).
+3. Dynamic routing comes from CLI/core output, not this skill text; follow the recommended next command before choosing a projected command bundle (\`spec\`, \`plan\`, \`tasks\`, \`do\`, \`test\`, \`ship\`, or \`doctor\`). The \`tasks\` bundle covers \`tasks -> verifies\`; the \`test\` bundle covers \`test -> goal-verify\`.
 4. If the intent is still ambiguous after status, ask one clarifying question before spec/plan/do/test/ship work.
 5. For risky requests that mention state-machine, concurrency, database, SQL, security, API/schema, CI/build, or external unknowns, run \`sdd lifecycle decide --from-text <text>\` before spec/plan work.
 6. If status reports workflow_status=not_started, start the spec stage for the resolved Git branch partition; do not use \`sdd init\` as the workflow branch entry.
 7. If status points to gaps, drift, or doctor/update work, handle that maintenance action before do/test/ship.
 8. If status recommends a task, run \`sdd tasks inspect <task_id>\` and use the task Boundary and Acceptance before starting \`do\`.
-9. If status recommends do or test, follow the corresponding projected command entry or its canonical CLI command instead of inferring completion from chat.
-10. If status exposes legacy sync-back or projection drift, treat \`sdd sync-back inspect|apply\` as diagnostic/recovery/replay only; do not insert it into the ordinary happy path.
-11. If the user asks to release or go online, run \`sdd ship --branch <branch> --dry-run\` for local readiness first; do not publish, push, tag, or create external release state without explicit confirmation.
+9. If status recommends do, tasks, or test, follow the corresponding projected command bundle or its canonical CLI command instead of inferring completion from chat.
+10. If status exposes projection drift, run \`sdd doctor\` and follow diagnostic/recovery guidance before resuming the ordinary happy path.
+11. If the user asks to release or go online, run \`sdd ship close --branch <branch> --json\` for local readiness first; do not publish, push, tag, or create external release state without explicit confirmation.
 
 Refresh this managed skill with \`sdd update\` when drift is reported.
 `
       },
 
       commandEntry('sdd-doctor', '.claude/commands/sdd/doctor.md', 'doctor', 'Check project config, scoped run evidence, generated AI entry drift, and use sdd doctor fast|deep|recover for explicit diagnostic scope.'),
+      {
+        id: 'sdd-update',
+        kind: 'command',
+        relativePath: '.claude/commands/sdd/update.md',
+        title: 'SDD update',
+        body: `Refresh SDD-managed AI entries and re-import declared external/user-global/project skill capability metadata through the same idempotent update path used by init bootstrap. Use this for existing initialized projects when generated entries drift or a skill import needs dedupe/refresh.
+
+Run:
+
+\`\`\`bash
+sdd update
+sdd update --import-skill <capability_id> --source project|user-global|external --source-ref <path-or-reference> --domain <domain> --stage <stage>
+\`\`\`
+
+This command is maintenance only: it updates SDD-managed projections and non-authoritative skill capability metadata in .sdd/project.yml. It does not execute imported skills, grant lifecycle authority, close gates, or publish external state.
+`
+      },
       {
         id: 'sdd-spec',
         kind: 'command',
@@ -129,125 +146,106 @@ Do not design implementation in \`spec.md\`; stop before plan work when requirem
         kind: 'command',
         relativePath: '.claude/commands/sdd/plan.md',
         title: 'SDD plan',
-        body: `Refine the existing SDD plan document as a deliverable technical solution, not a lightweight approach summary. Include based_on_spec_hash from status so later spec-stage revisions can mark this plan stale. Agent visibility: scout/planner/spec-reviewer may participate; evidence lands in plan or review artifacts.
+        body: `Refine specs/<branch>/plan.md and .sdd/runs/<branch>/plan/*.md as agent-authored plan-stage evidence. Runtime close validates refs, hashes, contracts, and handoff state into .sdd/runtime.sqlite; it must not create or modify Markdown.
 
 Run:
 
 \`\`\`bash
 sdd instructions plan --json
+sdd plan close --branch <branch> --json
 \`\`\`
 
-Then write or refine \`specs/<branch>/plan.md\` as the technical bridge from approved spec to task-ready execution. Include background, goals/non-goals, current state, target design, architecture/component impact, interaction/sequence design, state/data design, API/schema design, concurrency/transaction/consistency design, key decisions, alternatives, risk control, rollout/rollback, validation matrix, and task breakdown rationale.
+Then write or refine \`specs/<branch>/plan.md\` as the technical bridge from approved spec to task-ready execution. Have planner/reviewer/plan-manager author \`.sdd/runs/<branch>/plan/*.md\` evidence, including \`plan-collaboration-contract-vN.md\`, before close.
 
-Use PlantUML fences for diagrams when useful: component diagrams for impact surface, sequence/activity diagrams for workflows and concurrency, state diagrams for state-machine risk, and deployment/data diagrams when release or data topology matters. Apply risk-driven requirements before task writing: state-machine risk needs a state diagram; concurrency risk needs sequence/activity plus consistency design; database risk needs data/transaction/rollback design; api_schema risk needs interface/schema compatibility; security/sql risk needs explicit risk controls.
+Use PlantUML fences for diagrams when useful: component diagrams for impact surface, sequence/activity diagrams for workflows and concurrency, state diagrams for state-machine risk, and deployment/data diagrams when release or data topology matters. Stop before tasks when the technical solution is incomplete or has unresolved design gaps.
 
-Stop before creating tasks when the technical solution is incomplete or has unresolved design gaps.
-`
+Do not let runtime author, repair, normalize, or migrate Markdown.`
       },
       {
         id: 'sdd-tasks',
         kind: 'command',
         relativePath: '.claude/commands/sdd/tasks.md',
         title: 'SDD tasks',
-        body: `Refine the existing SDD tasks stage outputs as executable task and verification contracts, not a plain TODO list or project-management backlog. Include based_on_plan_hash from status so later plan/spec revisions can mark these contracts stale. Agent visibility: task-planner writes tasks.md; task-quality, dependency/parallelization, validation-strategy, verification-designer, and verification-reviewer roles may participate before contracts freeze.
+        body: `Use this generated command as the user-visible bundle for the \`tasks -> verifies\` runtime stages. First refine specs/<branch>/tasks.md and .sdd/runs/<branch>/tasks/*.md as agent-authored tasks-stage evidence, then continue to verifies through this bundle only after runtime/status targets that internal stage.
 
 Run:
 
 \`\`\`bash
+sdd status
 sdd instructions tasks --json
 sdd tasks format
+sdd tasks close --branch <branch> --json
+sdd tasks close --branch <branch> --target verifies --json
 \`\`\`
 
-Then write or refine \`specs/<branch>/tasks.md\` from the approved spec and plan, and ensure \`specs/<branch>/verify.md\` is created or refreshed by the verification-designer after the task contract is stable. Include Delivery Map, implementation waves, validation batches/waves, review gate declarations, task blocks with acceptance_refs and plan_refs, affected_files, change_surface, implementation_wave, validation_batch, validation_timing, requires_verify_before_next, validation, risk, agent_fit, allowed_agents, required_artifacts, verification_availability, autonomy, plus companion sections for Boundary, Acceptance, Definition of Done, Evidence Expectations, and Implementation Notes.
+Workflow:
 
-Keep metadata inside the \`\`\`sdd-task fenced block and companion sections outside it. Use \`validation_timing: task_end\` and \`requires_verify_before_next: true\` for strict/high-risk tasks; use \`batch_end\` or \`wave_end\` with \`validation_batch\` only when sequential accumulation is safe. Frontend-only tasks must not declare Maven/Gradle backend build validation. Stop before \`sdd do task\` when task boundary, acceptance refs, plan refs, evidence requirements, validation batches/waves, or verify contract expectations are unclear.
-`
+1. Write or refine \`specs/<branch>/tasks.md\` from the approved spec and plan. Include Delivery Map, implementation waves, validation batches/waves, review gate declarations, task blocks with acceptance_refs and plan_refs, affected_files, change_surface, implementation_wave, validation_batch, validation_timing, requires_verify_before_next, validation, risk, agent_fit, allowed_agents, required_artifacts, verification_availability, autonomy, plus companion sections for Boundary, Acceptance, Definition of Done, Evidence Expectations, and Implementation Notes.
+2. Have task-planner/reviewer/tasks-manager author \`.sdd/runs/<branch>/tasks/*.md\` evidence, including \`tasks-collaboration-contract-vN.md\`, before \`sdd tasks close\`. Keep metadata inside the \`\`\`sdd-task fenced block and companion sections outside it.
+3. Run \`sdd tasks close --branch <branch> --json\`; runtime validates refs/frontmatter/hashes/contracts and writes only SQLite.
+4. If the fresh runtime handoff targets \`verifies\` inside this same bundle, have verification-designer/reviewer/verifies-manager author \`specs/<branch>/verify.md\` plus \`.sdd/runs/<branch>/verifies/*.md\` evidence, including \`verifies-collaboration-contract-vN.md\`.
+5. Run \`sdd tasks close --branch <branch> --target verifies --json\`; runtime validates verifies-stage refs/contracts and returns the next legal route.
+
+Do not implement code, run validation commands, silently advance to do, or let runtime author Markdown.`
       },
       {
         id: 'sdd-test',
         kind: 'command',
         relativePath: '.claude/commands/sdd/test.md',
         title: 'SDD test',
-        body: `Execute validation from the frozen tasks.md + verify.md contract, capture command output, evaluate acceptance evidence coverage, and return one unified test or validation-wave judgment.
+        body: `Use this generated command as the user-visible bundle for the \`test -> goal-verify\` runtime stages. Bind validation intent to an accepted verify.md validation unit, execute that unit, keep command summaries in runtime read models, have test-stage agents author .sdd/runs/<branch>/test/*.md evidence, then continue to goal verification through this bundle only after runtime/status targets that internal stage.
 
 Run:
 
 \`\`\`bash
 sdd status
 sdd instructions test --json
-# sdd test consumes the current verify.md contract and blocks if it is missing or stale; do not generate verify.md here.
-sdd test task <task_id> --branch <branch>
-sdd test batch <batch_id> --branch <branch>
-sdd test wave --branch <branch> --wave <n>
+sdd test <validation_unit_id-or-validation_text> --branch <branch>
+sdd test close --branch <branch> --json
+sdd test close --branch <branch> --target goal-verify --json
 \`\`\`
 
 Workflow:
 
-1. Confirm \`verify.md\` exists and is current for the selected branch; if it is missing or stale, return to \`/sdd:tasks\` or use explicit \`sdd verifies write\` recovery before testing.
-2. Use \`sdd test task <task_id>\` for strict or task_end tasks, or for deliberate narrowed overrides with \`--command\`, \`--run\`, \`--command-json\`, \`--command-file\`, or passthrough argv.
-3. For batch_end or wave_end tasks, use the verify-declared \`sdd test batch <batch_id>\` or \`sdd test wave\` boundary so accumulated implementation evidence is judged together; default \`sdd test task\` routes batch_end tasks to their batch and wave_end tasks to their wave boundary.
-4. Treat generated command logs, test index, validator artifact, acceptance maps, and workflow gate decisions as runtime evidence references, not as workflow documents.
-5. If validation returns PASS, proceed to a decision card if policy requires one, otherwise run \`sdd ship --branch <branch> --dry-run\`; if it returns FAIL or BLOCKED, fix the reported command or evidence gaps and rerun the same test boundary.
+1. Confirm accepted \`verify.md\` exists for the selected branch; if missing or stale, return to verifies through the tasks bundle.
+2. Use \`sdd test <validation_unit_id-or-validation_text> --branch <branch>\` as the normal entry; task id, validation batch id, and accepted task title/text are equivalent only when they bind to one verify.md validation unit.
+3. Use \`sdd test task|batch|wave\` only for explicit low-level diagnostics, replay, or narrowed override flags such as \`--command\`, \`--run\`, \`--command-json\`, \`--command-file\`, or passthrough argv.
+4. Have test-runner/reviewer/test-manager author \`.sdd/runs/<branch>/test/*.md\` evidence, including \`test-collaboration-contract-vN.md\`; PASS command output should not create log artifacts unless the validation contract explicitly needs stdout/stderr as primary evidence.
+5. Run \`sdd test close --branch <branch> --json\`; runtime validates refs/frontmatter/hashes/contracts and writes only SQLite.
+6. If the fresh runtime handoff targets \`goal-verify\` inside this same bundle, have goal-verifier/reviewer author \`.sdd/runs/<branch>/goal-verify/*.md\` evidence, then run \`sdd test close --branch <branch> --target goal-verify --json\` so runtime records truthAlignment before ship readiness.
 
-Do not auto-fix failures, author or refresh \`verify.md\`, mutate \`tasks.md\`, apply sync-back, commit, publish, or treat command success alone as semantic PASS.
-`
+Do not auto-fix failures, author or refresh \`verify.md\`, mutate \`tasks.md\`, commit, publish, or treat command success alone as semantic PASS.`
       },
       {
         id: 'sdd-do',
         kind: 'command',
         relativePath: '.claude/commands/sdd/do.md',
         title: 'SDD do',
-        body: `Execute one approved SDD task boundary through the ingestion-aware task workflow.
+        body: `Semantically bind /sdd:do or sdd do task input to one accepted task boundary, then run do-stage collaboration: implementer/reviewer/do-manager write .sdd/runs/<branch>/do/*.md evidence and runtime reconciles gate truth into SQLite.
 
 Run:
 
 \`\`\`bash
 sdd status
 sdd instructions do --json
-sdd tasks inspect <task_id>
+sdd tasks inspect <bound_task_id>
 \`\`\`
 
 Workflow:
 
-Agent evidence flow: scout gathers bounded context only; implementer edits only inside the selected task boundary; reviewer records review evidence; debugger is optional after review failure; validator records validation and acceptance mapping. Artifact flags use run-relative paths such as \`artifacts/implement-<task_id>.md\`, \`artifacts/review-<task_id>.md\`, and \`artifacts/validation-<task_id>.md\`; physical files live under branch evidence \`.sdd/runs/<branchSlug>/evidence/artifacts/\`. This command entry does not authorize autonomous background execution.
+Use CLI/core output as the source of truth. Task id and accepted task title/text are equivalent when they bind to the same accepted task boundary. Agent evidence flow: implementer edits only inside the bound task boundary and writes \`.sdd/runs/<branch>/do/implementation-vN.md\`; code-reviewer writes \`.sdd/runs/<branch>/do/code-review-vN.md\`; do-manager writes \`.sdd/runs/<branch>/do/do-manager-vN.md\` as a closure request. Runtime reads these Markdown refs/hashes/frontmatter, validates the gate, and writes only SQLite projections/run state. This command entry does not authorize autonomous background execution.
 
 
-1. Resolve exactly one task id from the user request or from the \`sdd status\` recommended next command. Stop and ask if it is ambiguous.
-2. Read \`sdd tasks inspect <task_id>\` and restate the task Boundary, Acceptance, gaps, and validation commands.
+1. Run \`sdd status\`, then let CLI/core bind the user request or recommended next command to exactly one accepted task boundary. Stop if binding is ambiguous, missing, stale, or boundary-expanding.
+2. Run \`sdd instructions do --json\` and \`sdd tasks inspect <bound_task_id>\`; restate only the bound task Boundary, blocking gaps, and validation commands.
 3. Work only inside the selected task boundary; do not expand scope without a checkpoint.
-4. Before creating explicit result artifacts, create the task run first, then write templates through the CLI writer: \`sdd artifact template artifacts/implement-<task_id>.md --task <task_id> --agent implementer --run <run_id> --write\`, \`sdd artifact template artifacts/review-<task_id>.md --task <task_id> --agent reviewer --run <run_id> --write\`, and \`sdd artifact template artifacts/validation-<task_id>.md --task <task_id> --agent validator --run <run_id> --write\`; do not manually create copies under \`specs/<branch>/artifacts/\` or \`specs/<branch>/evidence/artifacts/\`. Pass the run-relative \`artifacts/<file>\` path to CLI flags, and keep source/test files in \`## Evidence\`, not in \`sdd-result.artifacts\`.
-5. Run \`sdd artifact validate <run_id> <artifact> --task <task_id> --agent <agent>\` before passing artifacts into \`sdd do task <task_id>\`.
-6. Run \`sdd do task <task_id>\` with explicit artifact paths when evidence is available; this path records Phase 3 artifact ingestion evidence for doctor.
-7. Report the run id, status, agent evidence artifacts, gaps, and next gate. If completed, follow the \`sdd status\` recommended next command: continue sequential \`sdd do task\` when safe, run \`sdd test task\` for strict/task_end work, or run \`sdd test batch\` / \`sdd test wave\` at the declared validation boundary.
+4. Implement within affected_files and capture changed file refs/hashes in \`.sdd/runs/<branch>/do/implementation-vN.md\` frontmatter.
+5. Have code-reviewer write \`.sdd/runs/<branch>/do/code-review-vN.md\` against the implementation evidence hash, whether approved or blocked.
+6. Have do-manager write \`.sdd/runs/<branch>/do/do-manager-vN.md\` as a closure request that references the reviewed implementation and review hash.
+7. Run \`sdd do task <task_id-or-task-text> --branch <branch>\`; runtime must read \`.sdd/runs/<branch>/do/*.md\`, validate frontmatter/hash/review/manager closure, and write only SQLite projections/run state.
+8. Report the run id, status, binding target, blocking gaps, accepted evidence refs, and next gate. If completed, proceed to \`sdd test <validation_unit_id-or-validation_text> --branch <branch>\` for verification.
 
-Do not create worktrees, auto commit, or mark missing evidence as PASS.
-`
-      },
-      {
-        id: 'sdd-sync-back',
-        kind: 'command',
-        relativePath: '.claude/commands/sdd/sync-back.md',
-        title: 'SDD sync-back',
-        body: `Inspect or replay legacy task completion write-back state for diagnostic, recovery, or compatibility use. Sync-back is a low-level projection repair command, not an ordinary happy-path workflow stage.
-
-Run:
-
-\`\`\`bash
-sdd status
-sdd instructions sync-back --json
-sdd sync-back inspect --branch <branch> --task <task_id>
-\`\`\`
-
-Diagnostic workflow:
-
-1. Resolve exactly one task id and workflow partition from an explicit recovery request, old run replay, CI inspection, or doctor/status diagnostic. Stop and ask if either is ambiguous.
-2. Run \`sdd sync-back inspect --branch <branch> --task <task_id>\` before any apply; pass \`<run_id>\` only for replay, CI, or old-run inspection.
-3. Report what apply would write: target tasks file, task id, markdown status transition, proposal path, evidence artifacts, apply_policy, and policy reasons.
-4. If inspect reports \`status=ready\` and \`apply_policy=direct\`, run \`sdd sync-back apply --branch <branch> --task <task_id>\` only for explicit recovery/replay.
-5. If inspect reports approval_required=true, ask for explicit human confirmation and only then run \`sdd sync-back apply --branch <branch> --task <task_id> --approved\`.
-6. Explain that default apply writes only tasks.md for the target task, appends the sync-back implementation note, marks run sync_back applied, and rebuilds the local run index; \`--refresh-verify\` is an explicit recovery option after reviewed task-contract changes.
-
-Do not apply without inspect, do not use \`--approved\` without human confirmation, do not change source files during sync-back, and do not recommend sync-back after normal \`/sdd:test\` PASS.
+Do not create worktrees, auto commit, mark missing evidence as PASS, or let runtime author Markdown artifacts.
 `
       },
       {
@@ -255,26 +253,26 @@ Do not apply without inspect, do not use \`--approved\` without human confirmati
         kind: 'command',
         relativePath: '.claude/commands/sdd/ship.md',
         title: 'SDD ship',
-        body: `Run local release-readiness checks and optionally write \`specs/<branch>/release.md\`. This command is a preflight/release-summary gate; it does not authorize npm publish, git push, git tag, deploy, or external release creation.
+        body: `Close ship readiness through agent-authored .sdd/runs/<branch>/ship/*.md evidence. Optional specs/<branch>/release.md is ship-agent authored, not runtime-authored.
 
 Run:
 
 \`\`\`bash
-sdd ship --branch <branch> --dry-run
+sdd status
 sdd instructions ship --json
+sdd ship close --branch <branch> --json
 \`\`\`
 
 Workflow:
 
 1. Resolve the target branch/partition from \`sdd status\` or the user's explicit branch.
-2. Run \`sdd ship --branch <branch> --dry-run\` first; inspect PASS/BLOCKED readiness and next actions without writing \`release.md\`.
-3. If the readiness output is acceptable, run \`sdd ship --branch <branch>\` to write \`specs/<branch>/release.md\`.
-4. Use \`sdd statusline --branch <branch>\` for compact runtime/test/team/token/evidence health when reporting progress.
+2. Confirm goal-verify has recorded aligned truthAlignment or validated reconciliation truth.
+3. Have ship-manager/release agent author \`.sdd/runs/<branch>/ship/*.md\` evidence, including \`ship-collaboration-contract-vN.md\`; write \`specs/<branch>/release.md\` only as an explicit ship-agent artifact if needed.
+4. Run \`sdd ship close --branch <branch> --json\`; runtime validates readiness refs/contracts/truthAlignment and writes only \`.sdd/runtime.sqlite\`.
 5. Run generated-entry drift, current-run health, typecheck, test, build, and package dry-run gates when preparing a real package release.
 6. Stop before publish, push, tag, deploy, or external release creation unless the user explicitly approves that separate action.
 
-Do not skip failed gates, do not treat historical doctor debt as a release blocker unless it affects current evidence, and do not mutate external release state from this preflight command.
-`
+Do not skip failed gates, do not treat historical doctor debt as a release blocker unless it affects current evidence, and do not let runtime author release Markdown.`
       }
     ];
   }

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

@@ -54,6 +54,7 @@ artifacts:
     assert.equal(first.record.delegationStatus, 'COMPLETED');
     assert.equal(second.valid, true);
     assert.equal(second.duplicate, true);
+    assert.equal(second.record.contentDigest, first.record.contentDigest);
     assert.equal(nextState.delegations[delegation.delegationId].status, 'COMPLETED');
     assert.equal(nextState.artifacts.filter((artifact) => artifact.path === 'artifacts/review-T1.md').length, 1);
     assert.equal(inspection.valid, true);
@@ -65,6 +66,43 @@ artifacts:
   }
 });
 
+test('ingestArtifactResult allocates a retry attempt for changed terminal artifact content', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-artifact-ingest-retry-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'run-1' });
+    const delegation = createDelegationRecord({
+      delegationId: 'B-T1-reviewer-001',
+      task: 'T1',
+      agent: 'reviewer',
+      expectedArtifact: 'artifacts/review-T1.md',
+      runMode: 'background'
+    });
+    await writeRunState(root, { ...state, delegations: { [delegation.delegationId]: delegation } });
+    await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+
+    const first = await ingestArtifactResult(root, state.runId, { delegationId: delegation.delegationId, artifactPath: 'artifacts/review-T1.md' });
+    await writeArtifact(root, state.runId, 'review-T1.md', `${validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md')}\nChanged evidence.\n`);
+    const retry = await ingestArtifactResult(root, state.runId, { delegationId: delegation.delegationId, artifactPath: 'artifacts/review-T1.md' });
+    const nextState = await readRunState(root, state.runId);
+    const inspection = await inspectArtifactResultIngestions(root, state.runId);
+
+    assert.equal(first.valid, true);
+    assert.equal(retry.valid, true);
+    assert.equal(retry.duplicate, false);
+    assert.equal(retry.record.delegationId, 'B-T1-reviewer-002');
+    assert.equal(retry.record.retryOf, 'B-T1-reviewer-001');
+    assert.equal(retry.record.replayReason, 'artifact_reingest');
+    assert.notEqual(retry.record.contentDigest, first.record.contentDigest);
+    assert.equal(nextState.delegations['B-T1-reviewer-001'].status, 'COMPLETED');
+    assert.equal(nextState.delegations['B-T1-reviewer-002'].status, 'COMPLETED');
+    assert.equal(nextState.delegations['B-T1-reviewer-002'].retryOf, 'B-T1-reviewer-001');
+    assert.deepEqual(inspection.records.map((record) => record.delegationId), ['B-T1-reviewer-001', 'B-T1-reviewer-002']);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('ingestArtifactResult rejects invalid artifact without accepted evidence', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'sdd-artifact-ingest-invalid-'));
   try {

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

@@ -1,6 +1,9 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
 import { ARTIFACT_RESULT_INGESTION_CONTRACT_VERSION } from '../contracts.js';
-import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
-import { artifactKind } from '../run-state/artifacts.js';
+import { getBranchStageEvidencePathFromRef, isBranchStageEvidenceRef, normalizeStageEvidenceOrLegacyArtifactRef, toArtifactRootRelativePath, toEvidencePayloadFileName } from '../runtime-paths.js';
+import { artifactKind, readArtifact } from '../run-state/artifacts.js';
 import { appendEvent } from '../run-state/events.js';
 import type { RunState, RunStateArtifactIngestionRecord, RunStateContractValidationIssue, RunStateDelegationRecord, RunStateTaskGap } from '../run-state/model.js';
 import { readRunState, writeRunState } from '../run-state/run-state.js';
@@ -35,16 +38,31 @@ export interface ArtifactResultIngestionInspection {
 
 export async function ingestArtifactResult(projectRoot: string, runId: string, input: { delegationId: string; artifactPath: string }): Promise<ArtifactResultIngestionResult> {
   const state = await readRunState(projectRoot, runId);
-  const delegation = state.delegations[input.delegationId];
-  if (!delegation) {
+  const originalDelegation = state.delegations[input.delegationId];
+  if (!originalDelegation) {
     throw new Error(`Unknown delegation ${input.delegationId} in run ${runId}.`);
   }
 
-  const artifactPath = getRunRelativeArtifactPath(toArtifactRootRelativePath(input.artifactPath));
-  const key = artifactIngestionKey(input.delegationId, artifactPath);
+  const artifactPath = normalizeStageEvidenceOrLegacyArtifactRef(input.artifactPath);
+  const contentDigest = await hashArtifact(projectRoot, runId, artifactPath);
+  let delegation = originalDelegation;
+  let key = artifactIngestionKey(delegation.delegationId, artifactPath);
   const existing = (state.artifactIngestions ?? {})[key] as ArtifactResultIngestionRecord | undefined;
-  if (existing) {
+  if (existing?.status === 'accepted' && (!existing.contentDigest || existing.contentDigest === contentDigest)) {
+    return { valid: true, duplicate: true, record: existing, delegation };
+  }
+  if (existing?.status === 'accepted' && existing.contentDigest !== contentDigest) {
+    delegation = allocateRetryDelegation(state, originalDelegation, 'artifact_reingest');
+    key = artifactIngestionKey(delegation.delegationId, artifactPath);
+    const retryExisting = (state.artifactIngestions ?? {})[key] as ArtifactResultIngestionRecord | undefined;
+    if (retryExisting?.status === 'accepted' && retryExisting.contentDigest === contentDigest) {
+      return { valid: true, duplicate: true, record: retryExisting, delegation };
+    }
+  } else if (existing) {
     return { valid: existing.status === 'accepted', duplicate: true, record: existing, delegation };
+  } else if (isDelegationTerminal(delegation.status)) {
+    delegation = allocateRetryDelegation(state, originalDelegation, 'artifact_reingest');
+    key = artifactIngestionKey(delegation.delegationId, artifactPath);
   }
 
   const report = await validateSddResultArtifact(projectRoot, runId, artifactPath, { expectedTask: delegation.task, expectedAgent: delegation.agent });
@@ -72,7 +90,10 @@ export async function ingestArtifactResult(projectRoot: string, runId: string, i
     delegationStatus: accepted ? targetStatus : (report.valid ? null : 'RECOVERABLE'),
     ingestedAt: now,
     issues,
-    gaps: accepted ? gaps : []
+    gaps: accepted ? gaps : [],
+    contentDigest,
+    retryOf: delegation.retryOf ?? null,
+    replayReason: delegation.replayReason ?? null
   };
 
   const nextDelegation = accepted
@@ -176,6 +197,41 @@ async function recordRuntimeEvidenceAdmission(projectRoot: string, state: RunSta
   });
 }
 
+async function hashArtifact(projectRoot: string, runId: string, evidenceRef: string): Promise<string> {
+  if (isBranchStageEvidenceRef(evidenceRef)) {
+    try {
+      return createHash('sha256').update(await readFile(getBranchStageEvidencePathFromRef(projectRoot, evidenceRef), 'utf8'), 'utf8').digest('hex');
+    } catch {
+      return createHash('sha256').update(await readArtifact(projectRoot, runId, toEvidencePayloadFileName(evidenceRef)), 'utf8').digest('hex');
+    }
+  }
+  return createHash('sha256').update(await readArtifact(projectRoot, runId, toArtifactRootRelativePath(evidenceRef)), 'utf8').digest('hex');
+}
+
+function allocateRetryDelegation(state: RunState, delegation: RunStateDelegationRecord, replayReason: NonNullable<RunStateDelegationRecord['replayReason']>): RunStateDelegationRecord {
+  const attempt = nextDelegationAttempt(state, delegation.task, delegation.agent);
+  return {
+    ...delegation,
+    delegationId: `B-${delegation.task}-${delegation.agent}-${String(attempt).padStart(3, '0')}`,
+    status: 'RUNNING',
+    startedAt: new Date().toISOString(),
+    lastHeartbeatAt: null,
+    terminalEventAt: null,
+    attempt,
+    retryOf: delegation.delegationId,
+    replayReason
+  };
+}
+
+function nextDelegationAttempt(state: RunState, taskId: string, agent: string): number {
+  const prefix = `B-${taskId}-${agent}-`;
+  const attempts = Object.keys(state.delegations)
+    .filter((delegationId) => delegationId.startsWith(prefix))
+    .map((delegationId) => Number.parseInt(delegationId.slice(prefix.length), 10))
+    .filter(Number.isFinite);
+  return Math.max(1, ...attempts) + 1;
+}
+
 function artifactIngestionKey(delegationId: string, artifactPath: string): string {
   return `${delegationId}:${artifactPath}`;
 }
@@ -214,7 +270,7 @@ function artifactIngestionGaps(delegation: RunStateDelegationRecord, status: Sdd
   if (status === 'PASS') {
     return [];
   }
-  return [taskGap(delegation.task, delegation.agent, `Artifact ingestion returned ${status} for ${delegation.delegationId}.`, 'Inspect the ingested artifact evidence before test or sync-back apply.')];
+  return [taskGap(delegation.task, delegation.agent, `Artifact ingestion returned ${status} for ${delegation.delegationId}.`, 'Inspect the ingested artifact evidence before continuing stage closure.')];
 }
 
 function contractIssue(field: string, message: string, recommendation: string): RunStateContractValidationIssue {

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

@@ -214,7 +214,6 @@ export function containsTemplatePlaceholder(value: string): boolean {
 export function isDerivedEvidenceRef(value: string): boolean {
   const normalized = normalizePortablePath(value).toLowerCase();
   return normalized.includes('acceptance-coverage-')
-    || normalized.endsWith('sync-back-proposal.md')
     || normalized.includes('/cache/')
     || normalized.includes('/profile')
     || normalized.endsWith('run-index.json')

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

@@ -48,8 +48,8 @@ test('validateSddResultArtifact catches missing, empty, and task mismatch artifa
     const state = await createRun(root, { runId: 'run-1' });
     const missing = await validateSddResultArtifact(root, state.runId, 'artifacts/missing.md', { expectedTask: 'T1', expectedAgent: 'reviewer' });
     assert.equal(missing.valid, false);
-    assert.equal(missing.issues.some((issue) => issue.field === 'artifacts' && /Cannot read artifact/.test(issue.message)), true);
-    assert.equal(missing.issues.some((issue) => /branch evidence/.test(issue.recommendation)), true);
+    assert.equal(missing.issues.some((issue) => issue.field === 'artifacts' && /Cannot read evidence/.test(issue.message)), true);
+    assert.equal(missing.issues.some((issue) => /stage evidence/.test(issue.recommendation)), true);
 
     await writeArtifact(root, state.runId, 'empty.md', '');
     const empty = await validateSddResultArtifact(root, state.runId, 'artifacts/empty.md');

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

@@ -1,6 +1,7 @@
+import { readFile } from 'node:fs/promises';
 import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
 import { readArtifact } from '../run-state/artifacts.js';
-import { toArtifactRootRelativePath } from '../runtime-paths.js';
+import { getBranchStageEvidencePathFromRef, isBranchStageEvidenceRef, normalizeStageEvidenceOrLegacyArtifactRef, toEvidencePayloadFileName } from '../runtime-paths.js';
 import { validateArtifactTrust } from './sdd-evidence.js';
 import type { ArtifactTrustValidationReport, ContractValidationIssue } from './sdd-evidence.js';
 
@@ -25,29 +26,29 @@ export interface SddResultValidationReport {
 
 export async function validateSddResultArtifact(projectRoot: string, runId: string, runRelativeArtifactPath: string, options: { expectedTask?: string; expectedAgent?: string } = {}): Promise<SddResultValidationReport> {
   const issues: ContractValidationIssue[] = [];
-  let artifactRootRelativePath: string;
+  let evidenceRef: string;
   try {
-    artifactRootRelativePath = toArtifactRootRelativePath(runRelativeArtifactPath);
+    evidenceRef = normalizeStageEvidenceOrLegacyArtifactRef(runRelativeArtifactPath);
   } catch (error) {
-    return { valid: false, result: null, issues: [contractIssue('artifacts', messageFromError(error), 'Use a run-relative artifacts/<file> path; the physical file lives under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/<file>. Source/test files belong in ## Evidence, not in sdd-result.artifacts.')] };
+    return { valid: false, result: null, issues: [contractIssue('artifacts', messageFromError(error), 'Use a repo-relative stage evidence ref under .sdd/runs/<branch>/<stage>/*.md. Source/test files belong in ## Evidence, not in sdd-result.artifacts.')] };
   }
 
   let raw: string;
   try {
-    raw = await readArtifact(projectRoot, runId, artifactRootRelativePath);
+    raw = await readSddResultEvidence(projectRoot, runId, evidenceRef);
   } catch (error) {
-    return { valid: false, result: null, issues: [contractIssue('artifacts', `Cannot read artifact ${runRelativeArtifactPath}: ${messageFromError(error)}`, `Create the expected artifact in branch evidence and pass the run-relative path ${runRelativeArtifactPath}.`)] };
+    return { valid: false, result: null, issues: [contractIssue('artifacts', `Cannot read evidence ${evidenceRef}: ${messageFromError(error)}`, `Create the expected stage evidence and pass ${evidenceRef}.`)] };
   }
 
   if (raw.trim().length === 0) {
-    issues.push(contractIssue('artifacts', `Artifact ${runRelativeArtifactPath} is empty.`, 'Write non-empty evidence and an sdd-result block.'));
+    issues.push(contractIssue('artifacts', `Evidence ${evidenceRef} is empty.`, 'Write non-empty evidence and an sdd-result block.'));
   }
   const parsed = parseSddResultMarkdown(raw);
   issues.push(...parsed.issues);
   let trust: ArtifactTrustValidationReport | undefined;
   if (parsed.result) {
-    issues.push(...validateSddResult(parsed.result, { ...options, runRelativeArtifactPath }));
-    trust = validateArtifactTrust(raw, parsed.result, runRelativeArtifactPath, options);
+    issues.push(...validateSddResult(parsed.result, { ...options, runRelativeArtifactPath: evidenceRef }));
+    trust = validateArtifactTrust(raw, parsed.result, evidenceRef, options);
     if (!trust.valid) {
       issues.push(...trust.issues);
     }
@@ -135,22 +136,30 @@ function validateSddResultMetadata(metadata: Record<string, string | string[]>):
     issues.push(contractIssue('status', `Unsupported sdd-result status ${status ?? 'missing'}.`, 'Use PASS, PASS_WITH_GAPS, FAIL, BLOCKED, TIMED_OUT, or CANCELLED.'));
   }
   if (artifacts.length === 0) {
-    issues.push(contractIssue('artifacts', 'sdd-result artifacts must contain at least one path.', 'Add the current run-relative artifact path, for example artifacts/<file>. Source/test files belong in ## Evidence.'));
+    issues.push(contractIssue('artifacts', 'sdd-result artifacts must contain at least one evidence ref.', 'Add the current stage evidence ref, for example .sdd/runs/<branch>/<stage>/<file>.md. Source/test files belong in ## Evidence.'));
   }
   for (const artifactPath of artifacts) {
-    validateRunRelativeArtifactReference(artifactPath, issues);
-    if (!artifactPath.replace(/\\/g, '/').startsWith('artifacts/')) {
-      issues.push(contractIssue('artifacts', `Source/test path ${artifactPath} is not a run artifact reference.`, 'Move source/test file citations to ## Evidence; keep only run-relative artifacts/<file> paths in sdd-result.artifacts.'));
-    }
+    validateSddResultEvidenceReference(artifactPath, issues);
   }
   return issues;
 }
 
-function validateRunRelativeArtifactReference(value: string, issues: ContractValidationIssue[], field = 'artifacts'): void {
+async function readSddResultEvidence(projectRoot: string, runId: string, evidenceRef: string): Promise<string> {
+  if (isBranchStageEvidenceRef(evidenceRef)) {
+    try {
+      return await readFile(getBranchStageEvidencePathFromRef(projectRoot, evidenceRef), 'utf8');
+    } catch {
+      return readArtifact(projectRoot, runId, toEvidencePayloadFileName(evidenceRef));
+    }
+  }
+  return readArtifact(projectRoot, runId, toEvidencePayloadFileName(evidenceRef));
+}
+
+function validateSddResultEvidenceReference(value: string, issues: ContractValidationIssue[], field = 'artifacts'): void {
   try {
-    toArtifactRootRelativePath(value);
+    normalizeStageEvidenceOrLegacyArtifactRef(value);
   } catch (error) {
-    issues.push(contractIssue(field, messageFromError(error), 'Use a run-relative artifacts/<file> path inside the active run.'));
+    issues.push(contractIssue(field, messageFromError(error), 'Use a repo-relative stage evidence ref under .sdd/runs/<branch>/<stage>/*.md.'));
   }
 }