zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/budget-policy.ts

@@ -0,0 +1,308 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { evaluateBudgetPreflightDryRun } from "./chronicle.js";
+import type { BudgetPreflightDryRunCaps, FactoryRunBudgetInput } from "./types.js";
+import { sha256 } from "./utils/hashing.js";
+import { parseJsonFile } from "./utils/json.js";
+import { safeFileStem } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+
+const FORBIDDEN_BUDGET_BODY_KEYS = new Set(["task", "prompt", "output", "body", "content"]);
+const REQUIRED_CAP_KEYS: Array<keyof BudgetPreflightDryRunCaps> = ["maxCostUsd", "maxRuns", "maxDurationMs", "maxParallelChildren"];
+const REQUIRED_PROFILES = ["smoke", "pilot", "batch"];
+
+export interface BudgetReadinessAuditInput {
+  run_id?: string;
+}
+
+export interface StrictBudgetDispatchGateInput {
+  runId?: string;
+  mode?: string;
+  execution?: string;
+  taskCount?: number;
+  selectedItems?: number;
+  budget?: FactoryRunBudgetInput;
+}
+
+function hasForbiddenBodyKeys(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenBodyKeys);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => FORBIDDEN_BUDGET_BODY_KEYS.has(key) || hasForbiddenBodyKeys(child));
+}
+
+function finiteNonnegative(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function capsFromRecord(record: unknown): BudgetPreflightDryRunCaps | undefined {
+  if (!isRecord(record)) return undefined;
+  const caps: BudgetPreflightDryRunCaps = {};
+  for (const key of REQUIRED_CAP_KEYS) {
+    if (!finiteNonnegative(record[key])) return undefined;
+    caps[key] = record[key] as number;
+  }
+  return caps;
+}
+
+function readinessCheck(name: string, passed: boolean, detail: Record<string, unknown> = {}): Record<string, unknown> {
+  return { name, passed, detail };
+}
+
+function nonnegativeOrUndefined(value: unknown): number | undefined {
+  return finiteNonnegative(value) ? value : undefined;
+}
+
+export function evaluateStrictBudgetDispatchGate(input: StrictBudgetDispatchGateInput = {}): Record<string, unknown> {
+  const budget = isRecord(input.budget) ? input.budget as FactoryRunBudgetInput : undefined;
+  const caps: BudgetPreflightDryRunCaps = {
+    ...(nonnegativeOrUndefined(budget?.maxCostUsd) !== undefined ? { maxCostUsd: nonnegativeOrUndefined(budget?.maxCostUsd) } : {}),
+    ...(nonnegativeOrUndefined(budget?.maxRuns) !== undefined ? { maxRuns: nonnegativeOrUndefined(budget?.maxRuns) } : {}),
+    ...(nonnegativeOrUndefined(budget?.maxDurationMs) !== undefined ? { maxDurationMs: nonnegativeOrUndefined(budget?.maxDurationMs) } : {}),
+    ...(nonnegativeOrUndefined(budget?.maxParallelChildren) !== undefined ? { maxParallelChildren: nonnegativeOrUndefined(budget?.maxParallelChildren) } : {}),
+  };
+  const observed = {
+    costUsd: nonnegativeOrUndefined(budget?.estimatedCostUsd) ?? 0,
+    runs: nonnegativeOrUndefined(budget?.estimatedRuns) ?? Math.max(0, Math.floor(input.taskCount ?? 0)),
+    durationMs: nonnegativeOrUndefined(budget?.estimatedDurationMs) ?? 0,
+    parallelChildren: nonnegativeOrUndefined(budget?.estimatedParallelChildren) ?? 1,
+  };
+  const strictEnabled = budget?.strictEnabled === true;
+  const strictRequested = budget?.strictRequested === true || strictEnabled;
+  const preflight = evaluateBudgetPreflightDryRun({
+    costUsd: observed.costUsd,
+    runs: observed.runs,
+    durationMs: observed.durationMs,
+    parallelChildren: observed.parallelChildren,
+    caps,
+    strictRequested,
+  });
+  const failures = Array.isArray(preflight.failures) ? preflight.failures.filter((failure): failure is string => typeof failure === "string") : [];
+  const wouldBlockDispatch = strictEnabled && failures.length > 0;
+  return {
+    schema: "zob.strict-budget-dispatch-gate.v1",
+    runId: input.runId,
+    mode: input.mode,
+    execution: input.execution,
+    strictRequested,
+    strictEnabled,
+    budgetEnforced: strictEnabled,
+    caps,
+    observed,
+    checks: preflight.checks,
+    passed: failures.length === 0,
+    failures,
+    wouldExceed: failures.length > 0,
+    wouldBlockDispatch,
+    dispatchDecision: wouldBlockDispatch ? "block" : strictEnabled ? "allow_strict" : "allow_advisory",
+    childDispatchAllowed: strictEnabled && !wouldBlockDispatch,
+    stopCondition: wouldBlockDispatch ? "blocked" : "none",
+    defaultDispatchDecision: strictEnabled ? "gate_decides" : "allow",
+    advisoryFallback: !strictEnabled,
+    gateEvaluationOnly: true,
+    noExecution: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+function budgetSafetyPassed(result: Record<string, unknown>): boolean {
+  return result.dryRun === true
+    && result.mode === "advisory"
+    && result.advisory === true
+    && result.strictEnabled === false
+    && result.budgetEnforced === false
+    && result.wouldBlockDispatch === false
+    && result.defaultDispatchDecision === "allow"
+    && result.modelRouterUsed === false
+    && result.daemonStarted === false
+    && result.childDispatchAllowed === false
+    && result.noExecution === true;
+}
+
+export function validateBudgetPolicyConfig(repoRoot: string): Record<string, unknown> {
+  const configPath = join(repoRoot, ".pi", "budget-policy.json");
+  const errors: string[] = [];
+  let parsed: Record<string, unknown> | undefined;
+  let configHash: string | undefined;
+  if (!existsSync(configPath)) {
+    errors.push(".pi/budget-policy.json is missing");
+  } else {
+    try {
+      const raw = readFileSync(configPath, "utf8");
+      configHash = sha256(raw);
+      const value = parseJsonFile(configPath);
+      if (!isRecord(value)) errors.push("budget policy config must be a JSON object");
+      else parsed = value;
+    } catch (error) {
+      errors.push(`budget policy config could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  const defaultCaps = capsFromRecord(parsed?.defaultCaps);
+  const profiles = isRecord(parsed?.profiles) ? parsed.profiles : undefined;
+  const validProfiles: Record<string, BudgetPreflightDryRunCaps> = {};
+
+  if (parsed) {
+    if (parsed.schema !== "zob.budget-policy.v1") errors.push("budget policy schema must be zob.budget-policy.v1");
+    if (parsed.advisoryOnly !== true) errors.push("budget policy must keep advisoryOnly=true");
+    if (parsed.strictBudgetDispatchGateAvailable !== true) errors.push("budget policy must declare strictBudgetDispatchGateAvailable=true");
+    if (parsed.strictBudgetRequiresExplicitInput !== true) errors.push("budget policy must declare strictBudgetRequiresExplicitInput=true");
+    for (const flag of ["strictBudgetDefaultEnabled", "strictBudgetEnabled", "budgetEnforced", "wouldBlockDispatch", "modelRouterUsed", "childDispatchAllowed", "daemonStarted", "networkAccessed", "bodyStored", "promptBodiesStored", "outputBodiesStored"]) {
+      if (parsed[flag] !== false) errors.push(`budget policy must keep ${flag}=false`);
+    }
+    if (parsed.noExecution !== true) errors.push("budget policy must keep noExecution=true");
+    if (parsed.defaultDispatchDecision !== "allow") errors.push("budget policy defaultDispatchDecision must remain allow");
+    if (!defaultCaps) errors.push("budget policy requires complete nonnegative defaultCaps");
+    if (!profiles) {
+      errors.push("budget policy requires profiles object");
+    } else {
+      for (const profileName of REQUIRED_PROFILES) {
+        const caps = capsFromRecord(profiles[profileName]);
+        if (!caps) errors.push(`budget policy requires complete nonnegative profiles.${profileName}`);
+        else validProfiles[profileName] = caps;
+      }
+    }
+    if (!Array.isArray(parsed.futureStrictBudgetPrerequisites) || !parsed.futureStrictBudgetPrerequisites.every((item) => typeof item === "string") || parsed.futureStrictBudgetPrerequisites.length === 0) {
+      errors.push("budget policy requires futureStrictBudgetPrerequisites string array");
+    }
+    if (hasForbiddenBodyKeys(parsed)) errors.push("budget policy must not store raw task/prompt/output/body/content fields");
+  }
+
+  return {
+    schema: "zob.budget-policy-validation.v1",
+    path: ".pi/budget-policy.json",
+    present: existsSync(configPath),
+    valid: errors.length === 0,
+    errors,
+    configHash,
+    defaultCaps,
+    profiles: Object.keys(validProfiles).sort(),
+    advisoryOnly: parsed?.advisoryOnly === true,
+    strictBudgetDispatchGateAvailable: parsed?.strictBudgetDispatchGateAvailable === true,
+    strictBudgetRequiresExplicitInput: parsed?.strictBudgetRequiresExplicitInput === true,
+    strictBudgetDefaultEnabled: parsed?.strictBudgetDefaultEnabled === true,
+    strictBudgetEnabled: parsed?.strictBudgetEnabled === true,
+    budgetEnforced: parsed?.budgetEnforced === true,
+    wouldBlockDispatch: parsed?.wouldBlockDispatch === true,
+    modelRouterUsed: parsed?.modelRouterUsed === true,
+    childDispatchAllowed: parsed?.childDispatchAllowed === true,
+    daemonStarted: parsed?.daemonStarted === true,
+    networkAccessed: parsed?.networkAccessed === true,
+    noExecution: parsed?.noExecution === true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function buildBudgetReadinessAudit(repoRoot: string, input: BudgetReadinessAuditInput = {}): Record<string, unknown> {
+  const configValidation = validateBudgetPolicyConfig(repoRoot);
+  const defaultCaps = isRecord(configValidation.defaultCaps) ? configValidation.defaultCaps as BudgetPreflightDryRunCaps : { maxCostUsd: 1, maxRuns: 1, maxDurationMs: 1000, maxParallelChildren: 1 };
+  const scenarios = [
+    { name: "within_default_caps", input: { costUsd: 0.5, runs: 1, durationMs: 500, parallelChildren: 1, caps: defaultCaps } },
+    { name: "cost_exceeds_default_caps", input: { costUsd: Number(defaultCaps.maxCostUsd ?? 1) + 1, runs: 1, durationMs: 500, parallelChildren: 1, caps: defaultCaps } },
+    { name: "runs_exceed_default_caps", input: { costUsd: 0.5, runs: Number(defaultCaps.maxRuns ?? 1) + 1, durationMs: 500, parallelChildren: 1, caps: defaultCaps } },
+    { name: "duration_exceeds_default_caps", input: { costUsd: 0.5, runs: 1, durationMs: Number(defaultCaps.maxDurationMs ?? 1000) + 1, parallelChildren: 1, caps: defaultCaps } },
+    { name: "parallel_children_exceed_default_caps", input: { costUsd: 0.5, runs: 1, durationMs: 500, parallelChildren: Number(defaultCaps.maxParallelChildren ?? 1) + 1, caps: defaultCaps } },
+    { name: "strict_budget_request_inert", input: { costUsd: Number(defaultCaps.maxCostUsd ?? 1) + 1, runs: 1, durationMs: 500, parallelChildren: 1, caps: defaultCaps, strictRequested: true } },
+  ].map((scenario) => {
+    const result = evaluateBudgetPreflightDryRun(scenario.input);
+    return {
+      name: scenario.name,
+      inputHash: sha256(JSON.stringify(scenario.input)),
+      passed: result.passed,
+      wouldExceed: result.wouldExceed,
+      strictRequested: result.strictRequested,
+      strictEnabled: result.strictEnabled,
+      budgetEnforced: result.budgetEnforced,
+      wouldBlockDispatch: result.wouldBlockDispatch,
+      childDispatchAllowed: result.childDispatchAllowed,
+      noExecution: result.noExecution,
+      failures: result.failures,
+      safetyPassed: budgetSafetyPassed(result),
+    };
+  });
+  const strictScenario = scenarios.find((scenario) => scenario.name === "strict_budget_request_inert");
+  const strictGateScenarios = [
+    { name: "strict_gate_allows_within_caps", input: { runId: "strict-gate-allow", mode: "smoke", execution: "agentic", taskCount: 1, budget: { strictEnabled: true, maxRuns: 2, estimatedRuns: 1, maxParallelChildren: 1, estimatedParallelChildren: 1 } } },
+    { name: "strict_gate_blocks_exceedance", input: { runId: "strict-gate-block", mode: "smoke", execution: "agentic", taskCount: 3, budget: { strictEnabled: true, maxRuns: 2, estimatedRuns: 3, maxParallelChildren: 1, estimatedParallelChildren: 1 } } },
+    { name: "strict_gate_default_disabled_advisory", input: { runId: "strict-gate-default", mode: "smoke", execution: "agentic", taskCount: 3, budget: { strictRequested: true, maxRuns: 2, estimatedRuns: 3 } } },
+  ].map((scenario) => {
+    const result = evaluateStrictBudgetDispatchGate(scenario.input);
+    return {
+      name: scenario.name,
+      inputHash: sha256(JSON.stringify(scenario.input)),
+      strictRequested: result.strictRequested,
+      strictEnabled: result.strictEnabled,
+      budgetEnforced: result.budgetEnforced,
+      wouldExceed: result.wouldExceed,
+      wouldBlockDispatch: result.wouldBlockDispatch,
+      childDispatchAllowed: result.childDispatchAllowed,
+      dispatchDecision: result.dispatchDecision,
+      stopCondition: result.stopCondition,
+      noExecution: result.noExecution,
+      failures: result.failures,
+    };
+  });
+  const strictAllow = strictGateScenarios.find((scenario) => scenario.name === "strict_gate_allows_within_caps");
+  const strictBlock = strictGateScenarios.find((scenario) => scenario.name === "strict_gate_blocks_exceedance");
+  const strictDefault = strictGateScenarios.find((scenario) => scenario.name === "strict_gate_default_disabled_advisory");
+  const checks = [
+    readinessCheck("budget_policy_config_valid", configValidation.present === true && configValidation.valid === true, { configHash: configValidation.configHash, errors: configValidation.errors }),
+    readinessCheck("budget_dry_run_scenarios_safe", scenarios.every((scenario) => scenario.safetyPassed === true), { scenarioCount: scenarios.length }),
+    readinessCheck("budget_exceedances_detected", scenarios.filter((scenario) => String(scenario.name).includes("exceed")).every((scenario) => scenario.wouldExceed === true), { exceedanceScenarios: scenarios.filter((scenario) => String(scenario.name).includes("exceed")).map((scenario) => scenario.name) }),
+    readinessCheck("strict_budget_request_inert_without_enable", strictScenario?.wouldExceed === true && strictScenario.strictRequested === true && strictScenario.strictEnabled === false && strictScenario.budgetEnforced === false && strictScenario.wouldBlockDispatch === false, { scenario: strictScenario?.name }),
+    readinessCheck("strict_budget_dispatch_gate_blocks_when_enabled", strictAllow?.strictEnabled === true && strictAllow.budgetEnforced === true && strictAllow.wouldBlockDispatch === false && strictAllow.childDispatchAllowed === true && strictBlock?.strictEnabled === true && strictBlock.budgetEnforced === true && strictBlock.wouldBlockDispatch === true && strictBlock.childDispatchAllowed === false && strictBlock.stopCondition === "blocked", { allow: strictAllow?.dispatchDecision, block: strictBlock?.dispatchDecision }),
+    readinessCheck("strict_budget_default_disabled", strictDefault?.strictRequested === true && strictDefault.strictEnabled === false && strictDefault.budgetEnforced === false && strictDefault.wouldBlockDispatch === false && strictDefault.dispatchDecision === "allow_advisory", { scenario: strictDefault?.name }),
+    readinessCheck("budget_enforcement_integration_implemented", true, { reason: "strict budget dispatch gate is available and can block before live child dispatch when explicitly enabled" }),
+    readinessCheck("strict_budget_global_default_enabled", false, { reason: "global/default strict budget enforcement remains disabled until operator approval and broader autonomy gates are proven" }),
+  ];
+  const failedChecks = checks.filter((check) => check.passed !== true).map((check) => check.name);
+  const auditPassed = checks.filter((check) => check.name !== "strict_budget_global_default_enabled").every((check) => check.passed === true);
+  const report = {
+    schema: "zob.budget-readiness-audit.v1",
+    runId: input.run_id,
+    auditPassed,
+    readiness: failedChecks.length === 0 ? "strict_budget_enabled_globally" : "strict_gate_available_default_blocked",
+    strictBudgetBlocked: failedChecks.length > 0,
+    strictBudgetNoShip: true,
+    strictBudgetBlockers: [
+      "global/default strict budget enforcement remains disabled",
+      "strict dispatch blocking requires explicit per-run budget.strictEnabled=true",
+      "oracle review and explicit approval are required before enabling strict budgets by default",
+    ],
+    checks,
+    failedChecks,
+    scenarios,
+    strictGateScenarios,
+    config: configValidation,
+    strictBudgetDispatchGateAvailable: true,
+    strictBudgetRequiresExplicitInput: true,
+    budgetEnforced: false,
+    strictEnabled: false,
+    wouldBlockDispatch: false,
+    defaultDispatchDecision: "allow",
+    modelRouterUsed: false,
+    childDispatchAllowed: false,
+    daemonStarted: false,
+    networkAccessed: false,
+    noExecution: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+  if (hasForbiddenBodyKeys(report)) throw new Error("Budget readiness audit would store forbidden body keys");
+  return report;
+}
+
+export function writeBudgetReadinessAuditReport(repoRoot: string, runId = "budget-readiness", input: BudgetReadinessAuditInput = {}): string {
+  const dir = join(repoRoot, ".pi", "logs", "budget");
+  mkdirSync(dir, { recursive: true });
+  const outputPath = join(dir, `${safeFileStem(runId)}.json`);
+  writeFileSync(outputPath, JSON.stringify(buildBudgetReadinessAudit(repoRoot, { ...input, run_id: runId }), null, 2), "utf8");
+  return outputPath;
+}

package/.pi/extensions/zob-harness/src/capabilities.ts

@@ -0,0 +1,249 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+
+import { discoverAgents } from "./agents.js";
+import { getOutputContractDefinitions } from "./output-contracts.js";
+import { loadChainDefinition, listChainDefinitions } from "./topology/chains.js";
+import { sha256 } from "./utils/hashing.js";
+import { parseJsonFile } from "./utils/json.js";
+import { safeFileStem } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+import { readableZobResourcePath, readableZobResourcePaths } from "./utils/resources.js";
+
+export interface ReuseScoutInput {
+  query: string;
+  run_id?: string;
+  limit?: number;
+}
+
+type CapabilityKind = "agent" | "factory" | "chain" | "output_contract";
+
+interface CapabilityCandidate {
+  kind: CapabilityKind;
+  id: string;
+  sourcePath?: string;
+  summary: string;
+  searchText: string;
+  metadata: Record<string, unknown>;
+}
+
+const FORBIDDEN_BODY_KEYS = new Set(["task", "prompt", "output", "body", "content"]);
+
+function hasForbiddenBodyKeys(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenBodyKeys);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => FORBIDDEN_BODY_KEYS.has(key) || hasForbiddenBodyKeys(child));
+}
+
+function keywords(value: string): string[] {
+  const stop = new Set(["the", "and", "for", "with", "from", "that", "this", "into", "only", "zob", "agent", "factory"]);
+  return [...new Set(value.toLowerCase().split(/[^a-z0-9_]+/).filter((item) => item.length >= 3 && !stop.has(item)))].sort();
+}
+
+function repoRelative(repoRoot: string, path: string): string {
+  return relative(repoRoot, path).replace(/\\/g, "/");
+}
+
+function readJsonObject(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = parseJsonFile(path);
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function listFactoryNames(repoRoot: string): string[] {
+  const names = new Set<string>();
+  for (const dir of readableZobResourcePaths(repoRoot, "factories")) {
+    for (const name of readdirSync(dir)) {
+      if (existsSync(join(dir, name, "factory.json"))) names.add(name);
+    }
+  }
+  return [...names].sort();
+}
+
+function listOutputContractFiles(repoRoot: string): string[] {
+  const fileNames = new Set<string>();
+  for (const dir of readableZobResourcePaths(repoRoot, "output-contracts")) {
+    for (const name of readdirSync(dir)) {
+      if (name.endsWith(".json")) fileNames.add(name);
+    }
+  }
+  return [...fileNames].sort();
+}
+
+function capabilityCandidates(repoRoot: string): CapabilityCandidate[] {
+  const agents = discoverAgents(repoRoot, "project").map((agent) => ({
+    kind: "agent" as const,
+    id: agent.name,
+    sourcePath: repoRelative(repoRoot, agent.filePath),
+    summary: agent.description,
+    searchText: [agent.name, agent.description, agent.tools?.join(" ") ?? ""].join(" "),
+    metadata: {
+      tools: agent.tools ?? [],
+      source: agent.source,
+      modelClass: agent.model,
+      promptHash: sha256(agent.prompt),
+    },
+  }));
+
+  const factories = listFactoryNames(repoRoot).map((name) => {
+    const factoryPath = readableZobResourcePath(repoRoot, "factories", name, "factory.json");
+    const definition = readJsonObject(factoryPath) ?? {};
+    const stages = Array.isArray(definition.stages) ? definition.stages.filter(isRecord) : [];
+    const stageAgents = [...new Set(stages.map((stage) => String(stage.agent ?? "")).filter(Boolean))].sort();
+    const stageContracts = [...new Set(stages.map((stage) => String(stage.outputContract ?? "")).filter(Boolean))].sort();
+    const stageTypes = [...new Set(stages.map((stage) => String(stage.type ?? "")).filter(Boolean))].sort();
+    const manifests = ["smoke-manifest.json", "pilot-manifest.json", "batch-manifest.json"].filter((fileName) => existsSync(readableZobResourcePath(repoRoot, "factories", name, fileName)));
+    const description = typeof definition.description === "string" ? definition.description : "";
+    return {
+      kind: "factory" as const,
+      id: name,
+      sourcePath: repoRelative(repoRoot, factoryPath),
+      summary: description,
+      searchText: [name, description, stageAgents.join(" "), stageContracts.join(" "), stageTypes.join(" ")].join(" "),
+      metadata: {
+        version: definition.version,
+        defaultMode: definition.defaultMode,
+        stageTypes,
+        stageAgents,
+        outputContracts: stageContracts,
+        manifests,
+        expectedArtifacts: Array.isArray(definition.expectedArtifacts) ? definition.expectedArtifacts : [],
+      },
+    };
+  });
+
+  const chains = listChainDefinitions(repoRoot).map((name) => {
+    const loaded = loadChainDefinition(repoRoot, name);
+    const definition = loaded.definition;
+    const steps = definition?.steps ?? [];
+    const stepAgents = [...new Set(steps.map((step) => step.agent))].sort();
+    const stepContracts = [...new Set(steps.map((step) => step.outputContract))].sort();
+    return {
+      kind: "chain" as const,
+      id: name,
+      sourcePath: repoRelative(repoRoot, loaded.chainPath),
+      summary: definition?.description ?? "",
+      searchText: [name, definition?.description ?? "", stepAgents.join(" "), stepContracts.join(" ")].join(" "),
+      metadata: {
+        readOnly: definition?.readOnly ?? true,
+        defaultExecution: definition?.defaultExecution ?? "plan_only",
+        steps: steps.length,
+        stepAgents,
+        outputContracts: stepContracts,
+        definitionHash: definition ? sha256(JSON.stringify(definition)) : undefined,
+      },
+    };
+  });
+
+  const contractDefinitions = new Map(getOutputContractDefinitions().map((definition) => [definition.id, definition.required]));
+  const outputContracts = listOutputContractFiles(repoRoot).map((fileName) => {
+    const contractPath = readableZobResourcePath(repoRoot, "output-contracts", fileName);
+    const parsed = readJsonObject(contractPath) ?? {};
+    const id = typeof parsed.id === "string" ? parsed.id : basename(fileName, ".json");
+    const description = typeof parsed.description === "string" ? parsed.description : "";
+    const required = contractDefinitions.get(id) ?? [];
+    return {
+      kind: "output_contract" as const,
+      id,
+      sourcePath: repoRelative(repoRoot, contractPath),
+      summary: description,
+      searchText: [id, description, required.join(" ")].join(" "),
+      metadata: {
+        required,
+        contractHash: sha256(readFileSync(contractPath, "utf8")),
+      },
+    };
+  });
+
+  return [...agents, ...factories, ...chains, ...outputContracts].sort((left, right) => `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`));
+}
+
+export function buildCapabilityIndex(repoRoot: string): Record<string, unknown> {
+  const candidates = capabilityCandidates(repoRoot);
+  const byKind = candidates.reduce<Record<string, number>>((accumulator, candidate) => {
+    accumulator[candidate.kind] = (accumulator[candidate.kind] ?? 0) + 1;
+    return accumulator;
+  }, {});
+  const capabilities = candidates.map((candidate) => ({
+    kind: candidate.kind,
+    id: candidate.id,
+    sourcePath: candidate.sourcePath,
+    summary: candidate.summary,
+    keywords: keywords(candidate.searchText),
+    metadata: candidate.metadata,
+  }));
+  const index = {
+    schema: "zob.capability-index.v1",
+    counts: { total: capabilities.length, byKind },
+    capabilities,
+    noExecution: true,
+    childDispatchAllowed: false,
+    networkAccessed: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+  if (hasForbiddenBodyKeys(index)) throw new Error("Capability index would store forbidden body keys");
+  return index;
+}
+
+export function buildReuseScoutReport(repoRoot: string, input: ReuseScoutInput): Record<string, unknown> {
+  const queryKeywords = keywords(input.query);
+  const limit = Math.max(1, Math.min(20, Math.floor(input.limit ?? 10)));
+  const candidates = capabilityCandidates(repoRoot)
+    .map((candidate) => {
+      const candidateKeywords = keywords(candidate.searchText);
+      const overlap = candidateKeywords.filter((keyword) => queryKeywords.includes(keyword));
+      const kindBoost = candidate.kind === "factory" && queryKeywords.includes("factory") ? 2 : candidate.kind === "chain" && queryKeywords.includes("workflow") ? 2 : 0;
+      const score = overlap.length + kindBoost;
+      return {
+        kind: candidate.kind,
+        id: candidate.id,
+        sourcePath: candidate.sourcePath,
+        score,
+        reasonCodes: [...overlap.map((keyword) => `keyword:${keyword}`), ...(kindBoost > 0 ? [`kind_boost:${candidate.kind}`] : [])].sort(),
+        summaryHash: sha256(candidate.summary),
+        metadata: candidate.metadata,
+      };
+    })
+    .filter((candidate) => candidate.score > 0)
+    .sort((left, right) => right.score - left.score || `${left.kind}:${left.id}`.localeCompare(`${right.kind}:${right.id}`))
+    .slice(0, limit);
+  const report = {
+    schema: "zob.reuse-scout-report.v1",
+    queryHash: sha256(input.query),
+    queryKeywords,
+    candidates,
+    candidateCount: candidates.length,
+    noExecution: true,
+    childDispatchAllowed: false,
+    networkAccessed: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+  if (hasForbiddenBodyKeys(report)) throw new Error("Reuse scout report would store forbidden body keys");
+  return report;
+}
+
+export function writeCapabilityIndex(repoRoot: string, runId = "capability-index"): string {
+  const dir = join(repoRoot, ".pi", "logs", "capabilities");
+  mkdirSync(dir, { recursive: true });
+  const outputPath = join(dir, `${safeFileStem(runId)}.json`);
+  writeFileSync(outputPath, JSON.stringify(buildCapabilityIndex(repoRoot), null, 2), "utf8");
+  return outputPath;
+}
+
+export function writeReuseScoutReport(repoRoot: string, input: ReuseScoutInput): string {
+  const dir = join(repoRoot, ".pi", "logs", "capabilities");
+  mkdirSync(dir, { recursive: true });
+  const outputPath = join(dir, `${safeFileStem(input.run_id ?? "reuse-scout")}.json`);
+  writeFileSync(outputPath, JSON.stringify(buildReuseScoutReport(repoRoot, input), null, 2), "utf8");
+  return outputPath;
+}