zob-harness 0.5.0 → 0.6.0

package/.pi/capabilities/zob-public-runtime-capabilities.json

@@ -1010,6 +1010,28 @@
       ],
       "noShipNotes": "Proposal only; no direct command execution."
     },
+    {
+      "name": "zob_context_search",
+      "family": "context",
+      "modes": [
+        "explore",
+        "plan",
+        "implement",
+        "oracle",
+        "factory",
+        "orchestrator"
+      ],
+      "skillRefs": [
+        ".pi/skills/zob-context-discovery/SKILL.md",
+        ".pi/skills/zob-harness/SKILL.md"
+      ],
+      "docRefs": [
+        "reports/context-discovery/design.md",
+        "README.md",
+        "scripts/README.md"
+      ],
+      "noShipNotes": "Bounded repo-local context discovery only; prefer ColGREP when installed/ready, otherwise use grep/find/read fallback. Never auto-install ColGREP, run installer/network/package-manager commands, read forbidden/secret/session/vendor/build paths, persist raw secret/session bodies, inject stale/global/unbounded prompt context, or treat broad search hits as exact proof without grep/read/file-ref verification. Oracle/no-ship review must check freshness, citation coverage, and forbidden-source violations."
+    },
     {
       "name": "zob_context_readiness",
       "family": "context",

package/.pi/context-discovery.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": 1,
+  "preferredProvider": "colgrep",
+  "fallbackProvider": "grep",
+  "includePaths": [
+    ".pi/extensions",
+    ".pi/skills",
+    ".pi/capabilities",
+    "scripts",
+    "docs",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "excludePaths": [
+    ".env",
+    "**/.env",
+    ".env.*",
+    "**/*secret*",
+    "**/*key*",
+    "*.pem",
+    ".pi/sessions",
+    ".pi/agent-sessions",
+    "node_modules",
+    "dist",
+    "build"
+  ],
+  "limits": {
+    "maxResults": 20,
+    "maxContextLines": 2,
+    "maxFileBytes": 1048576
+  },
+  "promptInjection": {
+    "enabled": true,
+    "includeInstallHint": true
+  }
+}

package/.pi/extensions/zob-harness/src/domains/context/context-discovery.ts

@@ -0,0 +1,317 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, join, normalize, sep } from "node:path";
+
+export type ContextSearchMode = "auto" | "semantic" | "hybrid" | "regex" | "files";
+
+export interface ContextDiscoveryConfig {
+  schemaVersion: number;
+  preferredProvider: string;
+  fallbackProvider: string;
+  includePaths: string[];
+  excludePaths: string[];
+  limits: {
+    maxResults: number;
+    maxContextLines: number;
+    maxFileBytes: number;
+  };
+  promptInjection: {
+    enabled: boolean;
+    includeInstallHint: boolean;
+  };
+  loadedFrom: string;
+}
+
+export interface ContextSearchParams {
+  query: string;
+  mode?: ContextSearchMode;
+  pattern?: string;
+  paths?: string[];
+  max_results?: number;
+  max_context_lines?: number;
+  json?: boolean;
+}
+
+interface NormalizedContextResult {
+  path: string;
+  line?: number;
+  ref: string;
+  preview: string;
+  context?: Array<{ line: number; text: string }>;
+  score?: number;
+}
+
+const CONFIG_PATH = ".pi/context-discovery.json";
+const DEFAULT_CONFIG: ContextDiscoveryConfig = {
+  schemaVersion: 1,
+  preferredProvider: "colgrep",
+  fallbackProvider: "grep",
+  includePaths: [".pi/extensions", ".pi/skills", ".pi/capabilities", "scripts", "docs", "README.md", "AGENTS.md"],
+  excludePaths: [".env", "**/.env", ".env.*", "**/*secret*", "**/*key*", "*.pem", ".pi/sessions", ".pi/agent-sessions", "node_modules", "dist", "build"],
+  limits: { maxResults: 20, maxContextLines: 2, maxFileBytes: 1024 * 1024 },
+  promptInjection: { enabled: true, includeInstallHint: true },
+  loadedFrom: "defaults",
+};
+const TEXT_EXTENSIONS = new Set(["", ".cjs", ".css", ".js", ".json", ".md", ".mjs", ".sh", ".ts", ".tsx", ".txt", ".yaml", ".yml"]);
+
+function clampInteger(value: unknown, fallback: number, min: number, max: number): number {
+  const numberValue = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(numberValue)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numberValue)));
+}
+
+function shellQuote(value: string): string {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/gu, "\\$&")).join(".*");
+  return new RegExp(`^${escaped}$`, "iu");
+}
+
+export function normalizeRepoPath(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || raw.trim().length === 0) return undefined;
+  const trimmed = raw.trim().replace(/^\.\//u, "");
+  if (trimmed.includes("\0") || trimmed.includes("\\") || isAbsolute(trimmed)) return undefined;
+  const normalized = normalize(trimmed);
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`)) return undefined;
+  return normalized.split(sep).join("/");
+}
+
+function pathIsExcluded(relPath: string, excludePaths: string[]): boolean {
+  const normalized = normalizeRepoPath(relPath);
+  if (!normalized) return true;
+  return excludePaths.some((pattern) => {
+    const clean = normalizeRepoPath(pattern) ?? pattern;
+    if (clean.includes("*")) {
+      return globToRegExp(clean).test(normalized) || globToRegExp(clean.replace(/^\*\*\//u, "")).test(basename(normalized));
+    }
+    return normalized === clean || normalized.startsWith(`${clean}/`) || basename(normalized) === clean;
+  });
+}
+
+export function loadContextDiscoveryConfig(repoRoot: string): ContextDiscoveryConfig {
+  const path = join(repoRoot, CONFIG_PATH);
+  if (!existsSync(path)) return { ...DEFAULT_CONFIG };
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<ContextDiscoveryConfig>;
+    return {
+      ...DEFAULT_CONFIG,
+      ...parsed,
+      includePaths: Array.isArray(parsed.includePaths) ? parsed.includePaths.filter((item): item is string => typeof item === "string") : DEFAULT_CONFIG.includePaths,
+      excludePaths: Array.isArray(parsed.excludePaths) ? parsed.excludePaths.filter((item): item is string => typeof item === "string") : DEFAULT_CONFIG.excludePaths,
+      limits: { ...DEFAULT_CONFIG.limits, ...(parsed.limits ?? {}) },
+      promptInjection: { ...DEFAULT_CONFIG.promptInjection, ...(parsed.promptInjection ?? {}) },
+      loadedFrom: CONFIG_PATH,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG, loadedFrom: `${CONFIG_PATH}:unreadable-fallback-defaults` };
+  }
+}
+
+function commandExists(repoRoot: string, command: string): boolean {
+  if (process.env.ZOB_CONTEXT_FORCE_FALLBACK === "1") return false;
+  const result = spawnSync("sh", ["-c", `command -v ${shellQuote(command)}`], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 2_000 });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}
+
+export function detectColgrep(repoRoot: string): { provider: "colgrep" | "grep-fallback"; installed: boolean; ready: boolean; statusCode?: number | null; guidance: string } {
+  if (!commandExists(repoRoot, "colgrep")) {
+    return { provider: "grep-fallback", installed: false, ready: false, guidance: "ColGREP is not on PATH. Optional setup: install ColGREP manually, then run npm run zob:context:init. Grep/find fallback is active." };
+  }
+  const status = spawnSync("colgrep", ["status"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5_000 });
+  const ready = status.status === 0;
+  return {
+    provider: ready ? "colgrep" : "grep-fallback",
+    installed: true,
+    ready,
+    statusCode: status.status,
+    guidance: ready ? "ColGREP detected and ready." : "ColGREP is installed but not ready/indexed. Run npm run zob:context:init or inspect colgrep status. Grep/find fallback is active.",
+  };
+}
+
+export function buildActiveSearchBackendPromptSnippet(repoRoot: string): string {
+  const config = loadContextDiscoveryConfig(repoRoot);
+  if (!config.promptInjection.enabled) return "";
+  const detection = detectColgrep(repoRoot);
+  const scope = `${config.loadedFrom}; roots=${config.includePaths.slice(0, 6).join(",")}; excludes=${config.excludePaths.length}`;
+  if (detection.ready) {
+    return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: colgrep\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- Prefer zob_context_search for codebase discovery and broad/semantic search; use grep/read for exact proof and final citations.\n- Search output must stay bounded and avoid forbidden paths/secrets.`;
+  }
+  const installHint = config.promptInjection.includeInstallHint ? `\n- Optional ColGREP setup hint: ${detection.guidance}` : "";
+  return `\n\nZOB ACTIVE SEARCH BACKEND\n- active search backend: grep fallback\n- prompt injection: enabled by ${scope}; bounded per turn from current repo config, not a global/stale context pack.\n- Prefer zob_context_search, grep, find, and read for bounded repo-local discovery and exact proof.${installHint}\n- Missing ColGREP is not a blocker; do not auto-install it.`;
+}
+
+function safeSearchRoots(repoRoot: string, config: ContextDiscoveryConfig, requestedPaths?: string[]): { roots: string[]; rejected: string[] } {
+  const source = requestedPaths && requestedPaths.length > 0 ? requestedPaths : config.includePaths;
+  const roots: string[] = [];
+  const rejected: string[] = [];
+  for (const raw of source) {
+    const relPath = normalizeRepoPath(raw);
+    if (!relPath || pathIsExcluded(relPath, config.excludePaths)) {
+      rejected.push(String(raw));
+      continue;
+    }
+    if (!existsSync(join(repoRoot, relPath))) {
+      rejected.push(String(raw));
+      continue;
+    }
+    roots.push(relPath);
+  }
+  return { roots: [...new Set(roots)].sort(), rejected };
+}
+
+function looksTextFile(relPath: string): boolean {
+  return TEXT_EXTENSIONS.has(extname(relPath).toLowerCase());
+}
+
+function collectFiles(repoRoot: string, relPath: string, config: ContextDiscoveryConfig, out: string[]): void {
+  const safeRel = normalizeRepoPath(relPath);
+  if (!safeRel || pathIsExcluded(safeRel, config.excludePaths)) return;
+  const absolute = join(repoRoot, safeRel);
+  if (!existsSync(absolute)) return;
+  const stat = statSync(absolute);
+  if (stat.isFile()) {
+    if (stat.size <= config.limits.maxFileBytes && looksTextFile(safeRel)) out.push(safeRel);
+    return;
+  }
+  if (!stat.isDirectory()) return;
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) collectFiles(repoRoot, join(safeRel, entry.name), config, out);
+}
+
+function normalizeLineResult(repoRoot: string, item: Record<string, unknown>, config: ContextDiscoveryConfig): NormalizedContextResult | undefined {
+  const rawPath = item.path ?? item.file ?? item.filename ?? item.source_path;
+  const path = normalizeRepoPath(rawPath);
+  if (!path || pathIsExcluded(path, config.excludePaths) || !existsSync(join(repoRoot, path))) return undefined;
+  const lineValue = item.line ?? item.lineNumber ?? item.line_number ?? item.start_line;
+  const line = typeof lineValue === "number" ? Math.max(1, Math.floor(lineValue)) : undefined;
+  const rawPreview = item.preview ?? item.text ?? item.lineText ?? item.content ?? item.match ?? "";
+  const preview = String(rawPreview).replace(/\s+/gu, " ").trim().slice(0, 240);
+  const score = typeof item.score === "number" ? item.score : undefined;
+  return { path, line, ref: line ? `${path}:${line}` : path, preview, score };
+}
+
+function extractJsonResults(repoRoot: string, stdout: string, config: ContextDiscoveryConfig, maxResults: number): NormalizedContextResult[] {
+  try {
+    const parsed = JSON.parse(stdout) as unknown;
+    const container = Array.isArray(parsed) ? parsed : typeof parsed === "object" && parsed !== null ? parsed as Record<string, unknown> : {};
+    const candidates = Array.isArray(container) ? container : [container.results, container.matches, container.items].find(Array.isArray) ?? [];
+    return (candidates as unknown[]).filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null).map((item) => normalizeLineResult(repoRoot, item, config)).filter((item): item is NormalizedContextResult => Boolean(item)).slice(0, maxResults);
+  } catch {
+    return [];
+  }
+}
+
+function runColgrep(repoRoot: string, query: string, roots: string[], config: ContextDiscoveryConfig, maxResults: number, maxContextLines: number): { ok: boolean; results: NormalizedContextResult[]; error?: string } {
+  const args = ["--json", "-k", String(maxResults), "-n", String(maxContextLines), query, ...roots];
+  const result = spawnSync("colgrep", args, { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 10_000, maxBuffer: 1024 * 1024 });
+  if (result.status !== 0) return { ok: false, results: [], error: result.stderr.trim().slice(0, 240) || `colgrep exited ${String(result.status)}` };
+  const results = extractJsonResults(repoRoot, result.stdout, config, maxResults);
+  return { ok: true, results };
+}
+
+function fallbackSearch(repoRoot: string, params: Required<Pick<ContextSearchParams, "query" | "mode">> & Pick<ContextSearchParams, "pattern" | "paths">, config: ContextDiscoveryConfig, maxResults: number, maxContextLines: number): { results: NormalizedContextResult[]; rejectedPaths: string[]; roots: string[] } {
+  const { roots, rejected } = safeSearchRoots(repoRoot, config, params.paths);
+  const files: string[] = [];
+  for (const root of roots) collectFiles(repoRoot, root, config, files);
+  const needle = params.mode === "regex" ? params.pattern ?? params.query : params.query;
+  let regex: RegExp | undefined;
+  if (params.mode === "regex") {
+    try { regex = new RegExp(needle, "iu"); } catch { regex = undefined; }
+  }
+  const results: NormalizedContextResult[] = [];
+  for (const path of [...new Set(files)].sort()) {
+    if (results.length >= maxResults) break;
+    if (params.mode === "files") {
+      if (!path.toLowerCase().includes(params.query.toLowerCase())) continue;
+      results.push({ path, ref: path, preview: path });
+      continue;
+    }
+    const lines = readFileSync(join(repoRoot, path), "utf8").split(/\r?\n/u);
+    for (let index = 0; index < lines.length; index += 1) {
+      const matched = regex ? regex.test(lines[index]) : lines[index].toLowerCase().includes(params.query.toLowerCase());
+      if (!matched) continue;
+      const start = Math.max(0, index - maxContextLines);
+      const end = Math.min(lines.length, index + maxContextLines + 1);
+      results.push({
+        path,
+        line: index + 1,
+        ref: `${path}:${index + 1}`,
+        preview: lines[index].trim().slice(0, 240),
+        context: lines.slice(start, end).map((text, offset) => ({ line: start + offset + 1, text: text.slice(0, 240) })),
+      });
+      if (results.length >= maxResults) break;
+    }
+  }
+  return { results, rejectedPaths: rejected, roots };
+}
+
+export function runContextSearch(repoRoot: string, input: ContextSearchParams): Record<string, unknown> {
+  const config = loadContextDiscoveryConfig(repoRoot);
+  const query = String(input.query ?? "").trim();
+  const mode = input.mode ?? "auto";
+  const maxResults = clampInteger(input.max_results, config.limits.maxResults, 1, 50);
+  const maxContextLines = clampInteger(input.max_context_lines, config.limits.maxContextLines, 0, 5);
+  const detection = detectColgrep(repoRoot);
+  const { roots, rejected } = safeSearchRoots(repoRoot, config, input.paths);
+  let provider = detection.ready ? "colgrep" : "grep-fallback";
+  let fallback = !detection.ready;
+  let fallbackReason = detection.ready ? undefined : detection.guidance;
+  let results: NormalizedContextResult[] = [];
+  if (detection.ready && mode !== "regex" && mode !== "files") {
+    const colgrep = runColgrep(repoRoot, query, roots, config, maxResults, maxContextLines);
+    if (colgrep.ok) results = colgrep.results;
+    else {
+      provider = "grep-fallback";
+      fallback = true;
+      fallbackReason = colgrep.error ?? "ColGREP query failed; grep fallback used.";
+    }
+  } else if (detection.ready) {
+    provider = "grep-fallback";
+    fallback = true;
+    fallbackReason = `${mode} mode uses exact grep/find fallback for deterministic results.`;
+  }
+  if (fallback || results.length === 0) {
+    const fallbackResult = fallbackSearch(repoRoot, { query, mode, pattern: input.pattern, paths: input.paths }, config, maxResults, maxContextLines);
+    results = fallbackResult.results;
+  }
+  const refs = results.map((item) => item.ref);
+  return {
+    schema: "zob.context-search-result.v1",
+    provider,
+    preferredProvider: config.preferredProvider,
+    fallback,
+    fallbackReason,
+    colgrepInstalled: detection.installed,
+    colgrepReady: detection.ready,
+    mode,
+    resultCount: results.length,
+    refs,
+    results,
+    searchedRoots: roots,
+    rejectedPaths: rejected,
+    limits: { maxResults, maxContextLines },
+    recommendedVerification: refs.length > 0
+      ? [`grep -n ${shellQuote(query)} ${shellQuote(results[0]?.path ?? roots[0] ?? ".")}`, `read ${results[0]?.path ?? roots[0] ?? "."}`]
+      : [`grep -R -n ${shellQuote(query)} ${roots.map(shellQuote).join(" ") || "."}`, "find relevant safe paths, then read exact files"],
+    safety: { repoRelativeOnly: true, forbiddenPathsExcluded: config.excludePaths, rawPromptOrConversationPersisted: false, autoInstall: false },
+  };
+}
+
+export function formatContextSearchResult(result: Record<string, unknown>): string {
+  const provider = String(result.provider ?? "unknown");
+  const fallback = result.fallback === true ? "yes" : "no";
+  const count = typeof result.resultCount === "number" ? result.resultCount : 0;
+  const lines = [`zob_context_search: provider=${provider} fallback=${fallback} results=${count}`];
+  const reason = typeof result.fallbackReason === "string" ? result.fallbackReason : undefined;
+  if (reason) lines.push(`fallback_status: ${reason}`);
+  const results = Array.isArray(result.results) ? result.results.slice(0, 10) : [];
+  for (const item of results) {
+    if (typeof item !== "object" || item === null) continue;
+    const record = item as Record<string, unknown>;
+    lines.push(`- ${String(record.ref ?? record.path ?? "result")}: ${String(record.preview ?? "").slice(0, 240)}`);
+  }
+  const verification = Array.isArray(result.recommendedVerification) ? result.recommendedVerification.slice(0, 2).map(String) : [];
+  if (verification.length > 0) lines.push(`verify: ${verification.join(" ; ")}`);
+  return lines.join("\n");
+}

