zob-harness 0.1.0

package/scripts/project-dna/plan-workflow.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+const profiles = new Set(["auto", "low", "medium", "high", "xhigh", "max"]);
+const semanticCaptureModes = new Set(["full_capture", "architecture_only", "targeted_capture", "sample_first", "context_only"]);
+const rawKeyDenylist = new Set(["body", "prompt", "output", "content", "diff", "patch"]);
+
+function usage() {
+  console.error("Usage: node scripts/project-dna/plan-workflow.mjs --manifest .pi/factories/project-dna/example-project-dna-manifest-v2.json [--scan-dir reports/project-dna-scans/project-dna-factory-smoke] --out reports/project-dna-scans/project-dna-factory-smoke/agentic-plan.json");
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--manifest") args.manifest = argv[++index];
+    else if (arg === "--scan-dir") args.scanDir = argv[++index];
+    else if (arg === "--out") args.out = argv[++index];
+    else if (arg === "--help" || arg === "-h") { usage(); process.exit(0); }
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  if (!args.manifest || !args.out) throw new Error("--manifest and --out are required");
+  return args;
+}
+
+function repoPath(path, label) {
+  if (!path || isAbsolute(path)) throw new Error(`${label} must be repo-relative`);
+  const resolved = resolve(repoRoot, path);
+  const root = resolve(repoRoot);
+  const rel = relative(root, resolved);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) throw new Error(`${label} must stay inside repo and not be repo root: ${path}`);
+  return resolved;
+}
+
+function assertReportPath(path, label) {
+  const normalized = path.split(sep).join("/");
+  if (!normalized.startsWith("reports/project-dna-scans/")) throw new Error(`${label} must stay under reports/project-dna-scans: ${path}`);
+}
+
+function isInsideOrEqual(parent, child) {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function assertNotBroadPath(path, label) {
+  const resolved = resolve(path);
+  if (["/", "/home", "/home/ubuntu"].includes(resolved)) throw new Error(`refusing broad ${label}: ${path}`);
+}
+
+function inputPath(path, label) {
+  if (!path) throw new Error(`${label} is required`);
+  const resolved = isAbsolute(path) ? resolve(path) : repoPath(path, label);
+  assertNotBroadPath(resolved, label);
+  return resolved;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function assertNoRawKeys(value, trail = []) {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) assertNoRawKeys(value[index], [...trail, String(index)]);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (rawKeyDenylist.has(key.toLowerCase())) throw new Error(`raw key forbidden in plan metadata: ${[...trail, key].join(".")}`);
+    assertNoRawKeys(child, [...trail, key]);
+  }
+}
+
+function requireBoolean(value, expected, label, errors) {
+  if (value !== expected) errors.push(`${label} must be ${expected}`);
+}
+
+function validateManifest(manifest) {
+  const errors = [];
+  if (manifest.schema !== "zob.project-dna-manifest.v2") errors.push("manifest schema must be zob.project-dna-manifest.v2");
+  if (typeof manifest.run_id !== "string" || !/^[A-Za-z0-9._-]+$/.test(manifest.run_id)) errors.push("run_id must be a safe id");
+  if (typeof manifest.user_note !== "string" || manifest.user_note.length < 1) errors.push("user_note is required");
+  if (typeof manifest.capture_goal?.objective !== "string" || manifest.capture_goal.objective.length < 1) errors.push("capture_goal.objective is required");
+  requireBoolean(manifest.capture_goal?.bounded_context_only, true, "capture_goal.bounded_context_only", errors);
+  requireBoolean(manifest.capture_goal?.citation_required, true, "capture_goal.citation_required", errors);
+  if (!profiles.has(manifest.requested_compute_profile)) errors.push("requested_compute_profile invalid");
+  if (!semanticCaptureModes.has(manifest.capture_mode_policy?.semantic_mode)) errors.push("capture_mode_policy.semantic_mode invalid");
+  if (manifest.capture_mode_policy?.large_repo_fallback !== undefined && !["architecture_only", "targeted_capture", "sample_first", "context_only"].includes(manifest.capture_mode_policy.large_repo_fallback)) errors.push("capture_mode_policy.large_repo_fallback invalid");
+  requireBoolean(manifest.capture_mode_policy?.metadata_only, true, "capture_mode_policy.metadata_only", errors);
+  requireBoolean(manifest.capture_mode_policy?.parent_owned_dispatch, true, "capture_mode_policy.parent_owned_dispatch", errors);
+  requireBoolean(manifest.capture_mode_policy?.child_direct_dispatch_allowed, false, "capture_mode_policy.child_direct_dispatch_allowed", errors);
+  requireBoolean(manifest.capture_mode_policy?.network_access_allowed, false, "capture_mode_policy.network_access_allowed", errors);
+  requireBoolean(manifest.capture_mode_policy?.source_mutation_allowed, false, "capture_mode_policy.source_mutation_allowed", errors);
+  requireBoolean(manifest.capture_mode_policy?.knowledge_backend_write_allowed, false, "capture_mode_policy.knowledge_backend_write_allowed", errors);
+  if (manifest.capture_mode_policy?.durable_promotion_allowed !== undefined) requireBoolean(manifest.capture_mode_policy.durable_promotion_allowed, false, "capture_mode_policy.durable_promotion_allowed", errors);
+  if (typeof manifest.source_project?.source_id !== "string" || !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(manifest.source_project.source_id)) errors.push("source_project.source_id invalid");
+  if (manifest.capture_goal?.source_id !== manifest.source_project?.source_id) errors.push("capture_goal.source_id must match source_project.source_id");
+  if (typeof manifest.source_project?.path !== "string" || manifest.source_project.path.length < 1) errors.push("source_project.path is required");
+  if (!Array.isArray(manifest.read_policy?.allowed_paths) || manifest.read_policy.allowed_paths.length < 1) errors.push("read_policy.allowed_paths required");
+  if (!Array.isArray(manifest.read_policy?.forbidden_patterns) || manifest.read_policy.forbidden_patterns.length < 1) errors.push("read_policy.forbidden_patterns required");
+  requireBoolean(manifest.read_policy?.forbid_secret_like_paths, true, "read_policy.forbid_secret_like_paths", errors);
+  requireBoolean(manifest.read_policy?.external_project_scan_allowed, false, "read_policy.external_project_scan_allowed", errors);
+  requireBoolean(manifest.sample_project?.quarantine_required, true, "sample_project.quarantine_required", errors);
+  if (manifest.sample_project?.generation_policy !== "plan_only" && manifest.sample_project?.generation_policy !== "quarantine_only") errors.push("sample_project.generation_policy invalid");
+  if (manifest.promotion?.writeback_policy !== "proposal_only") errors.push("promotion.writeback_policy must be proposal_only");
+  requireBoolean(manifest.promotion?.requires_oracle_pass, true, "promotion.requires_oracle_pass", errors);
+  requireBoolean(manifest.promotion?.requires_human_approval, true, "promotion.requires_human_approval", errors);
+  requireBoolean(manifest.promotion?.durable_promotion_allowed, false, "promotion.durable_promotion_allowed", errors);
+  return errors;
+}
+
+function effectiveProfile(requested) {
+  if (requested === "auto") return "medium";
+  return profiles.has(requested) ? requested : "low";
+}
+
+function readOptionalScanSummary(scanDir) {
+  if (!scanDir) return {};
+  const summaryPath = repoPath(`${scanDir.replace(/\/$/, "")}/scan-summary.json`, "scan-summary");
+  if (!existsSync(summaryPath)) return {};
+  const parsed = JSON.parse(readFileSync(summaryPath, "utf8"));
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+
+function deriveCaptureMode(manifest, profile, scanSummary) {
+  const requested = manifest.capture_mode_policy?.semantic_mode;
+  const fallback = manifest.capture_mode_policy?.large_repo_fallback ?? "architecture_only";
+  const fileCount = Number(scanSummary.files_scanned ?? 0);
+  const intent = `${manifest.user_note ?? ""} ${manifest.capture_goal?.objective ?? ""}`.toLowerCase();
+  if (requested && requested !== "full_capture") return requested;
+  if (/\b(sample|exemple|example|neutral)\b/.test(intent)) return "sample_first";
+  if (/\b(context|query|lookup|retrieval)\b/.test(intent)) return "context_only";
+  if (/\b(architecture|archi|structure|scaffold)\b/.test(intent)) return "architecture_only";
+  if (fileCount >= 1000 || profile === "xhigh" || profile === "max") return fallback;
+  return requested ?? "full_capture";
+}
+
+function laneCatalog(profile) {
+  const base = [
+    { id: "manifest_preflight", phase: "p0", agent: "project-dna-safety-preflight", artifactContract: "safety-metadata.v1", toolHints: ["read"], required: true },
+    { id: "repo_scout", phase: "p0", agent: "repo-scout", artifactContract: "repo-complexity-report.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "read_only_scan", phase: "p1", agent: "agent", artifactContract: "scan-metadata.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "scan_validation", phase: "p1", agent: "qa", artifactContract: "validation-metadata.v1", toolHints: ["read", "bash"], required: true }
+  ];
+  if (["medium", "high", "xhigh", "max"].includes(profile)) base.push(
+    { id: "ontology_curation", phase: "p1", agent: "project-dna-ontology-steward", artifactContract: "ontology-metadata.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "architecture_cartography", phase: "p1", agent: "architecture-cartographer", artifactContract: "architecture-map.v2", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "pattern_mining", phase: "p1", agent: "pattern-miner", artifactContract: "pattern-index.partial.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "test_linking", phase: "p1", agent: "project-dna-test-linker", artifactContract: "test-link-metadata.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "capsule_build", phase: "p1", agent: "context-steward", artifactContract: "capsule-pointer-metadata.v1", toolHints: ["read"], required: true },
+    { id: "sample_spec", phase: "p1", agent: "sample-architect", artifactContract: "sample-spec-metadata.v1", toolHints: ["read"], required: true },
+    { id: "query_steward_review", phase: "p1", agent: "project-dna-query-steward", artifactContract: "query-steward-report.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "bounded_query", phase: "p1", agent: "context-steward", artifactContract: "context-pack-metadata.v1", toolHints: ["read"], required: true }
+  );
+  if (["high", "xhigh", "max"].includes(profile)) base.push(
+    { id: "symbol_range_curation", phase: "p1", agent: "symbol-range-curator", artifactContract: "range-quality-report.v1", toolHints: ["read", "grep", "find", "ls"], required: true },
+    { id: "quarantine_sample", phase: "p1", agent: "implementer", artifactContract: "quarantine-sample-metadata.v1", toolHints: ["read", "bash"], required: false },
+    { id: "golden_case_benchmark", phase: "p1", agent: "project-dna-golden-evaluator", artifactContract: "golden-benchmark-metadata.v1", toolHints: ["read", "bash"], required: true },
+    { id: "benchmark", phase: "p1", agent: "qa", artifactContract: "benchmark-metadata.v1", toolHints: ["read", "bash"], required: false },
+    { id: "oracle_review", phase: "p1", agent: "project-dna-oracle", artifactContract: "oracle-metadata.v1", toolHints: ["read", "grep", "find", "ls"], required: true }
+  );
+  if (["xhigh", "max"].includes(profile)) base.push({ id: "adversarial_safety_review", phase: "p1", agent: "project-dna-oracle", artifactContract: "oracle-metadata.v1", toolHints: ["read", "grep", "find", "ls"], required: true });
+  if (profile === "max") base.push({ id: "human_promotion_packet", phase: "p1", agent: "planner", artifactContract: "proposal-metadata.v1", toolHints: ["read"], required: true });
+  return base;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const manifestPath = repoPath(args.manifest, "--manifest");
+  if (!existsSync(manifestPath)) throw new Error(`missing manifest: ${args.manifest}`);
+  const manifestText = readFileSync(manifestPath, "utf8");
+  const manifest = JSON.parse(manifestText);
+  assertNoRawKeys(manifest);
+  const manifestErrors = validateManifest(manifest);
+  if (manifestErrors.length > 0) throw new Error(`manifest validation failed: ${manifestErrors.join("; ")}`);
+
+  const sourcePath = inputPath(manifest.source_project.path, "source_project.path");
+  if (!existsSync(sourcePath)) throw new Error(`source_project.path does not exist: ${manifest.source_project.path}`);
+  const allowedPaths = manifest.read_policy.allowed_paths.map((allowedPath) => {
+    const allowed = inputPath(allowedPath, "read_policy.allowed_paths[]");
+    if (!existsSync(allowed)) throw new Error(`read_policy.allowed_paths entry does not exist: ${allowedPath}`);
+    return allowed;
+  });
+  if (!allowedPaths.some((allowed) => isInsideOrEqual(allowed, sourcePath))) throw new Error("source_project.path must be inside one read_policy.allowed_paths entry");
+  if (args.scanDir) {
+    assertReportPath(args.scanDir, "--scan-dir");
+    repoPath(args.scanDir, "--scan-dir");
+  }
+  assertReportPath(args.out, "--out");
+  const outPath = repoPath(args.out, "--out");
+  const profile = effectiveProfile(manifest.requested_compute_profile);
+  const scanSummary = readOptionalScanSummary(args.scanDir);
+  const effectiveCapture = deriveCaptureMode(manifest, profile, scanSummary);
+  const caps = manifest.compute_caps ?? {};
+  const maxParallel = Math.max(1, Math.min(Number(caps.maxParallel ?? 1), Number(caps.maxAgents ?? 1), 8));
+  const lanes = laneCatalog(profile).map((lane, index) => ({
+    ...lane,
+    order: index + 1,
+    maxWorkers: Math.min(maxParallel, lane.id === "read_only_scan" ? 2 : 1),
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+    liveDispatchEnabled: false,
+    sourceMutationAllowed: false,
+    backendWritesEnabled: false,
+    durablePromotionAllowed: false,
+    storesRawBodies: false
+  }));
+  const plan = {
+    schema: "zob.project-dna-agentic-plan.v1",
+    runId: manifest.run_id,
+    sourceId: manifest.source_project.source_id,
+    manifestPath: args.manifest,
+    manifestHash: sha256(manifestText),
+    manifestEmbedded: false,
+    scanDir: args.scanDir ?? `reports/project-dna-scans/${manifest.run_id}`,
+    requestedComputeProfile: manifest.requested_compute_profile,
+    effectiveComputeProfile: profile,
+    requestedCaptureMode: manifest.capture_mode_policy.semantic_mode,
+    effectiveCaptureMode: effectiveCapture,
+    captureModeRationale: "derived_from_manifest_user_note_profile_and_optional_scan_summary",
+    targetedDomains: Array.isArray(manifest.capture_mode_policy.targeted_domains) ? manifest.capture_mode_policy.targeted_domains : [],
+    repoStats: {
+      filesScanned: Number.isFinite(Number(scanSummary.files_scanned)) ? Number(scanSummary.files_scanned) : null,
+      filesSkipped: Number.isFinite(Number(scanSummary.files_skipped)) ? Number(scanSummary.files_skipped) : null,
+      scanSummaryAvailable: Object.keys(scanSummary).length > 0
+    },
+    objectiveHash: sha256(manifest.capture_goal.objective),
+    metadataOnly: true,
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+    liveDispatchEnabled: false,
+    noExecution: true,
+    networkAccessed: false,
+    sourceProjectModified: false,
+    sourceMutationAllowed: false,
+    knowledgeBackendWriteEnabled: false,
+    durablePromotionAllowed: false,
+    rawBodiesStored: false,
+    promptBodiesStored: false,
+    resultBodiesStored: false,
+    bodyFreePlan: true,
+    dispatchPosture: "parent_owned_no_child_direct_dispatch",
+    promotionPolicy: "proposal_only",
+    artifactTargets: [
+      "project-fingerprint.json",
+      "dependency-map.json",
+      "file-map.json",
+      "symbol-map.json",
+      "import-graph.json",
+      "architecture-map.json",
+      "route-map.json",
+      "queue-map.json",
+      "config-map.json",
+      "test-map.json",
+      "db-map.json",
+      "ontology.json",
+      "golden-cases-smoke.json",
+      "query-steward-smoke.json",
+      "code-knowledge-graph.json",
+      "context-pack-smoke.json"
+    ],
+    lanes,
+    safetyAssertions: {
+      sourceReadOnly: true,
+      forbiddenPathsExcluded: true,
+      secretLikePathsForbidden: true,
+      externalKnowledgeBackendDisabled: true,
+      durablePromotionRequiresHumanApproval: true,
+      citationsRequired: true,
+      boundedContextOnly: true
+    },
+    blockers: [],
+    generatedAt: new Date().toISOString()
+  };
+  assertNoRawKeys(plan);
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+  console.log(JSON.stringify({ schema: "zob.project-dna-agentic-plan-cli.v1", planPath: relative(repoRoot, outPath).split(sep).join("/"), effectiveComputeProfile: profile, effectiveCaptureMode: effectiveCapture, laneCount: lanes.length, metadataOnly: true, childDispatchAllowed: false }, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  usage();
+  process.exit(1);
+}

package/scripts/project-dna/query-context.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+const repoRoot = process.cwd();
+const STOPWORDS = new Set(["the", "and", "for", "with", "how", "does", "this", "that", "dans", "avec", "pour", "comment", "faire", "using", "use", "project", "style"]);
+
+function usage() {
+  console.error(`Usage:
+  node scripts/project-dna/query-context.mjs --scan-dir <repo-relative-scan-dir> --query <text> [--out <repo-relative-json>] [--max-files 8]
+
+Builds a bounded cited ProjectDNA context pack from scan metadata. Raw query text is hashed, not persisted.`);
+}
+
+function parseArgs(argv) {
+  const out = { maxFiles: 8 };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--scan-dir") out.scanDir = argv[++i];
+    else if (arg === "--query") out.query = argv[++i];
+    else if (arg === "--out") out.out = argv[++i];
+    else if (arg === "--max-files") out.maxFiles = Number(argv[++i]);
+    else if (arg === "--golden-case-id") out.goldenCaseId = argv[++i];
+    else if (arg === "--steward-report-out") out.stewardReportOut = argv[++i];
+    else if (arg === "--help" || arg === "-h") out.help = true;
+    else throw new Error(`unknown argument: ${arg}`);
+  }
+  return out;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+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 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 queryTerms(query) {
+  return [...new Set(String(query).toLowerCase().split(/[^a-z0-9_.$-]+/).filter((term) => term.length >= 3 && !STOPWORDS.has(term)))];
+}
+
+function scoreFile(file, terms, steward = {}) {
+  const haystack = [file.path, file.kind, file.language, ...(file.imports ?? []), ...(file.exports ?? [])].join(" ").toLowerCase();
+  const path = String(file.path ?? "").toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (haystack.includes(term)) score += 3;
+  }
+  for (const hint of steward.expectedFileHints ?? []) {
+    const normalizedHint = String(hint).toLowerCase();
+    if (normalizedHint && path.includes(normalizedHint)) score += 30;
+  }
+  if (terms.includes("queue") && file.kind === "queue") score += 8;
+  if ((terms.includes("worker") || terms.includes("job")) && file.kind === "worker") score += 8;
+  if ((terms.includes("route") || terms.includes("api") || terms.includes("controller")) && file.kind === "route") score += 8;
+  if (terms.includes("service") && file.kind === "service") score += 8;
+  if ((terms.includes("test") || terms.includes("testing") || terms.includes("vitest")) && file.kind === "test") score += 8;
+  if ((terms.includes("config") || terms.includes("configuration") || terms.includes("manifest")) && (file.kind === "config" || file.kind === "package-manifest" || file.kind === "schema")) score += 8;
+  if ((terms.includes("schema") || terms.includes("schemas")) && file.kind === "schema") score += 10;
+  if ((terms.includes("readme") || terms.includes("docs")) && (path.endsWith("readme.md") || file.language === "markdown")) score += 8;
+  if ((terms.includes("golden") || terms.includes("benchmark")) && path.includes("golden-cases")) score += 12;
+  if ((terms.includes("ontology") || terms.includes("pattern")) && path.includes("ontology")) score += 12;
+  return score;
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function readOptionalJson(path) {
+  if (!existsSync(path)) return undefined;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function loadOntology(scanDir) {
+  return readOptionalJson(join(scanDir, "ontology.json")) ?? readOptionalJson(resolve(repoRoot, ".pi/factories/project-dna/pi-agentic-ontology.json"));
+}
+
+function loadGoldenSuite(scanDir) {
+  return readOptionalJson(join(scanDir, "golden-cases-smoke.json")) ?? readOptionalJson(resolve(repoRoot, ".pi/factories/project-dna/golden-cases-smoke.json"));
+}
+
+function scoreConcept(concept, terms) {
+  const haystack = [concept.id, concept.kind, ...(concept.aliases ?? []), ...(concept.expected_file_hints ?? [])].join(" ").toLowerCase();
+  return terms.filter((term) => haystack.includes(term)).length;
+}
+
+function stewardExpansion(scanDir, query, goldenCaseId) {
+  const ontology = loadOntology(scanDir);
+  const suite = loadGoldenSuite(scanDir);
+  const terms = queryTerms(query);
+  const explicitCase = (suite?.cases ?? []).find((testCase) => testCase.id === goldenCaseId);
+  const matchedCase = explicitCase ?? (suite?.cases ?? [])
+    .map((testCase) => ({ testCase, score: terms.filter((term) => String(testCase.query ?? "").toLowerCase().includes(term) || String(testCase.intent_id ?? "").toLowerCase().includes(term)).length }))
+    .sort((left, right) => right.score - left.score)[0]?.testCase;
+  const matchedConcept = (ontology?.concepts ?? [])
+    .map((concept) => ({ concept, score: scoreConcept(concept, terms) + (concept.id === matchedCase?.intent_id ? 5 : 0) }))
+    .sort((left, right) => right.score - left.score)[0]?.concept;
+  const intentId = explicitCase?.intent_id ?? matchedCase?.intent_id ?? matchedConcept?.id ?? "project_dna.context_lookup";
+  const expectedPatterns = unique([...(matchedCase?.expected_patterns ?? []), intentId]);
+  const expectedFileHints = unique([...(matchedConcept?.expected_file_hints ?? []), ...(matchedCase?.required_files_to_read_first ?? []), ...(matchedCase?.required_citation_includes ?? [])]);
+  const controlledTerms = unique([intentId, ...(matchedConcept?.aliases ?? []), ...expectedFileHints].map((term) => String(term).toLowerCase()));
+  return {
+    intentId,
+    confidence: explicitCase ? "high" : matchedCase || matchedConcept ? "medium" : "low",
+    goldenCaseId: explicitCase?.id ?? matchedCase?.id ?? null,
+    expectedPatterns,
+    expectedFileHints,
+    controlledTerms,
+    ontologyId: ontology?.ontology_id ?? null,
+    suiteId: suite?.suite_id ?? null,
+  };
+}
+
+function writeStewardReport(outRel, scanDir, queryHash, steward) {
+  const outPath = resolveRepoPath(outRel, "--steward-report-out", true);
+  const scanDirRel = relative(repoRoot, scanDir).split(sep).join("/");
+  const report = {
+    schema: "zob.project-dna-query-steward-report.v1",
+    scan_dir: scanDirRel,
+    query_hash: queryHash,
+    raw_query_persisted: false,
+    query_stored: false,
+    intent: {
+      id: steward.intentId,
+      confidence: steward.confidence,
+      golden_case_id: steward.goldenCaseId,
+      ontology_id: steward.ontologyId,
+      suite_id: steward.suiteId,
+    },
+    controlled_expansion: {
+      stored_raw_terms: false,
+      term_hashes: steward.controlledTerms.map((term) => sha256(term)),
+      term_count: steward.controlledTerms.length,
+    },
+    expected_patterns: steward.expectedPatterns,
+    expected_file_hints: steward.expectedFileHints,
+    loading_rules: {
+      bounded_context_only: true,
+      citation_required: true,
+      agent_loads_entire_project: false,
+      writeback_policy: "proposal_only",
+    },
+    safety: {
+      source_project_modified: false,
+      knowledge_backend_write_enabled: false,
+      durable_promotion_allowed: false,
+    }
+  };
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+  return relative(repoRoot, outPath).split(sep).join("/");
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || !args.scanDir || !args.query) {
+    usage();
+    if (!args.help) process.exit(2);
+    return;
+  }
+  const scanDir = resolveRepoPath(args.scanDir, "--scan-dir");
+  const baseTerms = queryTerms(args.query);
+  const queryHash = sha256(args.query);
+  const steward = stewardExpansion(scanDir, args.query, args.goldenCaseId);
+  const terms = unique([...baseTerms, ...steward.controlledTerms]);
+  const stewardReportRef = args.stewardReportOut ? writeStewardReport(args.stewardReportOut, scanDir, queryHash, steward) : null;
+  const maxFiles = Number.isFinite(args.maxFiles) && args.maxFiles > 0 ? Math.min(20, Math.floor(args.maxFiles)) : 8;
+
+  const fingerprint = readJson(scanDir, "project-fingerprint.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 scored = (fileMap.files ?? [])
+    .map((file) => ({ file, score: scoreFile(file, terms, steward) }))
+    .filter((item) => item.score > 0)
+    .sort((left, right) => right.score - left.score || left.file.path.localeCompare(right.file.path));
+  const selected = (scored.length > 0 ? scored : (fileMap.files ?? []).slice(0, maxFiles).map((file) => ({ file, score: 0 }))).slice(0, maxFiles);
+  const selectedCitations = unique(selected.flatMap((item) => [...(item.file.symbol_citations ?? []), ...(item.file.citations ?? [])]));
+  const architecturePatternHits = (architectureMap.patterns ?? []).filter((pattern) => {
+    const id = String(pattern.id ?? "").toLowerCase();
+    return terms.some((term) => id.includes(term)) || steward.expectedPatterns.includes(pattern.id);
+  });
+  const stewardPatternHits = steward.expectedPatterns
+    .filter((id) => !architecturePatternHits.some((pattern) => pattern.id === id))
+    .map((id) => ({ id, confidence: steward.confidence, evidence: selectedCitations.slice(0, 3), stewarded: true }));
+  const patternHits = [...architecturePatternHits, ...stewardPatternHits];
+  const graphEdges = (graph.edges ?? []).filter((edge) => selected.some((item) => edge.to === `source:${item.file.path}` || edge.from === `source:${item.file.path}`)).slice(0, 20);
+  const broadCitations = selectedCitations.filter((citation) => {
+    const match = /:L(\d+)-L?(\d+)$/.exec(String(citation));
+    return match ? Number(match[2]) - Number(match[1]) + 1 > 250 : false;
+  });
+
+  const result = {
+    schema: "zob.project-dna-query-result.v1",
+    source_id: fingerprint.source_id,
+    scan_dir: relative(repoRoot, scanDir).split(sep).join("/"),
+    query_hash: queryHash,
+    query_stored: false,
+    query_terms_stored: false,
+    raw_query_persisted: false,
+    answer: selected.length > 0
+      ? "ProjectDNA Query Steward found bounded cited pointers in scan metadata. Read cited files before implementation."
+      : "ProjectDNA Query Steward did not find matching files; treat this as a context gap.",
+    query_steward: {
+      used: true,
+      intent_id: steward.intentId,
+      confidence: steward.confidence,
+      golden_case_id: steward.goldenCaseId,
+      report_ref: stewardReportRef,
+      raw_query_persisted: false,
+      controlled_expansion_terms_stored: false,
+      expected_patterns: steward.expectedPatterns,
+      expected_file_hint_count: steward.expectedFileHints.length,
+      controlled_expansion_term_hashes: steward.controlledTerms.map((term) => sha256(term)),
+    },
+    files_to_read_first: selected.map((item) => ({
+      path: item.file.path,
+      kind: item.file.kind,
+      score: item.score,
+      line_range: (item.file.primary_symbol_citation ?? item.file.citations?.[0])?.split(":").at(-1) ?? null,
+      reason: item.score > 0 ? "metadata_match" : "fallback_from_context_pack",
+      citations: unique([...(item.file.symbol_citations ?? []), ...(item.file.citations ?? [])]),
+    })),
+    citations: unique([...selectedCitations, ...(patternHits.flatMap((pattern) => pattern.evidence ?? [])), ...((contextPack.citations ?? []).slice(0, 4))]),
+    graph_edges: graphEdges,
+    pattern_hits: patternHits.map((pattern) => ({ id: pattern.id, confidence: pattern.confidence, evidence: pattern.evidence ?? [], stewarded: pattern.stewarded === true })),
+    citation_quality: {
+      citations_checked: selectedCitations.length,
+      broad_citation_count: broadCitations.length,
+      broad_citation_ratio: selectedCitations.length > 0 ? Number((broadCitations.length / selectedCitations.length).toFixed(3)) : 0,
+      prefers_symbol_ranges: true,
+    },
+    gaps: selected.length === 0 ? ["No files available in ProjectDNA file map."] : patternHits.length === 0 ? ["No ontology or architecture pattern id matched the query terms; use file-level citations only."] : [],
+    loading_rules: {
+      bounded_context_only: true,
+      citation_required: true,
+      agent_loads_entire_project: false,
+      writeback_policy: "proposal_only",
+    },
+    safety: {
+      scan_metadata_only: true,
+      source_project_modified: false,
+      knowledge_backend_write_enabled: false,
+    }
+  };
+
+  if (args.out) {
+    const outPath = resolveRepoPath(args.out, "--out", true);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+  }
+  console.log(JSON.stringify(result, null, 2));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(JSON.stringify({ schema: "zob.project-dna-query-error.v1", error: error instanceof Error ? error.message : String(error), source_project_modified: false, knowledge_backend_write_enabled: false }, null, 2));
+  process.exit(1);
+}