sdd-agent-platform 0.3.0 → 0.4.1

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

@@ -0,0 +1,302 @@
+import {
+  ACCEPTANCE_POLICY_RULESET_VERSION,
+  SDD_EVIDENCE_CONTRACT,
+  SDD_EVIDENCE_VERSION
+} from '../contracts.js';
+import { normalizePortablePath } from '../path-safety.js';
+
+export type EvidenceCoverageStatus = 'PASS' | 'FAIL' | 'BLOCKED' | 'REFERENCED_ONLY' | 'MISSING';
+export type EvidenceQualityIssue = 'EMPTY_EVIDENCE' | 'TODO_PLACEHOLDER' | 'TEMPLATE_TEXT' | 'MENTION_ONLY' | 'UNSOURCED_PASS' | 'MISSING_COMMAND_OUTPUT' | 'MISSING_ARTIFACT_REFERENCE' | 'MISSING_MATERIAL_REFERENCE' | 'PROVENANCE_GAP' | 'POLICY_RULE_FAILED' | 'DERIVED_SOURCE_EVIDENCE' | 'PARTITION_SCOPE_VIOLATION';
+
+export interface ContractValidationIssue {
+  field: string;
+  message: string;
+  recommendation: string;
+}
+
+export interface EvidenceItem {
+  kind: string;
+  ref: string;
+  summary: string | null;
+}
+
+export interface EvidenceClaim {
+  contract: typeof SDD_EVIDENCE_CONTRACT;
+  version: typeof SDD_EVIDENCE_VERSION;
+  task: string;
+  acceptance: string;
+  status: EvidenceCoverageStatus;
+  claim: string;
+  sourceArtifact: string;
+  evidence: EvidenceItem[];
+  provenance: string[];
+  policy: string[];
+  rawMetadata: Record<string, string | string[]>;
+}
+
+interface SddResult {
+  task: string;
+  agent: string;
+  status: 'PASS' | 'PASS_WITH_GAPS' | 'FAIL' | 'BLOCKED' | 'TIMED_OUT' | 'CANCELLED';
+}
+
+export interface ArtifactTrustValidationReport {
+  valid: boolean;
+  claims: EvidenceClaim[];
+  issues: ContractValidationIssue[];
+}
+
+export function parseSddEvidenceMarkdown(raw: string, options: { expectedTask?: string; sourceArtifact?: string } = {}): ArtifactTrustValidationReport {
+  const matches = Array.from(raw.matchAll(/^\s*```sdd-evidence\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
+  const claims: EvidenceClaim[] = [];
+  const issues: ContractValidationIssue[] = [];
+  for (const match of matches) {
+    const metadata = parseSimpleYamlBlock(match[1] ?? '');
+    const built = buildEvidenceClaim(metadata, options.sourceArtifact);
+    issues.push(...built.issues);
+    if (built.claim) {
+      claims.push(built.claim);
+      issues.push(...validateEvidenceClaim(built.claim, options));
+    }
+  }
+  return { valid: claims.length > 0 && issues.length === 0, claims, issues };
+}
+
+export function validateArtifactTrust(raw: string, result: SddResult, runRelativeArtifactPath: string, options: { expectedTask?: string; expectedAgent?: string } = {}): ArtifactTrustValidationReport {
+  const expectedAgent = options.expectedAgent ?? result.agent;
+  const expectedTask = options.expectedTask ?? result.task;
+  const requiresTrust = expectedAgent === 'validator' && (result.status === 'PASS' || result.status === 'PASS_WITH_GAPS');
+  const parsed = parseSddEvidenceMarkdown(raw, { expectedTask, sourceArtifact: runRelativeArtifactPath });
+  const issues = requiresTrust || parsed.claims.length > 0 ? [...parsed.issues] : [];
+
+  if (requiresTrust) {
+    issues.push(...validateArtifactBodyTrust(raw));
+    if (parsed.claims.length === 0) {
+      issues.push(evidenceIssue('UNSOURCED_PASS', 'sdd-evidence', `Validator ${result.status} artifact ${runRelativeArtifactPath} has no structured ${SDD_EVIDENCE_CONTRACT} evidence block.`, 'Add policy-backed sdd-evidence with acceptance, claim, source artifact, evidence refs, provenance refs, and policy refs.'));
+    }
+  }
+
+  return { valid: issues.length === 0 && (!requiresTrust || parsed.claims.length > 0), claims: parsed.claims, issues };
+}
+
+function buildEvidenceClaim(metadata: Record<string, string | string[]>, sourceArtifact: string | undefined): { claim: EvidenceClaim | null; issues: ContractValidationIssue[] } {
+  const issues: ContractValidationIssue[] = [];
+  const contract = scalarValue(metadata.contract);
+  const version = scalarValue(metadata.version);
+  const task = scalarValue(metadata.task);
+  const acceptance = scalarValue(metadata.acceptance);
+  const status = scalarValue(metadata.status);
+  const claimText = scalarValue(metadata.claim);
+  const claimSourceArtifact = scalarValue(metadata.source_artifact) ?? scalarValue(metadata.sourceArtifact) ?? sourceArtifact ?? null;
+  if (!contract) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.contract', 'sdd-evidence contract is missing.', `Set contract: ${SDD_EVIDENCE_CONTRACT}.`));
+  }
+  if (!version) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.version', 'sdd-evidence version is missing.', `Set version: ${SDD_EVIDENCE_VERSION}.`));
+  }
+  if (!task) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.task', 'sdd-evidence task is missing.', 'Set task to the delegated task id.'));
+  }
+  if (!acceptance) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.acceptance', 'sdd-evidence acceptance is missing.', 'Set acceptance to the AC id or acceptance text being proven.'));
+  }
+  if (!status || !isEvidenceCoverageStatus(status)) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.status', `sdd-evidence status ${status ?? 'missing'} is not supported.`, 'Use PASS, FAIL, BLOCKED, REFERENCED_ONLY, or MISSING.'));
+  }
+  if (!claimText) {
+    issues.push(evidenceIssue('UNSOURCED_PASS', 'sdd-evidence.claim', 'sdd-evidence claim is missing.', 'Add a concise claim that states what acceptance is proven.'));
+  }
+  if (!claimSourceArtifact) {
+    issues.push(evidenceIssue('MISSING_ARTIFACT_REFERENCE', 'sdd-evidence.source_artifact', 'sdd-evidence source artifact is missing.', 'Set source_artifact to the run-relative artifact path.'));
+  }
+  if (!task || !acceptance || !status || !isEvidenceCoverageStatus(status) || !claimText || !claimSourceArtifact || contract !== SDD_EVIDENCE_CONTRACT || version !== SDD_EVIDENCE_VERSION) {
+    return { claim: null, issues };
+  }
+  const evidence = listValue(metadata.evidence_refs ?? metadata.evidence_ref ?? metadata.evidence).map(parseEvidenceItem);
+  const provenance = listValue(metadata.provenance_refs ?? metadata.provenance_ref ?? metadata.provenance);
+  const policy = listValue(metadata.policy_refs ?? metadata.policy_ref ?? metadata.policy);
+  return {
+    claim: {
+      contract: SDD_EVIDENCE_CONTRACT,
+      version: SDD_EVIDENCE_VERSION,
+      task,
+      acceptance,
+      status,
+      claim: claimText,
+      sourceArtifact: claimSourceArtifact,
+      evidence,
+      provenance,
+      policy,
+      rawMetadata: metadata
+    },
+    issues
+  };
+}
+
+function validateEvidenceClaim(claim: EvidenceClaim, options: { expectedTask?: string }): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (options.expectedTask && claim.task !== options.expectedTask) {
+    issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.task', `sdd-evidence task ${claim.task} does not match expected task ${options.expectedTask}.`, 'Use the same task id as the delegated artifact.'));
+  }
+  if (containsTemplatePlaceholder(claim.claim)) {
+    issues.push(evidenceIssue('TODO_PLACEHOLDER', 'sdd-evidence.claim', 'sdd-evidence claim contains placeholder text.', 'Replace TODO/template text with actual validation evidence.'));
+  }
+  if (isDerivedEvidenceRef(claim.sourceArtifact)) {
+    issues.push(evidenceIssue('DERIVED_SOURCE_EVIDENCE', 'sdd-evidence.source_artifact', `sdd-evidence source artifact ${claim.sourceArtifact} is derived output, not source evidence.`, 'Reference the validator/reviewer/source artifact that contains the evidence, not coverage, cache, proposal, or summary output.'));
+  }
+  if (claim.status === 'PASS') {
+    if (claim.evidence.length === 0) {
+      issues.push(evidenceIssue('UNSOURCED_PASS', 'sdd-evidence.evidence', `PASS claim ${claim.acceptance} has no evidence refs.`, 'Add at least one command, artifact, file, test, or review evidence ref.'));
+    }
+    if (claim.provenance.length === 0) {
+      issues.push(evidenceIssue('PROVENANCE_GAP', 'sdd-evidence.provenance', `PASS claim ${claim.acceptance} has no provenance refs.`, 'Add provenance refs for the artifact, command, run state, or material used by this claim.'));
+    }
+    if (claim.policy.length === 0) {
+      issues.push(evidenceIssue('POLICY_RULE_FAILED', 'sdd-evidence.policy', `PASS claim ${claim.acceptance} has no policy refs.`, `Add ${ACCEPTANCE_POLICY_RULESET_VERSION}:<rule-id> policy refs.`));
+    }
+  }
+  for (const item of claim.evidence) {
+    if (!item.ref) {
+      issues.push(evidenceIssue('MISSING_ARTIFACT_REFERENCE', 'sdd-evidence.evidence', `Evidence item for ${claim.acceptance} has an empty ref.`, `Provide a non-empty evidence ref.`));
+    }
+    if (containsTemplatePlaceholder(item.ref) || containsTemplatePlaceholder(item.summary ?? '')) {
+      issues.push(evidenceIssue('TODO_PLACEHOLDER', 'sdd-evidence.evidence', `Evidence item for ${claim.acceptance} contains placeholder text.`, `Replace TODO/template text with real evidence.`));
+    }
+    if (isDerivedEvidenceRef(item.ref)) {
+      issues.push(evidenceIssue('DERIVED_SOURCE_EVIDENCE', 'sdd-evidence.evidence', `Evidence ref ${item.ref} is derived output, not source evidence.`, `Use source artifacts, commands, files, tests, or material refs.`));
+    }
+  }
+  for (const ref of claim.provenance) {
+    if (isDerivedEvidenceRef(ref)) {
+      issues.push(evidenceIssue('DERIVED_SOURCE_EVIDENCE', 'sdd-evidence.provenance', `Provenance ref ${ref} is derived output, not source evidence.`, `Use source artifact, command, run-state, or material provenance refs.`));
+    }
+  }
+  return issues;
+}
+
+function validateArtifactBodyTrust(raw: string): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (raw.trim().length === 0) {
+    issues.push(evidenceIssue('EMPTY_EVIDENCE', 'evidence', 'Artifact body is empty.', 'Write non-empty evidence and an sdd-result block.'));
+  }
+  if (containsTemplatePlaceholder(raw)) {
+    issues.push(evidenceIssue('TODO_PLACEHOLDER', 'evidence', 'Artifact still contains TODO/template placeholder text.', 'Replace scaffold text with real evidence before claiming PASS.'));
+  }
+  if (/^\s*-\s*\[PASS\]\s*(?:Acceptance\s+)?(?:AC[-\w.]+|[^\r\n]+)\s*$/im.test(raw) && !/^\s*```sdd-evidence\s*$/im.test(raw)) {
+    issues.push(evidenceIssue('MENTION_ONLY', 'acceptance_coverage', 'Validator PASS artifact only mentions an acceptance target without structured source evidence.', `Add ${SDD_EVIDENCE_CONTRACT} claim/evidence/provenance/policy records.`));
+  }
+  if (/Mentioned in artifacts\//i.test(raw)) {
+    issues.push(evidenceIssue('MENTION_ONLY', 'acceptance_coverage', 'Artifact cites generated mention-only coverage text.', 'Use source evidence, not generated coverage summaries.'));
+  }
+  return issues;
+}
+
+function parseEvidenceItem(value: string): EvidenceItem {
+  const separator = value.indexOf(':');
+  if (separator > 0) {
+    const kind = value.slice(0, separator).trim();
+    const ref = value.slice(separator + 1).trim();
+    if (/^[A-Za-z0-9_-]+$/.test(kind)) {
+      return { kind, ref, summary: null };
+    }
+  }
+  return { kind: value.startsWith('artifacts/') ? 'artifact' : 'text', ref: value, summary: null };
+}
+
+function isEvidenceCoverageStatus(value: string): value is EvidenceCoverageStatus {
+  return value === 'PASS' || value === 'FAIL' || value === 'BLOCKED' || value === 'REFERENCED_ONLY' || value === 'MISSING';
+}
+
+export function containsTemplatePlaceholder(value: string): boolean {
+  return /\bTODO\b|template placeholder|TODO\.|Add validation evidence|TODO run validation command|TODO cite files/i.test(value);
+}
+
+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')
+    || normalized.includes('command-output-summary')
+    || normalized.includes('evidence-summary')
+    || normalized.includes('context-package')
+    || normalized.includes('context-build')
+    || normalized.includes('log-worker-summary');
+}
+
+function evidenceIssue(code: EvidenceQualityIssue, field: string, message: string, recommendation: string): ContractValidationIssue {
+  return contractIssue(field, `${code}: ${message}`, recommendation);
+}
+
+function contractIssue(field: string, message: string, recommendation: string): ContractValidationIssue {
+  return { field, message, recommendation };
+}
+
+function parseSimpleYamlBlock(raw: string): Record<string, string | string[]> {
+  const result: Record<string, string | string[]> = {};
+  const lines = raw.split(/\r?\n/);
+  let currentListKey: string | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    if (currentListKey && /^-\s+/.test(trimmed)) {
+      const current = result[currentListKey];
+      const items = Array.isArray(current) ? current : [];
+      items.push(unquoteSimpleYamlValue(trimmed.slice(2).trim()));
+      result[currentListKey] = items;
+      continue;
+    }
+
+    const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!scalarMatch) {
+      currentListKey = null;
+      continue;
+    }
+    const key = scalarMatch[1];
+    const value = scalarMatch[2].trim();
+    if (value === '') {
+      result[key] = [];
+      currentListKey = key;
+    } else if (value === '[]') {
+      result[key] = [];
+      currentListKey = null;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      result[key] = value.slice(1, -1).split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
+      currentListKey = null;
+    } else {
+      result[key] = unquoteSimpleYamlValue(value);
+      currentListKey = null;
+    }
+  }
+
+  return result;
+}
+
+function unquoteSimpleYamlValue(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return value.slice(1, -1);
+    }
+  }
+  return value;
+}
+
+function scalarValue(value: string | string[] | undefined): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function listValue(value: string | string[] | undefined): string[] {
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (!value || value === '[]') {
+    return [];
+  }
+  return [value];
+}

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