package/.pi/extensions/zob-harness/src/runtime/events.ts

@@ -4,6 +4,7 @@ import { Text } from "@earendil-works/pi-tui";
 
 import { EXTERNAL_PACKAGE_TOOLS_CONTRACT, MODE_PROMPTS, ZOB_COMPACTION_CONTINUITY_CONTRACT, ZOB_TOOL_ROUTING_CONTRACT } from "../core/constants.js";
 import { buildCurrentZobLivePeerCard } from "../domains/coms/coms-v2/identity.js";
+import { buildActiveSearchBackendPromptSnippet } from "../domains/context/context-discovery.js";
 import { buildZobLiveAckEnvelope, buildZobLiveErrorEnvelope, buildZobLivePongEnvelope } from "../domains/coms/coms-v2/envelope.js";
 import { appendLiveCompletedRef } from "../domains/coms/coms-v2/ledger-bridge.js";
 import { bindZobLocalEndpoint, makeZobLocalEndpoint, sendZobLocalEnvelope } from "../domains/coms/coms-v2/local-transport.js";
@@ -979,7 +980,7 @@ export function registerHarnessEvents(pi: ExtensionAPI, state: HarnessRuntimeSta
     }
   });
 
-  pi.on("before_agent_start", async (event) => {
+  pi.on("before_agent_start", async (event, ctx) => {
     const goalHint = state.activeGoal
       ? `\n\nZOB GOAL GATE\n- ORIGINAL_USER_ASK: ${state.activeGoal.originalUserAsk}\n- ACTIVE_GOAL: ${state.activeGoal.activeGoal}\n- EXPECTED_OUTPUT: ${state.activeGoal.expectedOutput}\n- CONSTRAINTS: ${state.activeGoal.constraints}\n- VALIDATION_EVIDENCE: ${state.activeGoal.validationEvidence}`
       : "\n\nZOB GOAL GATE\n- No active goal set. If the request is broad or multi-step, use /goal_gate first or restate ORIGINAL_USER_ASK / ACTIVE_GOAL explicitly before delegating.";
@@ -993,10 +994,11 @@ export function registerHarnessEvents(pi: ExtensionAPI, state: HarnessRuntimeSta
     const autonomyHint = `\n\n${formatInteractiveAutonomyPromptHint(state.autonomy)}`;
     const zagentHint = formatZagentPromptHint(state);
     const zpeerHint = buildZpeerAwarenessPrompt(state, state.zobLive.inbound?.repoRoot ?? process.cwd());
+    const activeSearchBackendHint = buildActiveSearchBackendPromptSnippet(ctx.cwd);
     if (state.activeMode === "vanilla") {
       return { systemPrompt: `${event.systemPrompt}\n\n${MODE_PROMPTS.vanilla}` };
     }
-    const contractHint = `\n\nZOB HARNESS OPERATING CONTRACT\n- Prefer Explore -> Plan -> Implement -> Oracle for non-trivial work.\n- Use the six-part contract for delegated work: TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT.\n- Do not claim completion without concrete evidence.\n- If output may truncate, prioritize verdict, blockers, and next steps over exhaustive listings.\n\n${SAME_AGENT_MODE_INTENT_PROMPT}\n\n${ZOB_TOOL_ROUTING_CONTRACT}\n\n${ZOB_COMPACTION_CONTINUITY_CONTRACT}\n\n${EXTERNAL_PACKAGE_TOOLS_CONTRACT}\n\n${MODE_PROMPTS[state.activeMode]}${goalHint}${runtimeGoalHint}${rulesHint}${autonomyHint}${zagentHint}${zpeerHint}`;
+    const contractHint = `\n\nZOB HARNESS OPERATING CONTRACT\n- Prefer Explore -> Plan -> Implement -> Oracle for non-trivial work.\n- Use the six-part contract for delegated work: TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT.\n- Do not claim completion without concrete evidence.\n- If output may truncate, prioritize verdict, blockers, and next steps over exhaustive listings.\n\n${SAME_AGENT_MODE_INTENT_PROMPT}\n\n${ZOB_TOOL_ROUTING_CONTRACT}\n\n${ZOB_COMPACTION_CONTINUITY_CONTRACT}\n\n${EXTERNAL_PACKAGE_TOOLS_CONTRACT}\n\n${MODE_PROMPTS[state.activeMode]}${goalHint}${runtimeGoalHint}${rulesHint}${autonomyHint}${zagentHint}${zpeerHint}${activeSearchBackendHint}`;
     return { systemPrompt: `${event.systemPrompt}${contractHint}` };
   });
 

package/.pi/extensions/zob-harness/src/runtime/schemas.ts

@@ -565,6 +565,15 @@ const ContextReadinessParams = Type.Object({
   runId: Type.Optional(Type.String({ description: "Optional run id for the metadata-only Context/GBrain P0 readiness audit." })),
 });
 
+const ContextSearchParams = Type.Object({
+  query: Type.String({ description: "Bounded repo-local context search query. Required for all modes." }),
+  mode: Type.Optional(StringEnum(["auto", "semantic", "hybrid", "regex", "files"] as const, { description: "Search mode. auto/semantic/hybrid prefer ColGREP when ready; regex/files use deterministic fallback.", default: "auto" })),
+  pattern: Type.Optional(Type.String({ description: "Optional regex pattern used when mode=regex. Defaults to query." })),
+  paths: Type.Optional(Type.Array(Type.String(), { description: "Optional repo-relative search roots. Forbidden/session/vendor/build paths are rejected by the helper." })),
+  max_results: Type.Optional(Type.Number({ description: "Maximum result count. Runtime clamps to safe bounds." })),
+  max_context_lines: Type.Optional(Type.Number({ description: "Context lines around fallback matches. Runtime clamps to safe bounds." })),
+});
+
 const ContextScopeValidateParams = Type.Object({
   runId: Type.String({ description: "Run id requiring a context_scope before lookup/context-pack injection." }),
   scopeId: Type.Optional(Type.String({ description: "Optional deterministic context scope id." })),
@@ -685,6 +694,7 @@ export {
   MissionControlProposeCommandParams,
   MissionControlSnapshotParams,
   ContextReadinessParams,
+  ContextSearchParams,
   ContextScopeValidateParams,
   ContextWritebackProposalParams,
   ProjectDnaReadinessParams,

package/.pi/extensions/zob-harness/src/runtime/tools-context.ts

@@ -2,6 +2,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import {
   ContextReadinessParams,
+  ContextSearchParams,
   ContextScopeValidateParams,
   ContextWritebackProposalParams,
 } from "./schemas.js";
@@ -11,6 +12,7 @@ import {
   validateContextScope,
   writeContextWritebackProposal,
 } from "../domains/context/context-gbrain.js";
+import { formatContextSearchResult, runContextSearch } from "../domains/context/context-discovery.js";
 
 export function registerContextTools(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -24,6 +26,24 @@ export function registerContextTools(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "zob_context_search",
+    label: "ZOB Context Search",
+    description: "Search bounded repo-local context through the active context backend. Prefers ColGREP when installed and ready, falls back to safe grep/find-style search, never auto-installs ColGREP, and excludes forbidden/session/vendor/build paths.",
+    promptSnippet: "Use zob_context_search for bounded repo-local discovery before broad grep/read; verify exact proof with grep/read on returned refs.",
+    promptGuidelines: [
+      "Call zob_context_search for codebase/context discovery when semantic or broad search is useful.",
+      "zob_context_search prefers ColGREP when ready and falls back to bounded grep when ColGREP is missing, not ready, or a query fails.",
+      "Never install ColGREP from this tool path; missing ColGREP is not a blocker.",
+      "Use returned refs as leads and verify final claims with exact read/grep evidence.",
+    ],
+    parameters: ContextSearchParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const result = runContextSearch(ctx.cwd, params);
+      return { content: [{ type: "text", text: formatContextSearchResult(result) }], details: result };
+    },
+  });
+
   pi.registerTool({
     name: "zob_context_validate_scope",
     label: "ZOB Context Scope Validate",

package/.pi/skills/zob-context-discovery/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: zob-context-discovery
+description: Use when running, documenting, or reviewing adaptive active search backend context discovery, including zob_context_search, optional ColGREP setup, and grep/find/read fallback behavior.
+---
+# ZOB Context Discovery Skill
+
+## When to use
+
+Use this skill for:
+- `zob_context_search` and `zob_context_*` discovery workflows.
+- Active search backend guidance in prompts, docs, or registry entries.
+- Optional ColGREP setup/doctor/query UX.
+- Reviews of context discovery safety, bounded search output, and exact evidence refs.
+
+## Active backend rules
+
+1. Prefer `zob_context_search` for repo-local discovery when the runtime tool is available.
+2. When ColGREP is installed and ready, use it as the preferred broad/semantic discovery backend.
+3. Always use grep/find/read or exact file refs for verification before making claims.
+4. When ColGREP is missing, unavailable, or not indexed, fall back to grep/find/read. Missing ColGREP is not a blocker for normal ZOB work.
+5. Do not auto-install ColGREP, run network/package-manager installer commands, or mutate user tooling without explicit owner approval.
+6. Keep search bounded to repo-local allowed paths and task-relevant globs.
+7. Never read forbidden paths or secret-like files, including `.env`, `**/.env`, `**/*secret*`, `**/*key*`, private keys, `.pi/sessions`, `.pi/agent-sessions`, `node_modules`, `dist`, or `build`.
+8. Persist only safe metadata/artifact refs for context packs. Do not persist raw secret/session bodies.
+
+## User setup and scripts
+
+- `npm run zob:context:doctor` checks the active backend, reports config/status, and prints install/setup guidance without installing anything.
+- `npm run zob:context:init` may initialize safe ColGREP settings/indexing only when ColGREP is already installed and the owner runs it deliberately.
+- `npm run zob:context:query -- <query>` runs a one-shot context query, preferring ColGREP when ready and using grep fallback otherwise.
+- `npm run smoke:context-discovery` validates deterministic fallback behavior and should pass even when ColGREP is absent.
+
+## Prompt injection posture
+
+- Active-backend prompt injection is controlled by `.pi/context-discovery.json` under `promptInjection.enabled`.
+- The injected block must stay concise, current-repo scoped, and bounded by the configured include/exclude roots; it is a discovery hint, not a context pack or evidence source.
+- Do not inject stale/global context or raw search results into the prompt. Use `zob_context_search` and then read exact files when details are needed.
+
+## Evidence expectations
+
+- Cite repo-relative paths and line refs when available.
+- Treat semantic/broad search hits as leads until exact grep/read verification confirms the behavior.
+- Include provider/fallback metadata in readiness claims when relevant.
+- If context discovery cannot search a required path because of scope or forbidden-path policy, report a blocker instead of broadening silently.
+
+## Oracle / no-ship criteria
+
+No-ship for context discovery if any of these remain true:
+- forbidden sources or secret/session/vendor/build paths are read, indexed intentionally, or returned as results;
+- ColGREP setup requires unapproved network/package-manager/installer commands;
+- missing ColGREP blocks normal ZOB operation instead of using fallback;
+- dynamic prompt injection includes stale/global context, raw search bodies, or unbounded output;
+- implementation claims rely on semantic hits without exact grep/read/file-ref verification;
+- context freshness or citation coverage cannot be shown for files used as evidence.

package/.pi/skills/zob-harness/SKILL.md

@@ -14,7 +14,7 @@ Use this skill for any task involving:
 - Software-factory design from repeated manual workflows.
 - Runtime tool/command routing via `.pi/capabilities/zob-public-runtime-capabilities.json`.
 
-For routing behavior, load `zob-tool-router` before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load `zob-compaction-policy` before changing compaction hooks or resuming from a compacted long-running goal. For domain behavior, load the domain skill named by the registry instead of inlining details here: `zob-goal-todo-tree`, `zob-coms-v2-live`, `zob-coms-safety`, `zob-mission-control-coms`, `zob-autonomous-runtime`, `zob-factory`, `zob-sandbox`, `zob-oracle`, or `zob-spec` as applicable.
+For routing behavior, load `zob-tool-router` before non-trivial or tool-ambiguous work. For compaction/recovery behavior, load `zob-compaction-policy` before changing compaction hooks or resuming from a compacted long-running goal. For active context discovery/search backend behavior, load `zob-context-discovery` and prefer `zob_context_search` when available, with ColGREP as the preferred ready backend and grep/find/read as exact-verification fallback. For domain behavior, load the domain skill named by the registry instead of inlining details here: `zob-goal-todo-tree`, `zob-coms-v2-live`, `zob-coms-safety`, `zob-mission-control-coms`, `zob-autonomous-runtime`, `zob-factory`, `zob-sandbox`, `zob-oracle`, or `zob-spec` as applicable.
 
 ## Agent Factory posture
 
@@ -34,7 +34,7 @@ Communication is a core deliverable. Prefer one parent-visible control room by d
 1. Classify the task as one of: `explore`, `plan`, `implement`, `oracle`, `factory`, `orchestrator`. When `.pi/routing/intent-classifier.json` enables an optional model classifier, treat it as advisory intent routing only; regex fallback and deterministic safety hard-blocks remain authoritative. `autoSwitchIntents` controls which detected intents switch mode directly; this project enables all ZOB modes by default. Use `/intent-classifier status|regex|model-strict|model-fallback|test` (alias `/intent`) to switch/test routing without editing JSON by hand.
 2. For non-trivial or tool-ambiguous work, apply `zob-tool-router`: classify applicable families, then use/delegate/skip each with a reason.
 3. Use `orchestrator` when the task needs Chief Vision coordination, multi-agent decomposition, Lead/Worker routing, goal/TODO graph governance, or parent-owned dispatch; the root should delegate substantive work rather than do it directly.
-4. Check `.pi/capabilities/zob-public-runtime-capabilities.json` for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes.
+4. Check `.pi/capabilities/zob-public-runtime-capabilities.json` for the relevant tool/command family, mode allowlist, skill refs, and no-ship notes. For context tasks, prefer the active backend via `zob_context_search`; use ColGREP when ready, and grep/find/read for fallback plus exact verification.
 5. If broad or risky, use the `delegate_agent` tool before editing.
 6. For delegated work, use the six-part contract:
    - TASK

package/AGENTS.md

@@ -49,7 +49,7 @@ Use the registry plus the domain skill instead of copying tool docs into prompts
 - Delegation/catalog: `zob_delegation_catalog`, `delegate_agent`, `delegate_task` -> `.pi/skills/zob-delegation-routing/SKILL.md` and `.pi/skills/zob-harness/SKILL.md`; call the catalog before first delegation when agent/contract/tool routing is uncertain, normally omit `delegate_task.output_contract` and `delegate_task.required_tools`, and never invent contract IDs or agent tools.
 - Live coms: `zob_coms_*` -> `.pi/skills/zob-coms-v2-live/SKILL.md` and `.pi/skills/zob-coms-safety/SKILL.md`; required-local delivery must be live, never append-only success.
 - Mission Control: `zob_mission_control_*` / readiness -> `.pi/skills/zob-mission-control-coms/SKILL.md`; command writes are proposals only.
-- Context: `zob_context_*` -> registry no-ship notes plus `.pi/skills/zob-harness/SKILL.md` / `.pi/skills/zob-spec/SKILL.md` as applicable.
+- Context: `zob_context_search`, `zob_context_*` -> registry no-ship notes plus `.pi/skills/zob-context-discovery/SKILL.md`, `.pi/skills/zob-harness/SKILL.md`, and `.pi/skills/zob-spec/SKILL.md` as applicable; prefer the active search backend (ColGREP when ready, grep/find/read fallback) and verify exact claims with file refs.
 - Compute profile / effort routing: `zob_compute_*`, `npm run preview:compute-profile:project-dna-smoke`, `npm run validate:compute-profile:project-dna-smoke` -> `.pi/skills/zob-compute-profile/SKILL.md`; preview/resolve/report tools are metadata-only and never bypass safety, budget, oracle, sandbox, or parent-owned dispatch gates.
 - Autonomy: `zob_autonomous_*` -> `.pi/skills/zob-autonomous-runtime/SKILL.md`; dry-run/readonly smoke/validation are supervised evidence only, not global autonomy completion.
 - Factory quarantine/run: `factory_quarantine_*`, `factory_run` -> `.pi/skills/zob-factory/SKILL.md` and `.pi/skills/zob-sandbox/SKILL.md`.

package/README.md

@@ -330,9 +330,22 @@ Durable records stay hash-only (`bodyStored=false` with TODO refs, receiver refs
 
 This release adds the handoff runtime/docs and `npm run smoke:goal-todo-handoff` validation. It does not auto-launch teams or auto-complete parent TODOs. Current npm release automation is handled separately by the CI/CD flow below; local agents still must not create tags, publish packages, commit, or push unless explicitly authorized through the governed workflow.
 
-### Use ProjectDNA context
+### Use active context discovery
 
-ProjectDNA turns approved local code scan artifacts into bounded, cited context packs and sample/spec outputs. Keep scans approved, artifacts local, and writeback proposal-only unless the parent explicitly authorizes more.
+ZOB can adapt context search to the active backend. Use `zob_context_search` inside Pi when available: it prefers ColGREP for broad/semantic repo discovery when ColGREP is installed and indexed, and falls back to grep/find/read when it is missing or unavailable. Treat broad search hits as leads and verify exact claims with file refs before editing or reporting readiness.
+
+ColGREP setup is optional and owner-driven; ZOB must not auto-install it or run installer/package-manager commands. Local helpers:
+
+```bash
+npm run zob:context:doctor        # read-only backend/config status and setup guidance
+npm run zob:context:init          # initialize safe ColGREP settings/index only if ColGREP is already installed
+npm run zob:context:query -- "goal todo routing"  # one-shot query with grep fallback
+npm run smoke:context-discovery   # deterministic fallback smoke; passes without ColGREP
+```
+
+Forbidden/secret/session/vendor/build paths remain excluded from discovery. Active-backend prompt injection is bounded and configurable through `.pi/context-discovery.json` (`promptInjection.enabled`); it should never inject stale/global context or raw search results. Oracle/no-ship review for this feature checks context freshness, citation coverage, exact grep/read verification, forbidden-source violations, and no unapproved installer/network behavior.
+
+See [`reports/context-discovery/design.md`](reports/context-discovery/design.md), [`.pi/skills/zob-context-discovery/SKILL.md`](.pi/skills/zob-context-discovery/SKILL.md), and [scripts/README.md](scripts/README.md) for the operating rules and script map.
 
 ### Use governed commits
 
@@ -430,6 +443,7 @@ npm run check -- --pretty false    # TypeScript validation baseline
 npm run check:ci                   # CI-style TypeScript check
 npm run validate:script-surface    # package script/file surface validation
 npm run smoke:harness              # path-policy + child-goal-ref smoke
+npm run smoke:context-discovery    # active context backend smoke with grep fallback
 npm run smoke:goal-todo-handoff    # Goal TODO ZPeer/ZTeam handoff static smoke
 npm run smoke:intent-classifier    # optional model intent-classifier fallback smoke
 npm run smoke:git-ops              # governed commit policy smoke
@@ -437,6 +451,9 @@ npm run smoke:worker-pool          # worker-pool static smoke
 npm run smoke:zpeer                # static + local ZPeer smoke
 npm run validate:project-dna       # ProjectDNA scaffold validation
 npm run pack:dry-run               # npm package dry-run surface check
+npm run zob:context:doctor         # active context backend status/guidance
+npm run zob:context:init           # optional ColGREP init when already installed
+npm run zob:context:query -- "..."  # one-shot active backend query
 npm run demo:pacman:prepare        # prepare Pac-Man factory run artifacts
 npm run demo:pacman:validate       # validate Pac-Man factory run artifacts
 npm run demo:pacman                # launch the full Pac-Man Agent Factory demo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zob-harness",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "A governed Agent Factory for Pi: launch communicating agent teams, run tmux-backed factories, validate artifacts, and package repeatable workflows.",
   "license": "MIT",
@@ -46,6 +46,7 @@
     ".pi/autonomy-policy.json",
     ".pi/budget-policy.json",
     ".pi/capabilities",
+    ".pi/context-discovery.json",
     ".pi/chains",
     ".pi/compute-profiles",
     ".pi/daemon-policy.json",
@@ -77,6 +78,7 @@
     "scripts/agentic-spec-team",
     "scripts/autonomy",
     "scripts/compute-profile",
+    "scripts/context-discovery",
     "scripts/git-ops",
     "scripts/goal-todo",
     "scripts/intent-classifier",
@@ -114,6 +116,10 @@
     "smoke:autonomy-readiness-secret": "node scripts/autonomy/mission-readiness-secret-smoke.mjs",
     "smoke:zpeer": "node scripts/zpeer-static-smoke.mjs && node scripts/zpeer-local-e2e-smoke.mjs",
     "smoke:zagent": "node scripts/zagent-static-smoke.mjs",
+    "zob:context:doctor": "node scripts/context-discovery/doctor.mjs",
+    "zob:context:init": "node scripts/context-discovery/init-colgrep.mjs",
+    "zob:context:query": "node scripts/context-discovery/query.mjs",
+    "smoke:context-discovery": "node scripts/context-discovery/smoke.mjs",
     "validate:script-surface": "node scripts/package-surface/validate-script-refs.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "release:preview": "node scripts/release/preview.mjs",

package/scripts/README.md

@@ -8,6 +8,7 @@ These script families are intended to be part of the normal tracked repo workflo
 
 - `scripts/autonomy/` — static/read-only autonomy readiness smokes.
 - `scripts/compute-profile/` — compute profile policy and regression checks.
+- `scripts/context-discovery/` — adaptive active search backend helpers: `npm run zob:context:doctor`, `npm run zob:context:init`, `npm run zob:context:query`, and `npm run smoke:context-discovery`; prefers ColGREP when installed/ready and validates grep fallback when it is absent.
 - `scripts/git-ops/` — governed `/zcommit` policy smokes.
 - `scripts/goal-todo/` — Goal/TODO tree compatibility smokes, including `scripts/goal-todo/handoff-static-smoke.mjs` coverage for the Goal TODO ZPeer/ZTeam handoff script (`npm run smoke:goal-todo-handoff`).
 - `scripts/harness-intake/` — natural-language harness setup/session analyzer that produces quarantined ZOB team/factory proposals plus tmux launch support.
@@ -53,6 +54,7 @@ Common safe checks:
 ```bash
 npm run validate:script-surface
 npm run validate:capability-refs
+npm run smoke:context-discovery
 npm run check -- --pretty false
 npm run smoke:harness
 ```
@@ -63,4 +65,6 @@ Run `npm run release:preview` before an authorized `/zcommit push` when you want
 
 Run `npm run validate:capability-refs` after changing `.pi/capabilities/zob-public-runtime-capabilities.json`, skills, docs, or runtime capability references. It verifies registry doc/skill refs resolve to repo-local files.
 
+Run `npm run smoke:context-discovery` after changing context-discovery docs, skills, config, or helpers. It is expected to pass without ColGREP by proving the grep fallback path.
+
 Run additional domain-specific smokes only when their source files are present and the task requires them.

package/scripts/context-discovery/doctor.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { detectColgrep, loadConfig, printJson } from "./shared.mjs";
+
+const config = loadConfig();
+const colgrep = detectColgrep();
+const report = {
+  ok: true,
+  mode: colgrep.ready ? "colgrep-ready" : "grep-fallback",
+  colgrep,
+  config: {
+    loadedFrom: config.loadedFrom,
+    includePaths: config.includePaths,
+    excludePaths: config.excludePaths,
+    limits: config.limits,
+    promptInjection: config.promptInjection,
+  },
+  guidance: colgrep.guidance,
+};
+
+if (process.argv.includes("--json")) {
+  printJson(report);
+} else {
+  console.log("ZOB context discovery doctor");
+  console.log(`mode: ${report.mode}`);
+  console.log(`config: ${config.loadedFrom}`);
+  console.log(`includePaths: ${config.includePaths.join(", ")}`);
+  console.log(`excludePaths: ${config.excludePaths.join(", ")}`);
+  console.log(`promptInjection: enabled=${String(config.promptInjection.enabled)} includeInstallHint=${String(config.promptInjection.includeInstallHint)}`);
+  console.log(`guidance: ${report.guidance}`);
+}
+
+process.exit(0);

package/scripts/context-discovery/init-colgrep.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { detectColgrep, loadConfig, printJson } from "./shared.mjs";
+
+const config = loadConfig();
+const colgrep = detectColgrep();
+
+if (!colgrep.installed) {
+  const report = {
+    ok: false,
+    action: "init-colgrep",
+    skipped: true,
+    reason: "colgrep-missing",
+    guidance: "ColGREP is not installed or not on PATH. This script will not auto-install it. Install ColGREP manually, then rerun npm run zob:context:init.",
+  };
+  if (process.argv.includes("--json")) {
+    printJson(report);
+  } else {
+    console.log(report.guidance);
+  }
+  process.exit(0);
+}
+
+const settingsArgs = [
+  "settings",
+  "--relative-paths",
+  "--force-include",
+  ".pi",
+  ...config.excludePaths.flatMap((pattern) => ["--ignore", pattern]),
+];
+const settings = spawnSync("colgrep", settingsArgs, {
+  cwd: process.cwd(),
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+const init = spawnSync("colgrep", ["init", "-y"], {
+  cwd: process.cwd(),
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+const ok = settings.status === 0 && init.status === 0;
+const report = {
+  ok,
+  action: "init-colgrep",
+  skipped: false,
+  settingsStatus: settings.status,
+  initStatus: init.status,
+  stdout: [settings.stdout, init.stdout].filter(Boolean).join("\n").trim(),
+  stderr: [settings.stderr, init.stderr].filter(Boolean).join("\n").trim(),
+  guidance: ok ? "ColGREP settings/init completed." : "ColGREP exists but settings/init failed; inspect stdout/stderr and run colgrep help/status manually.",
+};
+
+if (process.argv.includes("--json")) {
+  printJson(report);
+} else {
+  console.log(report.guidance);
+  if (report.stderr) {
+    console.log(report.stderr);
+  }
+}
+
+process.exit(ok ? 0 : 1);

package/scripts/context-discovery/query.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { detectColgrep, fallbackSearch, loadConfig, parseArgs, printHumanSearch, printJson } from "./shared.mjs";
+
+const args = parseArgs(process.argv.slice(2));
+const query = args.query ?? args.q ?? args._.join(" ");
+if (!query) {
+  console.error("usage: npm run zob:context:query -- --query <text> [--max-results 20] [--max-context-lines 2] [--json]");
+  process.exit(2);
+}
+
+const config = loadConfig();
+const maxResults = Math.max(1, Math.min(Number(args["max-results"] ?? config.limits.maxResults ?? 20), 100));
+const maxContextLines = Math.max(0, Math.min(Number(args["max-context-lines"] ?? config.limits.maxContextLines ?? 2), 5));
+const colgrep = detectColgrep();
+
+function runFallback(reason) {
+  return {
+    ...fallbackSearch({ query, config, maxResults, maxContextLines }),
+    reason,
+    colgrep,
+  };
+}
+
+let result;
+if (colgrep.ready) {
+  const colgrepArgs = ["--json", "-k", String(maxResults), "-n", String(maxContextLines), String(query), ...config.includePaths];
+  const colgrepResult = spawnSync("colgrep", colgrepArgs, {
+    cwd: process.cwd(),
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  if (colgrepResult.status === 0) {
+    result = {
+      provider: "colgrep",
+      fallback: false,
+      query,
+      resultCount: undefined,
+      raw: colgrepResult.stdout.trim(),
+      stderr: colgrepResult.stderr.trim(),
+      recommendedVerification: ["Use grep/read on returned repo-relative refs for exact proof."],
+    };
+  } else {
+    result = runFallback("colgrep-query-failed");
+    result.colgrepQueryStatus = colgrepResult.status;
+    result.colgrepQueryStderr = colgrepResult.stderr.trim();
+    result.colgrepArgs = colgrepArgs;
+  }
+} else {
+  result = runFallback(colgrep.installed ? "colgrep-not-ready" : "colgrep-missing");
+}
+
+if (args.json) {
+  printJson(result);
+} else if (result.provider === "colgrep") {
+  console.log("provider: colgrep");
+  console.log(result.raw);
+} else {
+  printHumanSearch(result);
+}

package/scripts/context-discovery/shared.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";
+
+export const repoRoot = process.cwd();
+export const configPath = ".pi/context-discovery.json";
+
+export const defaultConfig = {
+  schemaVersion: 1,
+  preferredProvider: "colgrep",
+  fallbackProvider: "grep",
+  includePaths: [
+    ".pi/extensions",
+    ".pi/skills",
+    ".pi/capabilities",
+    "scripts",
+    "docs",
+    "README.md",
+    "AGENTS.md",
+  ],
+  excludePaths: [
+    ".env",
+    "**/.env",
+    ".env.*",
+    "**/*secret*",
+    "**/*key*",
+    "*.pem",
+    ".pi/sessions",
+    ".pi/agent-sessions",
+    "node_modules",
+    "dist",
+    "build",
+  ],
+  limits: {
+    maxResults: 20,
+    maxContextLines: 2,
+    maxFileBytes: 1024 * 1024,
+  },
+  promptInjection: {
+    enabled: true,
+    includeInstallHint: true,
+  },
+};
+
+export function loadConfig() {
+  if (!existsSync(join(repoRoot, configPath))) {
+    return { ...defaultConfig, loadedFrom: "defaults" };
+  }
+  const parsed = JSON.parse(readFileSync(join(repoRoot, configPath), "utf8"));
+  return {
+    ...defaultConfig,
+    ...parsed,
+    includePaths: Array.isArray(parsed.includePaths) ? parsed.includePaths : defaultConfig.includePaths,
+    excludePaths: Array.isArray(parsed.excludePaths) ? parsed.excludePaths : defaultConfig.excludePaths,
+    limits: { ...defaultConfig.limits, ...(parsed.limits ?? {}) },
+    promptInjection: { ...defaultConfig.promptInjection, ...(parsed.promptInjection ?? {}) },
+    loadedFrom: configPath,
+  };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+export function commandExists(command) {
+  if (process.env.ZOB_CONTEXT_FORCE_FALLBACK === "1") {
+    return false;
+  }
+  const result = spawnSync("sh", ["-c", `command -v ${shellQuote(command)}`], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}
+
+export function detectColgrep() {
+  const installed = commandExists("colgrep");
+  if (!installed) {
+    return {
+      provider: "grep-fallback",
+      installed: false,
+      ready: false,
+      guidance: "ColGREP is not on PATH. Install/setup it manually if desired, then run npm run zob:context:init. Fallback search remains active.",
+    };
+  }
+
+  const status = spawnSync("colgrep", ["status"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  return {
+    provider: status.status === 0 ? "colgrep" : "grep-fallback",
+    installed: true,
+    ready: status.status === 0,
+    statusCode: status.status,
+    stdout: status.stdout?.trim() ?? "",
+    stderr: status.stderr?.trim() ?? "",
+    guidance: status.status === 0
+      ? "ColGREP detected and status check passed."
+      : "ColGREP is installed but not ready/indexed. Run npm run zob:context:init or inspect colgrep status output.",
+  };
+}
+
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      args._.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      index += 1;
+    }
+  }
+  return args;
+}
+
+export function normalizeRepoPath(raw) {
+  const normalized = normalize(String(raw).replace(/^\.\//u, ""));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith(`..${sep}`)) {
+    return null;
+  }
+  return normalized.split(sep).join("/");
+}
+
+function globToRegExp(pattern) {
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/gu, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${escaped}$`, "iu");
+}
+
+function isExcluded(relPath, excludePaths) {
+  const normalized = normalizeRepoPath(relPath);
+  if (!normalized) {
+    return true;
+  }
+  return excludePaths.some((pattern) => {
+    const clean = normalizeRepoPath(pattern) ?? pattern;
+    if (clean.includes("*")) {
+      return globToRegExp(clean).test(normalized) || globToRegExp(clean.replace(/^\*\*\//u, "")).test(basename(normalized));
+    }
+    return normalized === clean || normalized.startsWith(`${clean}/`) || basename(normalized) === clean;
+  });
+}
+
+function looksTextFile(relPath) {
+  const textExts = new Set(["", ".cjs", ".css", ".js", ".json", ".md", ".mjs", ".sh", ".ts", ".tsx", ".txt", ".yaml", ".yml"]);
+  return textExts.has(extname(relPath).toLowerCase());
+}
+
+function collectFiles(startRel, config, out) {
+  const safeRel = normalizeRepoPath(startRel);
+  if (!safeRel || isExcluded(safeRel, config.excludePaths)) {
+    return;
+  }
+  const absolute = join(repoRoot, safeRel);
+  if (!existsSync(absolute)) {
+    return;
+  }
+  const stat = statSync(absolute);
+  if (stat.isFile()) {
+    if (stat.size <= config.limits.maxFileBytes && looksTextFile(safeRel)) {
+      out.push(safeRel);
+    }
+    return;
+  }
+  if (!stat.isDirectory()) {
+    return;
+  }
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) {
+    collectFiles(join(safeRel, entry.name), config, out);
+  }
+}
+
+export function fallbackSearch({ query, config, maxResults, maxContextLines }) {
+  const files = [];
+  for (const includePath of config.includePaths) {
+    collectFiles(includePath, config, files);
+  }
+
+  const wanted = String(query ?? "").toLowerCase();
+  const results = [];
+  for (const relPath of [...new Set(files)].sort()) {
+    if (results.length >= maxResults) {
+      break;
+    }
+    const content = readFileSync(join(repoRoot, relPath), "utf8");
+    const lines = content.split(/\r?\n/u);
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+      if (!lines[lineIndex].toLowerCase().includes(wanted)) {
+        continue;
+      }
+      const start = Math.max(0, lineIndex - maxContextLines);
+      const end = Math.min(lines.length, lineIndex + maxContextLines + 1);
+      results.push({
+        path: relPath,
+        line: lineIndex + 1,
+        ref: `${relPath}:${lineIndex + 1}`,
+        preview: lines[lineIndex].trim().slice(0, 240),
+        context: lines.slice(start, end).map((text, offset) => ({ line: start + offset + 1, text: text.slice(0, 240) })),
+      });
+      if (results.length >= maxResults) {
+        break;
+      }
+    }
+  }
+
+  return {
+    provider: "grep-fallback",
+    fallback: true,
+    query,
+    maxResults,
+    maxContextLines,
+    resultCount: results.length,
+    results,
+    recommendedVerification: results.length
+      ? [`grep -n ${shellQuote(query)} ${shellQuote(results[0].path)}`, `read ${results[0].path}`]
+      : [`grep -R -n ${shellQuote(query)} ${config.includePaths.map(shellQuote).join(" ")}`],
+  };
+}
+
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function printHumanSearch(result) {
+  console.log(`provider: ${result.provider}`);
+  console.log(`fallback: ${result.fallback ? "yes" : "no"}`);
+  console.log(`results: ${result.resultCount}`);
+  for (const item of result.results ?? []) {
+    console.log(`- ${item.ref}: ${item.preview}`);
+  }
+}
+
+export function repoRelative(path) {
+  return relative(repoRoot, join(repoRoot, path)).split(sep).join("/");
+}

package/scripts/context-discovery/smoke.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const env = { ...process.env, ZOB_CONTEXT_FORCE_FALLBACK: "1" };
+const result = spawnSync(process.execPath, ["scripts/context-discovery/query.mjs", "--query", "ZOB Harness", "--json", "--max-results", "5"], {
+  cwd: process.cwd(),
+  env,
+  encoding: "utf8",
+  stdio: ["ignore", "pipe", "pipe"],
+});
+
+if (result.status !== 0) {
+  console.error("context-discovery smoke FAIL: query exited non-zero");
+  console.error(result.stderr || result.stdout);
+  process.exit(1);
+}
+
+let parsed;
+try {
+  parsed = JSON.parse(result.stdout);
+} catch (error) {
+  console.error("context-discovery smoke FAIL: query did not emit JSON");
+  console.error(result.stdout);
+  process.exit(1);
+}
+
+const hasAllowedRef = Array.isArray(parsed.results) && parsed.results.some((entry) => typeof entry.path === "string" && !entry.path.includes(".pi/sessions") && !entry.path.includes(".pi/agent-sessions") && !entry.path.includes("node_modules"));
+if (parsed.provider !== "grep-fallback" || parsed.fallback !== true || parsed.reason !== "colgrep-missing" || !hasAllowedRef) {
+  console.error("context-discovery smoke FAIL: fallback result did not match expectations");
+  console.error(JSON.stringify({ provider: parsed.provider, fallback: parsed.fallback, reason: parsed.reason, results: parsed.results }, null, 2));
+  process.exit(1);
+}
+
+console.log("context-discovery smoke PASS");
+console.log(`provider=${parsed.provider} reason=${parsed.reason} results=${parsed.resultCount}`);
+console.log(`evidence=${parsed.results.find((entry) => typeof entry.path === "string")?.ref}`);