zob-harness 0.1.0

package/scripts/project-dna/bench-smoke.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+
+const LEGACY_CASES = [
+  {
+    id: "factory-schema-validation",
+    query: "factory schema validation",
+    required_citation_includes: ["factory.json", "schemas/"],
+    required_files_to_read_first: ["factory.json"],
+    expected_patterns: [],
+    required_safety: ["bounded_context_only", "citation_required", "no_knowledge_backend_write"],
+    score_threshold: 5,
+  },
+  {
+    id: "config-or-testing-gap",
+    query: "testing config pattern",
+    required_citation_includes: ["README.md"],
+    required_files_to_read_first: ["README.md"],
+    expected_patterns: [],
+    required_safety: ["bounded_context_only", "citation_required", "no_knowledge_backend_write"],
+    score_threshold: 5,
+  },
+  {
+    id: "manifest-compute-profile",
+    query: "manifest compute profile caps",
+    required_citation_includes: ["example-project-dna-manifest.json"],
+    required_files_to_read_first: ["example-project-dna-manifest.json"],
+    expected_patterns: [],
+    required_safety: ["bounded_context_only", "citation_required", "no_knowledge_backend_write"],
+    score_threshold: 5,
+  },
+  {
+    id: "context-pack-schema",
+    query: "context pack schema citations loading rules",
+    required_citation_includes: ["schemas/context-pack.schema.json"],
+    required_files_to_read_first: ["schemas/context-pack.schema.json"],
+    expected_patterns: [],
+    required_safety: ["bounded_context_only", "citation_required", "no_knowledge_backend_write"],
+    score_threshold: 5,
+  },
+];
+
+function usage() {
+  console.error(`Usage:
+  node scripts/project-dna/bench-smoke.mjs --scan-dir <repo-relative-scan-dir> [--out <repo-relative-json>]
+
+Runs a deterministic ProjectDNA retrieval/sample smoke benchmark. Does not call LLMs or external knowledge backend.`);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scan-dir") out.scanDir = argv[++i];
+    else if (arg === "--out") out.out = argv[++i];
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function resolveRepoPath(input, label, allowMissing = false) {
+  if (!input || isAbsolute(input)) throw new Error(`${label} must be repo-relative`);
+  const resolved = resolve(repoRoot, input);
+  const rel = relative(repoRoot, resolved);
+  if (rel.startsWith("..") || rel === "") throw new Error(`${label} must stay inside repo and not be repo root`);
+  if (!allowMissing && !existsSync(resolved)) throw new Error(`${label} not found: ${input}`);
+  return resolved;
+}
+
+function runNode(args) {
+  return execFileSync(process.execPath, args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function optionalJson(path) {
+  return existsSync(path) ? readJson(path) : undefined;
+}
+
+function loadCases(scanDir) {
+  const suite = optionalJson(join(scanDir, "golden-cases-smoke.json")) ?? optionalJson(join(repoRoot, ".pi/factories/project-dna/golden-cases-smoke.json"));
+  if (suite?.schema === "zob.project-dna-golden-suite.v1" && Array.isArray(suite.cases) && suite.cases.length > 0) {
+    return { benchmarkKind: "golden-agentic-5of5-smoke", suiteId: suite.suite_id, cases: suite.cases };
+  }
+  return { benchmarkKind: "legacy-hardcoded-smoke", suiteId: null, cases: LEGACY_CASES };
+}
+
+function queryCase(scanDirRel, testCase, index) {
+  const outRel = `${scanDirRel.replace(/\/$/, "")}/bench/${String(index + 1).padStart(2, "0")}-${testCase.id}.json`;
+  const stewardReportArgs = index === 0 ? ["--steward-report-out", `${scanDirRel.replace(/\/$/, "")}/query-steward-smoke.json`] : [];
+  const stdout = runNode([
+    "scripts/project-dna/query-context.mjs",
+    "--scan-dir", scanDirRel,
+    "--query", testCase.query,
+    "--golden-case-id", testCase.id,
+    "--max-files", "12",
+    "--out", outRel,
+    ...stewardReportArgs,
+  ]);
+  const result = readJson(join(repoRoot, outRel));
+  const citations = result.citations ?? [];
+  const filesToReadFirst = (result.files_to_read_first ?? []).map((file) => String(file.path ?? ""));
+  const patternHits = (result.pattern_hits ?? []).map((pattern) => String(pattern.id ?? ""));
+  const errors = [];
+  if (result.schema !== "zob.project-dna-query-result.v1") errors.push("query result schema mismatch");
+  if (result.query_stored !== false || result.raw_query_persisted !== false) errors.push("query result must not persist raw query");
+  if (result.query_steward?.used !== true) errors.push("query steward must be used");
+  if (result.query_steward?.raw_query_persisted !== false) errors.push("query steward must not persist raw query");
+  if (result.query_steward?.controlled_expansion_terms_stored !== false) errors.push("query steward must not persist raw expansion terms");
+  if (result.loading_rules?.bounded_context_only !== true) errors.push("query result must be bounded_context_only");
+  if (result.loading_rules?.citation_required !== true) errors.push("query result must require citations");
+  if (result.loading_rules?.agent_loads_entire_project !== false) errors.push("query result must not load whole project");
+  if (result.safety?.knowledge_backend_write_enabled !== false) errors.push("query result must keep knowledge_backend_write_enabled=false");
+  for (const needle of testCase.required_citation_includes ?? []) {
+    if (!citations.some((citation) => String(citation).includes(needle))) errors.push(`missing citation containing ${needle}`);
+  }
+  for (const needle of testCase.required_files_to_read_first ?? []) {
+    if (!filesToReadFirst.some((file) => file.includes(needle))) errors.push(`missing files_to_read_first containing ${needle}`);
+  }
+  for (const pattern of testCase.expected_patterns ?? []) {
+    if (!patternHits.includes(pattern)) errors.push(`missing expected pattern hit ${pattern}`);
+  }
+  const score = errors.length === 0 ? 5 : Math.max(0, 5 - errors.length);
+  if (score < Number(testCase.score_threshold ?? 5)) errors.push(`score ${score} below threshold ${testCase.score_threshold ?? 5}`);
+  return {
+    id: testCase.id,
+    status: errors.length === 0 ? "passed" : "failed",
+    score,
+    threshold: Number(testCase.score_threshold ?? 5),
+    errors,
+    queryResultPath: outRel,
+    citationCount: citations.length,
+    citations_checked: citations,
+    filesToReadFirstCount: filesToReadFirst.length,
+    patternHitCount: patternHits.length,
+    stewardIntent: result.query_steward?.intent_id ?? null,
+    stdoutFirstLine: stdout.split("\n")[0] ?? "",
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.scanDir) {
+    usage();
+    if (!args.help) process.exit(2);
+    return;
+  }
+  const scanDir = resolveRepoPath(args.scanDir, "--scan-dir");
+  const scanDirRel = relative(repoRoot, scanDir).split(sep).join("/");
+  const outPath = resolveRepoPath(args.out ?? `${scanDirRel}/bench/benchmark-smoke.json`, "--out", true);
+  mkdirSync(dirname(outPath), { recursive: true });
+
+  const errors = [];
+  const commandResults = [];
+  try {
+    commandResults.push({ command: `node scripts/project-dna/validate-scan-artifacts.mjs --scan-dir ${scanDirRel}`, output: runNode(["scripts/project-dna/validate-scan-artifacts.mjs", "--scan-dir", scanDirRel]).split("\n")[0] });
+  } catch (error) {
+    errors.push(`scan validation failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const sampleDirRel = `${scanDirRel}/quarantine/sample-project`;
+  if (existsSync(join(repoRoot, sampleDirRel))) {
+    try {
+      commandResults.push({ command: `node scripts/project-dna/validate-sample-project.mjs --sample-dir ${sampleDirRel}`, output: runNode(["scripts/project-dna/validate-sample-project.mjs", "--sample-dir", sampleDirRel]).split("\n")[0] });
+    } catch (error) {
+      errors.push(`sample validation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    errors.push(`sample dir missing for benchmark: ${sampleDirRel}`);
+  }
+
+  const suite = loadCases(scanDir);
+  const cases = suite.cases.map((testCase, index) => queryCase(scanDirRel, testCase, index));
+  for (const testCase of cases) for (const error of testCase.errors) errors.push(`${testCase.id}: ${error}`);
+
+  const result = {
+    schema: "zob.project-dna-benchmark-smoke.v1",
+    benchmark_kind: suite.benchmarkKind,
+    suite_id: suite.suiteId,
+    scan_dir: scanDirRel,
+    status: errors.length === 0 ? "passed" : "failed",
+    cases,
+    command_results: commandResults,
+    errors,
+    metrics: {
+      cases_total: cases.length,
+      cases_passed: cases.filter((testCase) => testCase.status === "passed").length,
+      citation_total: cases.reduce((sum, testCase) => sum + testCase.citationCount, 0),
+      average_score: cases.length > 0 ? Number((cases.reduce((sum, testCase) => sum + testCase.score, 0) / cases.length).toFixed(2)) : 0,
+    },
+    gates: {
+      deterministic_only: true,
+      llm_judge_used: false,
+      source_project_modified: false,
+      knowledge_backend_write_enabled: false,
+      promotion_allowed: false,
+      human_approval_required: true,
+    }
+  };
+  writeFileSync(outPath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify(result, null, 2));
+  if (errors.length > 0) process.exit(1);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(JSON.stringify({ schema: "zob.project-dna-benchmark-smoke-error.v1", error: error instanceof Error ? error.message : String(error), source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+  process.exit(1);
+}

package/scripts/project-dna/build-capsules.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+
+function usage() {
+  console.error(`Usage:
+  node scripts/project-dna/build-capsules.mjs --scan-dir <repo-relative-scan-dir> [--out-dir <repo-relative-output-dir>]
+
+Builds pointer capsules from ProjectDNA scan metadata. Does not read source project files.`);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scan-dir") out.scanDir = argv[++i];
+    else if (arg === "--out-dir") out.outDir = argv[++i];
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function resolveRepoDir(input, label) {
+  if (!input || isAbsolute(input)) throw new Error(`${label} must be repo-relative`);
+  const resolved = resolve(repoRoot, input);
+  const rel = relative(repoRoot, resolved);
+  if (rel.startsWith("..") || rel === "") throw new Error(`${label} must stay inside repo and not be repo root`);
+  return resolved;
+}
+
+function readJson(dir, name) {
+  const path = join(dir, name);
+  if (!existsSync(path)) throw new Error(`missing scan artifact: ${name}`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function citationList(citations = []) {
+  const unique = [...new Set(citations.filter(Boolean))];
+  if (unique.length === 0) return "- Gap: no citations available.";
+  return unique.map((citation) => `- \`${citation}\``).join("\n");
+}
+
+function filesByKind(fileMap, kind) {
+  return (fileMap.files ?? []).filter((file) => file.kind === kind);
+}
+
+function filesAsPointers(files, limit = 12) {
+  if (files.length === 0) return "- Gap: no matching files detected.";
+  return files.slice(0, limit).map((file) => {
+    const citation = file.citations?.[0] ?? file.path;
+    return `- \`${citation}\` — ${file.kind}${file.imports?.length ? `; imports: ${file.imports.slice(0, 5).join(", ")}` : ""}`;
+  }).join("\n");
+}
+
+function writeCapsule(outDir, name, content) {
+  writeFileSync(join(outDir, name), `${content.trim()}\n`, "utf8");
+}
+
+function capsuleHeader(title, sourceId) {
+  return `# ${title}\n\nSource: \`${sourceId}\`\n\nStatus: generated pointer capsule from ProjectDNA scan metadata. Treat citations as navigation hints, not full truth. Read cited files before implementation.\n`;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.scanDir) {
+    usage();
+    if (!args.help) process.exit(2);
+    return;
+  }
+  const scanDir = resolveRepoDir(args.scanDir, "--scan-dir");
+  const outDir = resolveRepoDir(args.outDir ?? `${args.scanDir.replace(/\/$/, "")}/capsules`, "--out-dir");
+  const outRel = relative(repoRoot, outDir).split(sep).join("/");
+  mkdirSync(outDir, { recursive: true });
+
+  const fingerprint = readJson(scanDir, "project-fingerprint.json");
+  const dependencyMap = readJson(scanDir, "dependency-map.json");
+  const fileMap = readJson(scanDir, "file-map.json");
+  const architectureMap = readJson(scanDir, "architecture-map.json");
+  const contextPack = readJson(scanDir, "context-pack-smoke.json");
+  const graph = readJson(scanDir, "code-knowledge-graph.json");
+  const sourceId = fingerprint.source_id;
+
+  const capsules = [];
+
+  const architecture = `${capsuleHeader("Architecture overview", sourceId)}
+## Look here first
+
+${citationList(contextPack.citations)}
+
+## Detected stack/tools
+
+- package manager: ${dependencyMap.package_manager ?? "not detected"}
+- runtime dependencies: ${(dependencyMap.runtime_dependencies ?? []).slice(0, 20).join(", ") || "none detected"}
+- dev dependencies: ${(dependencyMap.dev_dependencies ?? []).slice(0, 20).join(", ") || "none detected"}
+
+## Detected patterns
+
+${(architectureMap.patterns ?? []).length ? architectureMap.patterns.map((pattern) => `- ${pattern.id} (${pattern.confidence}) — evidence: ${(pattern.evidence ?? []).slice(0, 4).map((item) => `\`${item}\``).join(", ")}`).join("\n") : "- Gap: no high-confidence architecture patterns detected."}
+
+## Graph summary
+
+- nodes: ${(graph.nodes ?? []).length}
+- edges: ${(graph.edges ?? []).length}
+
+## Gaps
+
+${(architectureMap.gaps ?? []).map((gap) => `- ${gap}`).join("\n") || "- No scan-level gaps reported."}
+`;
+  writeCapsule(outDir, "architecture.md", architecture);
+  capsules.push("architecture.md");
+
+  const folderStructure = `${capsuleHeader("Folder structure", sourceId)}
+## Top-level directories/files
+
+${(architectureMap.top_level_directories ?? []).map((dir) => `- \`${dir}\``).join("\n") || "- Gap: no files detected."}
+
+## File pointers by kind
+
+${Object.entries(architectureMap.kind_counts ?? {}).sort(([a], [b]) => a.localeCompare(b)).map(([kind, count]) => `- ${kind}: ${count}`).join("\n") || "- Gap: no kind counts available."}
+`;
+  writeCapsule(outDir, "folder-structure.md", folderStructure);
+  capsules.push("folder-structure.md");
+
+  const testing = `${capsuleHeader("Testing pointers", sourceId)}
+## Test files
+
+${filesAsPointers(filesByKind(fileMap, "test"))}
+
+## Observed rule
+
+- Use these citations to infer test placement/style; do not infer missing test conventions from generic framework docs.
+`;
+  writeCapsule(outDir, "testing.md", testing);
+  capsules.push("testing.md");
+
+  const config = `${capsuleHeader("Config pointers", sourceId)}
+## Config files
+
+${filesAsPointers(filesByKind(fileMap, "config"))}
+
+## Observed rule
+
+- Prefer cited config files over ad-hoc direct client/secret construction.
+`;
+  writeCapsule(outDir, "config.md", config);
+  capsules.push("config.md");
+
+  const services = `${capsuleHeader("Service-layer pointers", sourceId)}
+## Service files
+
+${filesAsPointers(filesByKind(fileMap, "service"))}
+
+## Route/controller files
+
+${filesAsPointers(filesByKind(fileMap, "route"))}
+
+## Observed rule
+
+- If both route and service files exist, inspect cited pairs before adding business logic.
+`;
+  writeCapsule(outDir, "services.md", services);
+  capsules.push("services.md");
+
+  const queues = `${capsuleHeader("Queue / worker pointers", sourceId)}
+## Queue files
+
+${filesAsPointers(filesByKind(fileMap, "queue"))}
+
+## Worker files
+
+${filesAsPointers(filesByKind(fileMap, "worker"))}
+
+## Tool evidence
+
+${(dependencyMap.tool_roles ?? []).filter((tool) => tool.role === "queue").map((tool) => `- ${tool.name}: ${tool.role}`).join("\n") || "- Gap: no queue dependency detected."}
+
+## Observed rule
+
+- Only use this capsule when cited queue/worker files exist; otherwise report a gap instead of inventing a queue pattern.
+`;
+  writeCapsule(outDir, "queues.md", queues);
+  capsules.push("queues.md");
+
+  const summary = {
+    schema: "zob.project-dna-capsule-build-summary.v1",
+    source_id: sourceId,
+    scan_dir: relative(repoRoot, scanDir).split(sep).join("/"),
+    out_dir: outRel,
+    capsules,
+    source_files_read: false,
+    scan_metadata_only: true,
+    source_project_modified: false,
+    knowledge_backend_write_enabled: false,
+  };
+  writeFileSync(join(outDir, "capsule-summary.json"), `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify(summary, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(JSON.stringify({ schema: "zob.project-dna-capsule-build-error.v1", error: error instanceof Error ? error.message : String(error), source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+  process.exit(1);
+}

package/scripts/project-dna/build-sample-spec.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+
+function usage() {
+  console.error(`Usage:
+  node scripts/project-dna/build-sample-spec.mjs --scan-dir <repo-relative-scan-dir> [--neutral-domain <domain>] [--out <repo-relative-json>]
+
+Builds a neutral ProjectDNA sample specification from scan metadata. It does not generate sample code.`);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scan-dir") out.scanDir = argv[++i];
+    else if (arg === "--neutral-domain") out.neutralDomain = argv[++i];
+    else if (arg === "--out") out.out = argv[++i];
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function resolveRepoPath(input, label) {
+  if (!input || isAbsolute(input)) throw new Error(`${label} must be repo-relative`);
+  const resolved = resolve(repoRoot, input);
+  const rel = relative(repoRoot, resolved);
+  if (rel.startsWith("..") || rel === "") throw new Error(`${label} must stay inside repo and not be repo root`);
+  return resolved;
+}
+
+function readJson(dir, name) {
+  const path = join(dir, name);
+  if (!existsSync(path)) throw new Error(`missing scan artifact: ${name}`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.scanDir) {
+    usage();
+    if (!args.help) process.exit(2);
+    return;
+  }
+
+  const scanDir = resolveRepoPath(args.scanDir, "--scan-dir");
+  const outPath = resolveRepoPath(args.out ?? `${args.scanDir.replace(/\/$/, "")}/sample-spec.json`, "--out");
+  const fingerprint = readJson(scanDir, "project-fingerprint.json");
+  const dependencyMap = readJson(scanDir, "dependency-map.json");
+  const fileMap = readJson(scanDir, "file-map.json");
+  const architectureMap = readJson(scanDir, "architecture-map.json");
+  const contextPack = readJson(scanDir, "context-pack-smoke.json");
+
+  const kinds = new Set((fileMap.files ?? []).map((file) => file.kind));
+  const requiredModules = ["config"];
+  if (kinds.has("route") || kinds.has("entrypoint")) requiredModules.push("api");
+  if (kinds.has("service")) requiredModules.push("services");
+  if (kinds.has("queue") || kinds.has("worker")) requiredModules.push("queues", "workers");
+  if (kinds.has("database")) requiredModules.push("database");
+  if (kinds.has("test")) requiredModules.push("tests");
+  if (requiredModules.length === 1) requiredModules.push("example-module", "tests");
+
+  const toolRoles = dependencyMap.tool_roles ?? [];
+  const preserve = unique([
+    dependencyMap.package_manager ? `package-manager:${dependencyMap.package_manager}` : undefined,
+    ...toolRoles.map((tool) => `tool-role:${tool.name}:${tool.role}`),
+    ...Object.keys(architectureMap.kind_counts ?? {}).map((kind) => `file-kind:${kind}`),
+    ...((architectureMap.patterns ?? []).map((pattern) => `pattern:${pattern.id}`)),
+  ]);
+
+  const sampleSpec = {
+    schema: "zob.project-dna-sample-spec.v1",
+    source_id: fingerprint.source_id,
+    sample_name: `${fingerprint.source_id}-dna-sample`,
+    neutral_domain: args.neutralDomain ?? "task-tracker",
+    generation_status: "spec_only_no_code_generated",
+    target_stack_policy: "preserve_detected_stack_where_safe",
+    copy_policy: "structure_and_patterns_only",
+    preserve,
+    remove: [
+      "real product concepts",
+      "company/user/customer names",
+      "business-specific logic",
+      "private data",
+      "secrets and credentials",
+      "fragile external integrations",
+      "large verbatim source files"
+    ],
+    required_modules: unique(requiredModules),
+    suggested_files: unique(requiredModules).map((module) => ({
+      module,
+      path: module === "api" ? "src/api/routes.ts" : module === "tests" ? "test/sample.test.ts" : `src/${module}/index.ts`,
+      purpose: `neutral ${module} example preserving observed ProjectDNA conventions where cited`,
+    })),
+    citations: unique([...(contextPack.citations ?? []), ...(architectureMap.citations ?? [])]).slice(0, 30),
+    validation: {
+      required: true,
+      suggested_commands: ["install", "lint/typecheck if configured", "test if configured", "build if configured"],
+      no_ship_if_fails: true,
+    },
+    promotion: {
+      writeback_policy: "proposal_only",
+      oracle_required: true,
+      human_approval_required: true,
+    },
+    safety: {
+      source_files_read: false,
+      scan_metadata_only: true,
+      sample_code_generated: false,
+      source_project_modified: false,
+      knowledge_backend_write_enabled: false,
+    },
+  };
+
+  writeFileSync(outPath, `${JSON.stringify(sampleSpec, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify({
+    schema: "zob.project-dna-sample-spec-build-summary.v1",
+    source_id: fingerprint.source_id,
+    out: relative(repoRoot, outPath).split(sep).join("/"),
+    neutral_domain: sampleSpec.neutral_domain,
+    required_modules: sampleSpec.required_modules,
+    sample_code_generated: false,
+    source_project_modified: false,
+    knowledge_backend_write_enabled: false,
+  }, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(JSON.stringify({ schema: "zob.project-dna-sample-spec-error.v1", error: error instanceof Error ? error.message : String(error), source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+  process.exit(1);
+}

package/scripts/project-dna/emit-golden-cases.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+
+function usage() {
+  console.error(`Usage:
+  node scripts/project-dna/emit-golden-cases.mjs --scan-dir <repo-relative-scan-dir> [--source <repo-relative-json>] [--out <repo-relative-json>]
+
+Copies ProjectDNA golden cases into a reports scan directory. No source scan, no backend write.`);
+}
+
+function parseArgs(argv) {
+  const out = { source: ".pi/factories/project-dna/golden-cases-smoke.json" };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scan-dir") out.scanDir = argv[++i];
+    else if (arg === "--source") out.source = argv[++i];
+    else if (arg === "--out") out.out = argv[++i];
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function resolveRepoPath(input, label, allowMissing = false) {
+  if (!input || isAbsolute(input)) throw new Error(`${label} must be repo-relative`);
+  const resolved = resolve(repoRoot, input);
+  const rel = relative(repoRoot, resolved);
+  if (rel.startsWith("..") || rel === "") throw new Error(`${label} must stay inside repo and not be repo root`);
+  if (!allowMissing && !existsSync(resolved)) throw new Error(`${label} not found: ${input}`);
+  return resolved;
+}
+
+function assertReportPath(input, label) {
+  const normalized = input.split(sep).join("/");
+  if (!normalized.startsWith("reports/project-dna-scans/")) throw new Error(`${label} must stay under reports/project-dna-scans`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.scanDir) {
+    usage();
+    if (!args.help) process.exit(2);
+    return;
+  }
+  assertReportPath(args.scanDir, "--scan-dir");
+  const scanDir = resolveRepoPath(args.scanDir, "--scan-dir", true);
+  const sourcePath = resolveRepoPath(args.source, "--source");
+  const outRel = args.out ?? `${args.scanDir.replace(/\/$/, "")}/golden-cases-smoke.json`;
+  assertReportPath(outRel, "--out");
+  const outPath = resolveRepoPath(outRel, "--out", true);
+  if (!relative(scanDir, outPath) || relative(scanDir, outPath).startsWith("..")) throw new Error("--out must stay inside --scan-dir");
+  const suite = JSON.parse(readFileSync(sourcePath, "utf8"));
+  if (suite.schema !== "zob.project-dna-golden-suite.v1") throw new Error("golden case suite schema mismatch");
+  const emitted = {
+    ...suite,
+    emitted_from: relative(repoRoot, sourcePath).split(sep).join("/"),
+    scan_dir: relative(repoRoot, scanDir).split(sep).join("/"),
+    source_project_modified: false,
+    knowledge_backend_write_enabled: false,
+    durable_promotion_allowed: false,
+  };
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(emitted, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify({ schema: "zob.project-dna-golden-cases-emission.v1", out: relative(repoRoot, outPath).split(sep).join("/"), case_count: emitted.cases.length, source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(JSON.stringify({ schema: "zob.project-dna-golden-cases-emission-error.v1", error: error instanceof Error ? error.message : String(error), source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+  process.exit(1);
+}