@@ -0,0 +1,181 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+import { createRun } from '../run-state/run-state.js';
+import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { getLegacyArtifactPath, getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { parseSddResultMarkdown, validateSddResultArtifact } from './sdd-result.js';
+import { renderSddResultArtifactTemplate } from './templates.js';
+
+test('artifact path cannot escape artifacts directory', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-runtime-'));
+  try {
+    assert.throws(() => getLegacyArtifactPath(root, 'run-1', '../outside.md'), /escapes artifacts directory/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('parseSddResultMarkdown validates a legal sdd-result block', () => {
+  const report = parseSddResultMarkdown(`# Review
+
+\`\`\`sdd-result
+contract: sdd-result-v1
+version: 1.3.0
+agent: reviewer
+task: T1
+status: PASS
+artifacts:
+  - artifacts/review-T1.md
+\`\`\`
+`);
+
+  assert.equal(report.valid, true);
+  assert.equal(report.result?.agent, 'reviewer');
+  assert.equal(report.result?.task, 'T1');
+  assert.deepEqual(report.result?.artifacts, ['artifacts/review-T1.md']);
+});
+
+test('validateSddResultArtifact catches missing, empty, and task mismatch artifacts', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-result-'));
+  try {
+    await initProject(root);
+    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);
+
+    await writeArtifact(root, state.runId, 'empty.md', '');
+    const empty = await validateSddResultArtifact(root, state.runId, 'artifacts/empty.md');
+    assert.equal(empty.valid, false);
+    assert.equal(empty.issues.some((issue) => /empty/.test(issue.message)), true);
+
+    await writeArtifact(root, state.runId, 'review-T2.md', `# Review
+
+\`\`\`sdd-result
+contract: sdd-result-v1
+version: 1.3.0
+agent: reviewer
+task: T2
+status: PASS
+artifacts:
+  - artifacts/review-T2.md
+\`\`\`
+`);
+    const mismatch = await validateSddResultArtifact(root, state.runId, 'artifacts/review-T2.md', { expectedTask: 'T1', expectedAgent: 'reviewer' });
+    assert.equal(mismatch.valid, false);
+    assert.equal(mismatch.issues.some((issue) => issue.field === 'task' && /does not match expected task/.test(issue.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('validateSddResultArtifact accepts legacy run artifact directory for replay compatibility', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-result-legacy-artifact-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'run-1' });
+    const legacyPath = getLegacyArtifactPath(root, state.runId, 'review-T1.md');
+    await mkdir(path.dirname(legacyPath), { recursive: true });
+    await writeFile(legacyPath, `# Review
+
+\`\`\`sdd-result
+contract: sdd-result-v1
+version: 1.3.0
+agent: reviewer
+task: T1
+status: PASS
+artifacts:
+  - artifacts/review-T1.md
+\`\`\`
+`, 'utf8');
+
+    const report = await validateSddResultArtifact(root, state.runId, 'artifacts/review-T1.md', { expectedTask: 'T1', expectedAgent: 'reviewer' });
+
+    assert.equal(report.valid, true);
+    assert.equal(report.result?.task, 'T1');
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('writeArtifact stores new payloads in branch evidence without creating legacy artifact dirs', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-result-evidence-artifact-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1', branch: 'feature', taskId: 'T1' });
+    const written = await writeArtifact(root, state.runId, 'review-T1.md', validResultArtifact('reviewer', 'T1', 'PASS', 'artifacts/review-T1.md'));
+    const portablePath = written.absolutePath.replace(/\\/g, '/');
+
+    assert.equal(written.runRelativePath, 'artifacts/review-T1.md');
+    assert.match(portablePath, /\.sdd\/runs\/feature\/evidence\/artifacts\/review-T1-run-1-[a-f0-9]{12}\.md$/);
+    await assert.rejects(stat(path.join(root, '.sdd', 'runs', state.runId, 'artifacts')), /ENOENT/);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('renderSddResultArtifactTemplate renders self-referencing reviewer artifact', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-artifact-template-review-'));
+  try {
+    await initProject(root);
+    const state = await createRun(root, { runId: 'run-1' });
+    const template = await renderSddResultArtifactTemplate(root, {
+      taskId: 'T1',
+      agent: 'reviewer',
+      artifactPath: 'artifacts/review-T1.md'
+    });
+
+    assert.match(template, /contract: sdd-result-v1/);
+    assert.match(template, /agent: reviewer/);
+    assert.match(template, /task: T1/);
+    assert.match(template, /status: PASS/);
+    assert.match(template, /artifacts:\n  - artifacts\/review-T1\.md/);
+
+    await writeArtifact(root, state.runId, 'review-T1.md', template);
+    const report = await validateSddResultArtifact(root, state.runId, 'artifacts/review-T1.md', { expectedTask: 'T1', expectedAgent: 'reviewer' });
+    assert.equal(report.valid, true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('renderSddResultArtifactTemplate scaffolds validator acceptance mapping without trusted PASS evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-artifact-template-validator-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'feature', validTaskMarkdown('T1', []));
+    const state = await createRun(root, { runId: 'run-1' });
+    const template = await renderSddResultArtifactTemplate(root, {
+      branch: 'feature',
+      taskId: 'T1',
+      agent: 'validator',
+      artifactPath: 'artifacts/validation-T1.md'
+    });
+
+    assert.match(template, /## Acceptance Mapping/);
+    assert.match(template, /Acceptance AC-1: TODO\. Add validation evidence for Parser behavior is covered\./);
+    await writeArtifact(root, state.runId, 'validation-T1.md', template);
+    const report = await validateSddResultArtifact(root, state.runId, 'artifacts/validation-T1.md', { expectedTask: 'T1', expectedAgent: 'validator' });
+    assert.equal(report.valid, false);
+    assert.equal(report.trust?.valid, false);
+    assert.equal(report.issues.some((issue) => issue.message.includes('TODO_PLACEHOLDER')), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('artifact path helpers canonicalize root-relative and run-relative forms', () => {
+  assert.equal(getRunRelativeArtifactPath('nested/result.md'), 'artifacts/nested/result.md');
+  assert.equal(toArtifactRootRelativePath('artifacts/nested/result.md'), 'nested/result.md');
+  assert.throws(() => getRunRelativeArtifactPath('artifacts/result.md'), /artifact-root-relative/);
+  assert.throws(() => toArtifactRootRelativePath('result.md'), /must start with artifacts\//);
+  assert.throws(() => toArtifactRootRelativePath('artifacts/../outside.md'), /relative and stay under artifacts/);
+});