zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/workspace-claims.ts

@@ -0,0 +1,297 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { DEFAULT_RULES } from "./constants.js";
+import type { TeamDefinition } from "./types.js";
+import { sha256 } from "./utils/hashing.js";
+import { readJsonl } from "./utils/json.js";
+import { pathMatches, resolveRepoPath, safeFileStem } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+
+export type WorkspaceClaimMode = "read" | "write";
+export type WorkspaceClaimStatus = "active" | "blocked_conflict";
+
+export interface WorkspaceClaimInput {
+  run_id: string;
+  claimant: string;
+  paths: string[];
+  mode?: WorkspaceClaimMode;
+  purpose_hash: string;
+  todo_id?: string;
+  sandbox_run_id?: string;
+  lease_ms?: number;
+  allow_conflicts?: boolean;
+}
+
+export interface WorkspaceReleaseInput {
+  claim_id: string;
+  released_by: string;
+  reason_hash?: string;
+}
+
+export interface WorkspaceClaimsListInput {
+  run_id?: string;
+  claimant?: string;
+  include_expired?: boolean;
+  include_released?: boolean;
+  limit?: number;
+}
+
+export interface WorkspaceClaimRecord {
+  schema: "zob.workspace-claim.v1";
+  claimId: string;
+  runId: string;
+  claimant: string;
+  todoId: string | null;
+  sandboxRunId: string | null;
+  mode: WorkspaceClaimMode;
+  status: WorkspaceClaimStatus;
+  paths: string[];
+  pathHashes: string[];
+  purposeHash: string;
+  leaseMs: number;
+  claimedAt: string;
+  expiresAt: string;
+  conflicts: WorkspaceConflictWarning[];
+  active: boolean;
+  parentOwnedResolutionRequired: boolean;
+  productionWritesPerformed: false;
+  autoApply: false;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface WorkspaceReleaseRecord {
+  schema: "zob.workspace-release.v1";
+  releaseId: string;
+  claimId: string;
+  releasedBy: string;
+  reasonHash: string | null;
+  releasedAt: string;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface WorkspaceConflictWarning {
+  schema: "zob.workspace-conflict-warning.v1";
+  claimId: string;
+  conflictingClaimIds: string[];
+  overlappingPaths: string[];
+  conflictHash: string;
+  parentOwnedResolutionRequired: true;
+  writesBlocked: true;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+const DEFAULT_LEASE_MS = 60 * 60 * 1000;
+const MAX_LEASE_MS = 24 * 60 * 60 * 1000;
+
+function workspaceClaimsDir(repoRoot: string): string {
+  return join(repoRoot, ".pi", "workspace-claims");
+}
+
+function claimsPath(repoRoot: string): string {
+  return join(workspaceClaimsDir(repoRoot), "claims.jsonl");
+}
+
+function releasesPath(repoRoot: string): string {
+  return join(workspaceClaimsDir(repoRoot), "releases.jsonl");
+}
+
+function eventsPath(repoRoot: string): string {
+  return join(workspaceClaimsDir(repoRoot), "events.jsonl");
+}
+
+function knownRoleIds(definition: TeamDefinition): Set<string> {
+  return new Set([definition.orchestrator.id, ...definition.leads.map((lead) => lead.id), ...definition.workers.map((worker) => worker.id), "parent", "mission-control"]);
+}
+
+function appendWorkspaceClaimEvent(repoRoot: string, event: Record<string, unknown>): void {
+  mkdirSync(workspaceClaimsDir(repoRoot), { recursive: true });
+  appendFileSync(eventsPath(repoRoot), `${JSON.stringify({ ...event, timestamp: new Date().toISOString(), bodyStored: false, promptBodiesStored: false, outputBodiesStored: false })}\n`, "utf8");
+}
+
+function validateClaimInput(repoRoot: string, definition: TeamDefinition, input: WorkspaceClaimInput): string[] {
+  const errors: string[] = [];
+  if (!input.run_id || safeFileStem(input.run_id) !== input.run_id) errors.push(`run_id must be path-safe: ${input.run_id}`);
+  if (input.todo_id && safeFileStem(input.todo_id) !== input.todo_id) errors.push(`todo_id must be path-safe: ${input.todo_id}`);
+  if (input.sandbox_run_id && safeFileStem(input.sandbox_run_id) !== input.sandbox_run_id) errors.push(`sandbox_run_id must be path-safe: ${input.sandbox_run_id}`);
+  if (!knownRoleIds(definition).has(input.claimant)) errors.push(`Unknown workspace claim claimant '${input.claimant}'`);
+  if (input.mode !== undefined && input.mode !== "read" && input.mode !== "write") errors.push("workspace claim mode must be read|write");
+  if (!SHA256_HEX.test(input.purpose_hash)) errors.push("workspace claim purpose_hash must be sha256 hex");
+  if (!Array.isArray(input.paths) || input.paths.length === 0) errors.push("workspace claim requires at least one path");
+  if (input.paths.length > 50) errors.push("workspace claim paths are capped at 50");
+  for (const path of input.paths ?? []) {
+    if (typeof path !== "string" || path.trim().length === 0) {
+      errors.push("workspace claim contains an empty path");
+      continue;
+    }
+    const resolved = resolveRepoPath(repoRoot, path);
+    errors.push(...resolved.errors.map((error) => `workspace claim path: ${error}`));
+    for (const protectedPattern of DEFAULT_RULES.zeroAccessPaths) {
+      if (pathMatches(path, protectedPattern, repoRoot, repoRoot)) errors.push(`workspace claim path references zero-access path: ${protectedPattern}`);
+    }
+  }
+  if (input.lease_ms !== undefined && (!Number.isFinite(input.lease_ms) || input.lease_ms <= 0 || input.lease_ms > MAX_LEASE_MS)) errors.push("workspace claim lease_ms must be positive and <= 24h");
+  return errors;
+}
+
+function normalizedPath(repoRoot: string, path: string): string {
+  return resolveRepoPath(repoRoot, path).path.replace(/\/+$/g, "");
+}
+
+function pathsOverlap(repoRoot: string, left: string, right: string): boolean {
+  const a = normalizedPath(repoRoot, left);
+  const b = normalizedPath(repoRoot, right);
+  return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+
+function isReleased(claimId: string, releases: WorkspaceReleaseRecord[]): boolean {
+  return releases.some((release) => release.claimId === claimId);
+}
+
+function isExpired(claim: WorkspaceClaimRecord, nowMs = Date.now()): boolean {
+  const expiresAt = Date.parse(claim.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt <= nowMs;
+}
+
+function readClaims(repoRoot: string): WorkspaceClaimRecord[] {
+  return readJsonl(claimsPath(repoRoot)).filter(isWorkspaceClaimRecord).map((record) => record as unknown as WorkspaceClaimRecord);
+}
+
+function readReleases(repoRoot: string): WorkspaceReleaseRecord[] {
+  return readJsonl(releasesPath(repoRoot)).filter(isWorkspaceReleaseRecord).map((record) => record as unknown as WorkspaceReleaseRecord);
+}
+
+function activeClaims(repoRoot: string, nowMs = Date.now()): WorkspaceClaimRecord[] {
+  const releases = readReleases(repoRoot);
+  return readClaims(repoRoot).filter((claim) => claim.status === "active" && !isExpired(claim, nowMs) && !isReleased(claim.claimId, releases));
+}
+
+function conflictWarnings(repoRoot: string, claimId: string, paths: string[], mode: WorkspaceClaimMode): WorkspaceConflictWarning[] {
+  if (mode !== "write") return [];
+  const conflicts = activeClaims(repoRoot).flatMap((claim) => {
+    const overlaps = paths.filter((path) => claim.paths.some((claimedPath) => pathsOverlap(repoRoot, path, claimedPath)));
+    if (overlaps.length === 0) return [];
+    return [{ claim, overlaps }];
+  });
+  if (conflicts.length === 0) return [];
+  const overlappingPaths = [...new Set(conflicts.flatMap((conflict) => conflict.overlaps))].sort();
+  const conflictingClaimIds = conflicts.map((conflict) => conflict.claim.claimId).sort();
+  return [{
+    schema: "zob.workspace-conflict-warning.v1",
+    claimId,
+    conflictingClaimIds,
+    overlappingPaths,
+    conflictHash: sha256(JSON.stringify({ claimId, conflictingClaimIds, overlappingPaths })),
+    parentOwnedResolutionRequired: true,
+    writesBlocked: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  }];
+}
+
+export function createWorkspaceClaim(repoRoot: string, definition: TeamDefinition, input: WorkspaceClaimInput): WorkspaceClaimRecord {
+  const errors = validateClaimInput(repoRoot, definition, input);
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  const now = Date.now();
+  const leaseMs = Math.floor(input.lease_ms ?? DEFAULT_LEASE_MS);
+  const claimId = `wclaim_${sha256(`${input.run_id}:${input.claimant}:${input.paths.join("|")}:${input.purpose_hash}:${now}`).slice(0, 16)}`;
+  const mode = input.mode ?? "write";
+  const conflicts = conflictWarnings(repoRoot, claimId, input.paths, mode);
+  const blocked = conflicts.length > 0 && input.allow_conflicts !== true;
+  const record: WorkspaceClaimRecord = {
+    schema: "zob.workspace-claim.v1",
+    claimId,
+    runId: input.run_id,
+    claimant: input.claimant,
+    todoId: input.todo_id ?? null,
+    sandboxRunId: input.sandbox_run_id ?? null,
+    mode,
+    status: blocked ? "blocked_conflict" : "active",
+    paths: [...new Set(input.paths)].sort(),
+    pathHashes: [...new Set(input.paths)].sort().map((path) => sha256(path)),
+    purposeHash: input.purpose_hash,
+    leaseMs,
+    claimedAt: new Date(now).toISOString(),
+    expiresAt: new Date(now + leaseMs).toISOString(),
+    conflicts,
+    active: !blocked,
+    parentOwnedResolutionRequired: blocked,
+    productionWritesPerformed: false,
+    autoApply: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  mkdirSync(workspaceClaimsDir(repoRoot), { recursive: true });
+  if (!blocked) appendFileSync(claimsPath(repoRoot), `${JSON.stringify(record)}\n`, "utf8");
+  appendWorkspaceClaimEvent(repoRoot, { event: blocked ? "conflict_blocked" : "claim_active", claimId, runId: record.runId, claimant: record.claimant, mode: record.mode, paths: record.paths, conflicts, productionWritesPerformed: false, autoApply: false });
+  return record;
+}
+
+export function releaseWorkspaceClaim(repoRoot: string, definition: TeamDefinition, input: WorkspaceReleaseInput): WorkspaceReleaseRecord {
+  if (!input.claim_id || safeFileStem(input.claim_id) !== input.claim_id) throw new Error(`claim_id must be path-safe: ${input.claim_id}`);
+  if (!knownRoleIds(definition).has(input.released_by)) throw new Error(`Unknown workspace release actor '${input.released_by}'`);
+  if (input.reason_hash !== undefined && !SHA256_HEX.test(input.reason_hash)) throw new Error("workspace release reason_hash must be sha256 hex");
+  const claim = readClaims(repoRoot).find((candidate) => candidate.claimId === input.claim_id);
+  if (!claim) throw new Error(`workspace claim not found: ${input.claim_id}`);
+  const record: WorkspaceReleaseRecord = {
+    schema: "zob.workspace-release.v1",
+    releaseId: `wrelease_${sha256(`${input.claim_id}:${input.released_by}:${Date.now()}`).slice(0, 16)}`,
+    claimId: input.claim_id,
+    releasedBy: input.released_by,
+    reasonHash: input.reason_hash ?? null,
+    releasedAt: new Date().toISOString(),
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  mkdirSync(workspaceClaimsDir(repoRoot), { recursive: true });
+  appendFileSync(releasesPath(repoRoot), `${JSON.stringify(record)}\n`, "utf8");
+  appendWorkspaceClaimEvent(repoRoot, { event: "claim_released", claimId: record.claimId, releaseId: record.releaseId, releasedBy: record.releasedBy });
+  return record;
+}
+
+export function listWorkspaceClaims(repoRoot: string, input: WorkspaceClaimsListInput = {}): WorkspaceClaimRecord[] {
+  const releases = readReleases(repoRoot);
+  const limit = Math.max(1, Math.min(100, Math.floor(input.limit ?? 20)));
+  return readClaims(repoRoot)
+    .filter((claim) => !input.run_id || claim.runId === input.run_id)
+    .filter((claim) => !input.claimant || claim.claimant === input.claimant)
+    .filter((claim) => input.include_expired === true || !isExpired(claim))
+    .filter((claim) => input.include_released === true || !isReleased(claim.claimId, releases))
+    .slice(-limit);
+}
+
+export function workspaceClaimBodyFreeViolations(value: unknown): string[] {
+  const forbidden = new Set(["body", "task", "prompt", "output", "content", "patch", "diff"]);
+  const violations: string[] = [];
+  const visit = (item: unknown, path: string): void => {
+    if (!item || typeof item !== "object") return;
+    if (Array.isArray(item)) {
+      item.forEach((child, index) => visit(child, `${path}[${index}]`));
+      return;
+    }
+    for (const [key, child] of Object.entries(item as Record<string, unknown>)) {
+      if (forbidden.has(key)) violations.push(`${path}.${key}`);
+      visit(child, `${path}.${key}`);
+    }
+  };
+  visit(value, "root");
+  return violations;
+}
+
+export function isWorkspaceClaimRecord(value: unknown): value is WorkspaceClaimRecord {
+  return isRecord(value) && value.schema === "zob.workspace-claim.v1" && typeof value.claimId === "string" && typeof value.runId === "string" && Array.isArray(value.paths) && value.bodyStored === false && value.productionWritesPerformed === false && value.autoApply === false;
+}
+
+export function isWorkspaceReleaseRecord(value: unknown): value is WorkspaceReleaseRecord {
+  return isRecord(value) && value.schema === "zob.workspace-release.v1" && typeof value.claimId === "string" && value.bodyStored === false;
+}

package/.pi/extensions/zob-switch/index.ts

@@ -0,0 +1,180 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+
+const SETTINGS_PATH = join(".pi", "settings.json");
+const SNAPSHOT_PATH = join(".pi", "tmp", "zob-switch", "settings-snapshot.json");
+const SWITCH_EXTENSION = "extensions/zob-switch/index.ts";
+const HARNESS_EXTENSION = "extensions/zob-harness/index.ts";
+const ZOB_PROMPTS = "prompts";
+const ZOB_SKILLS = "skills";
+
+type JsonObject = Record<string, unknown>;
+
+type Snapshot = {
+  schema: "zob.harness-switch.settings-snapshot.v1";
+  savedAt: string;
+  settings: JsonObject;
+};
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function uniqueWithRequiredFirst(values: string[], requiredFirst: string[]): string[] {
+  const result: string[] = [];
+  for (const value of [...requiredFirst, ...values]) {
+    if (!result.includes(value)) result.push(value);
+  }
+  return result;
+}
+
+function withoutValues(values: string[], remove: string[]): string[] {
+  return values.filter((value) => !remove.includes(value));
+}
+
+function hasValue(settings: JsonObject, key: "extensions" | "prompts" | "skills", value: string): boolean {
+  return asStringArray(settings[key]).includes(value);
+}
+
+async function readSettings(cwd: string): Promise<JsonObject> {
+  const raw = await readFile(join(cwd, SETTINGS_PATH), "utf8");
+  const parsed = JSON.parse(raw) as unknown;
+  if (!isObject(parsed)) throw new Error(`${SETTINGS_PATH} must contain a JSON object`);
+  return parsed;
+}
+
+async function writeSettings(cwd: string, settings: JsonObject): Promise<void> {
+  await writeFile(join(cwd, SETTINGS_PATH), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+
+async function writeSnapshot(cwd: string, settings: JsonObject): Promise<void> {
+  const snapshot: Snapshot = {
+    schema: "zob.harness-switch.settings-snapshot.v1",
+    savedAt: new Date().toISOString(),
+    settings,
+  };
+  const snapshotPath = join(cwd, SNAPSHOT_PATH);
+  await mkdir(dirname(snapshotPath), { recursive: true });
+  await writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+}
+
+async function readSnapshot(cwd: string): Promise<Snapshot | null> {
+  const snapshotPath = join(cwd, SNAPSHOT_PATH);
+  if (!existsSync(snapshotPath)) return null;
+  const parsed = JSON.parse(await readFile(snapshotPath, "utf8")) as unknown;
+  if (!isObject(parsed) || parsed.schema !== "zob.harness-switch.settings-snapshot.v1" || !isObject(parsed.settings)) {
+    throw new Error(`${SNAPSHOT_PATH} is not a valid ZOB switch snapshot`);
+  }
+  return parsed as Snapshot;
+}
+
+function shouldWriteOffSnapshot(current: JsonObject, snapshot: Snapshot | null): boolean {
+  return snapshot === null || hasValue(current, "extensions", HARNESS_EXTENSION);
+}
+
+function buildOffSettings(current: JsonObject): JsonObject {
+  return {
+    ...current,
+    extensions: uniqueWithRequiredFirst(withoutValues(asStringArray(current.extensions), [HARNESS_EXTENSION]), [SWITCH_EXTENSION]),
+    prompts: withoutValues(asStringArray(current.prompts), [ZOB_PROMPTS]),
+    skills: withoutValues(asStringArray(current.skills), [ZOB_SKILLS]),
+  };
+}
+
+function buildOnSettings(base: JsonObject, usedSnapshot: boolean): JsonObject {
+  return {
+    ...base,
+    extensions: uniqueWithRequiredFirst(asStringArray(base.extensions), [SWITCH_EXTENSION, HARNESS_EXTENSION]),
+    prompts: usedSnapshot ? asStringArray(base.prompts) : uniqueWithRequiredFirst(asStringArray(base.prompts), [ZOB_PROMPTS]),
+    skills: usedSnapshot ? asStringArray(base.skills) : uniqueWithRequiredFirst(asStringArray(base.skills), [ZOB_SKILLS]),
+  };
+}
+
+function statusFor(settings: JsonObject, snapshotPresent: boolean): string {
+  const switchConfigured = hasValue(settings, "extensions", SWITCH_EXTENSION);
+  const harnessConfigured = hasValue(settings, "extensions", HARNESS_EXTENSION);
+  const promptsConfigured = hasValue(settings, "prompts", ZOB_PROMPTS);
+  const skillsConfigured = hasValue(settings, "skills", ZOB_SKILLS);
+  const state = switchConfigured && harnessConfigured && promptsConfigured && skillsConfigured
+    ? "on"
+    : switchConfigured && !harnessConfigured && !promptsConfigured && !skillsConfigured
+      ? "off"
+      : "partial";
+  return [
+    `ZOB Harness switch: ${state}`,
+    `switch extension: ${switchConfigured ? "configured" : "missing"}`,
+    `harness extension: ${harnessConfigured ? "configured" : "missing"}`,
+    `prompts: ${promptsConfigured ? "configured" : "missing"}`,
+    `skills: ${skillsConfigured ? "configured" : "missing"}`,
+    `snapshot: ${snapshotPresent ? "present" : "missing"}`,
+  ].join("\n");
+}
+
+function argumentCompletions(prefix: string): AutocompleteItem[] | null {
+  const query = prefix.trim().toLowerCase();
+  const items: AutocompleteItem[] = [
+    { value: "on", label: "on", description: "restore ZOB Harness from snapshot/defaults and reload" },
+    { value: "off", label: "off", description: "snapshot settings, unload ZOB Harness resources, and reload" },
+    { value: "status", label: "status", description: "show switch/harness/prompts/skills/snapshot state" },
+  ];
+  const filtered = query ? items.filter((item) => item.value.startsWith(query)) : items;
+  return filtered.length > 0 ? filtered : null;
+}
+
+export default function zobSwitch(pi: ExtensionAPI): void {
+  pi.registerCommand("zob", {
+    description: "Switch ZOB Harness on/off or show status: /zob on|off|status",
+    getArgumentCompletions: argumentCompletions,
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+      const projectSettingsAvailable = existsSync(join(ctx.cwd, SETTINGS_PATH));
+      if (!projectSettingsAvailable) {
+        const globalMessage = [
+          "ZOB Harness switch: global package loaded",
+          "project switch: unavailable in this cwd (no .pi/settings.json)",
+          "global disable: use `pi remove /Users/cgarrot/zob/zob-harness` outside Pi if needed",
+        ].join("\n");
+        ctx.ui.notify(action === "" || action === "status" ? globalMessage : `${globalMessage}\n/zob on|off only edits project-local .pi/settings.json when present.`, action === "" || action === "status" ? "info" : "warning");
+        return;
+      }
+
+      if (action === "off") {
+        const current = await readSettings(ctx.cwd);
+        const snapshot = await readSnapshot(ctx.cwd);
+        if (shouldWriteOffSnapshot(current, snapshot)) {
+          await writeSnapshot(ctx.cwd, current);
+        }
+        await writeSettings(ctx.cwd, buildOffSettings(current));
+        ctx.ui.notify("ZOB Harness switched off. Reloading Pi resources...", "info");
+        await ctx.reload();
+        return;
+      }
+
+      if (action === "on") {
+        const snapshot = await readSnapshot(ctx.cwd);
+        const base = snapshot?.settings ?? await readSettings(ctx.cwd);
+        await writeSettings(ctx.cwd, buildOnSettings(base, Boolean(snapshot)));
+        ctx.ui.notify(`ZOB Harness switched on${snapshot ? " from snapshot" : " with safe defaults"}. Reloading Pi resources...`, "info");
+        await ctx.reload();
+        return;
+      }
+
+      if (action === "" || action === "status") {
+        const settings = await readSettings(ctx.cwd);
+        const snapshot = await readSnapshot(ctx.cwd);
+        ctx.ui.notify(statusFor(settings, Boolean(snapshot)), "info");
+        return;
+      }
+
+      ctx.ui.notify("Usage: /zob on|off|status", "error");
+    },
+  });
+}

package/.pi/factories/budget-preflight-dry-run/batch-manifest.json

@@ -0,0 +1,59 @@
+{
+  "factory": "budget-preflight-dry-run",
+  "description": "Batch manifest for gated budget preflight dry-run coverage across safe local source, runtime, smoke, and operating-model evidence. Agentic batch requires completed pilot proof, persisted pilot oracle review, explicit concurrency cap, and batch gate validation.",
+  "items": [
+    {
+      "id": "budget-helper-source-batch",
+      "path": ".pi/extensions/zob-harness/src/chronicle.ts",
+      "metadata": {
+        "source": "local-source",
+        "batch": true,
+        "focus": "evaluateBudgetPreflightDryRun and chronicle completion gates"
+      }
+    },
+    {
+      "id": "factory-runtime-batch",
+      "path": ".pi/extensions/zob-harness/src/runtime/tools-factory.ts",
+      "metadata": {
+        "source": "local-source",
+        "batch": true,
+        "focus": "agentic factory runtime sentinels and chronicle failure handling"
+      }
+    },
+    {
+      "id": "factory-validation-batch",
+      "path": ".pi/extensions/zob-harness/src/factory/validation.ts",
+      "metadata": {
+        "source": "local-source",
+        "batch": true,
+        "focus": "batch gate validation for pilot, oracle, and concurrency prerequisites"
+      }
+    },
+    {
+      "id": "harness-smoke-batch",
+      "path": "scripts/harness-smoke.mjs",
+      "metadata": {
+        "source": "local-smoke",
+        "batch": true,
+        "focus": "smoke assertions for factory gates and no-execution safety"
+      }
+    },
+    {
+      "id": "operating-model-batch",
+      "path": "docs/OPERATING_MODEL.md",
+      "metadata": {
+        "source": "local-doc",
+        "batch": true,
+        "focus": "operating model for advisory budgets, gates, and no body storage"
+      }
+    }
+  ],
+  "expectedArtifacts": [
+    "patterns.canonical.json",
+    "risks.canonical.json",
+    "workflow-rules.md",
+    "agent-instructions.md",
+    "quality-gates.json",
+    "dashboard-summary.md"
+  ]
+}

package/.pi/factories/budget-preflight-dry-run/factory.json

@@ -0,0 +1,94 @@
+{
+  "name": "budget-preflight-dry-run",
+  "version": "0.1.0",
+  "description": "Smoke-first read-only lot for validating deterministic budget preflight dry-run behavior without enforcement or execution.",
+  "defaultMode": "smoke",
+  "requiredStages": [
+    "manifest_loaded",
+    "agentic_plan_written",
+    "item_processed",
+    "patterns_canonicalized",
+    "risks_canonicalized",
+    "quality_gates_written",
+    "validation",
+    "sentinel"
+  ],
+  "expectedArtifacts": [
+    "patterns.canonical.json",
+    "risks.canonical.json",
+    "workflow-rules.md",
+    "agent-instructions.md",
+    "quality-gates.json",
+    "dashboard-summary.md"
+  ],
+  "stages": [
+    {
+      "name": "map-budget-preflight-helper",
+      "type": "map",
+      "agent": "explore",
+      "outputContract": "explore.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Map the local budget preflight dry-run helper and smoke coverage for pass/fail caps, advisory metadata, and no-execution flags.",
+      "promptTemplate": "Analyze budget preflight dry-run item {item.id} at {item.path}. Verify the helper is deterministic and read-only, reports maxCostUsd, maxRuns, maxDurationMs, and maxParallelChildren, exposes advisory wouldExceed/strictEnabled:false metadata, and exposes dryRun/no-execution flags. Return literal_request, actual_need, success_looks_like, files, answer, gaps, next_steps, evidence, risks/blockers, compliance, and deliverable_delivered.",
+      "mustDo": [
+        "Read the item path before conclusions.",
+        "Cite helper and smoke assertion evidence.",
+        "Keep the result focused on dry-run preflight only."
+      ],
+      "mustNotDo": [
+        "No edits.",
+        "No secrets.",
+        "No budget enforcement.",
+        "No child dispatch.",
+        "No daemons, model routing, pilot, batch, browser, write-adapter, or cloud actions."
+      ],
+      "context": "Factory {factory.name} run {run.id}; map stage for {item.id} at {item.path}. Outputs directory: {outputs.dir}."
+    },
+    {
+      "name": "reduce-budget-preflight-evidence",
+      "type": "reduce",
+      "agent": "synthesis",
+      "outputContract": "synthesis.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Synthesize pass/fail cap and no-execution evidence into a smoke-first readiness verdict.",
+      "promptTemplate": "Synthesize budget preflight dry-run map outputs for factory {factory.name} run {run.id}. Read outputs from {outputs.dir}. Produce consensus, conflicts, missing_evidence, recommended_next_action, tasks_to_rerun, evidence, risks/blockers, compliance, and deliverable_delivered. Confirm this remains dry-run advisory behavior only.",
+      "mustDo": [
+        "Confirm all four cap checks are represented.",
+        "Confirm mode:advisory, wouldExceed, strictEnabled:false, budgetEnforced:false, dryRun, modelRouterUsed:false, daemonStarted:false, childDispatchAllowed:false, and noExecution:true are represented.",
+        "Identify missing smoke evidence if present."
+      ],
+      "mustNotDo": [
+        "No edits outside the run directory.",
+        "No invented evidence.",
+        "No secrets.",
+        "No budget enforcement.",
+        "No child dispatch.",
+        "No daemons, model routing, pilot, batch, browser, write-adapter, or cloud actions."
+      ],
+      "context": "Factory {factory.name} reduce stage for run {run.id}."
+    },
+    {
+      "name": "validate-budget-preflight-dry-run",
+      "type": "validate",
+      "agent": "oracle-merge",
+      "outputContract": "oracle-merge.v1",
+      "requiredTools": ["read", "grep", "find", "ls"],
+      "expectedOutcome": "Validate budget preflight dry-run lot artifacts and produce PASS/FAIL/WARN with no_ship decision.",
+      "promptTemplate": "Validate factory {factory.name} run {run.id}. Check manifest, outputs, checkpoints, validation.json, final-report.md, telemetry.json, and DONE.sentinel under {run.dir}. Return verdict, confidence, no_ship, blockers, notes, evidence, merged_lanes, risks/blockers, compliance, and deliverable_delivered.",
+      "mustDo": [
+        "Fail if sentinel or validation evidence is missing.",
+        "Fail if the lot implies real budget enforcement or child execution.",
+        "Cite exact artifact paths."
+      ],
+      "mustNotDo": [
+        "No patches.",
+        "No commits.",
+        "No secrets.",
+        "No budget enforcement.",
+        "No child dispatch.",
+        "No daemons, model routing, pilot, batch, browser, write-adapter, or cloud actions."
+      ],
+      "context": "Factory {factory.name} validation stage for run {run.id}."
+    }
+  ]
+}

package/.pi/factories/budget-preflight-dry-run/pilot-manifest.json

@@ -0,0 +1,50 @@
+{
+  "factory": "budget-preflight-dry-run",
+  "description": "Pilot manifest for budget preflight dry-run coverage across safe local source and smoke evidence. Agentic pilot requires completed smoke proof, persisted oracle review, and explicit pilot gate validation; agentic batch requires a separate pilot oracle review, concurrency cap, and batch manifest.",
+  "items": [
+    {
+      "id": "budget-helper-source",
+      "path": ".pi/extensions/zob-harness/src/chronicle.ts",
+      "metadata": {
+        "source": "local-source",
+        "pilot": true,
+        "focus": "evaluateBudgetPreflightDryRun helper"
+      }
+    },
+    {
+      "id": "budget-helper-export",
+      "path": ".pi/extensions/zob-harness/index.ts",
+      "metadata": {
+        "source": "local-source",
+        "pilot": true,
+        "focus": "exported budget preflight helper"
+      }
+    },
+    {
+      "id": "budget-helper-smoke",
+      "path": "scripts/harness-smoke.mjs",
+      "metadata": {
+        "source": "local-smoke",
+        "pilot": true,
+        "focus": "pass/fail cap smoke assertions"
+      }
+    },
+    {
+      "id": "budget-helper-operating-model",
+      "path": "docs/OPERATING_MODEL.md",
+      "metadata": {
+        "source": "local-doc",
+        "pilot": true,
+        "focus": "budget advisory/no enforcement operating model"
+      }
+    }
+  ],
+  "expectedArtifacts": [
+    "patterns.canonical.json",
+    "risks.canonical.json",
+    "workflow-rules.md",
+    "agent-instructions.md",
+    "quality-gates.json",
+    "dashboard-summary.md"
+  ]
+}