zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/promotion/candidate.ts

@@ -0,0 +1,336 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { DEFAULT_RULES } from "../constants.js";
+import { sha256 } from "../utils/hashing.js";
+import { readJsonObjectIfPresent } from "../utils/json.js";
+import { pathMatches, resolveRepoPath, safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+import type { PromotionApplyScope, PromotionCandidateInput, PromotionCandidateRecord, PromotionGates, PromotionKind, PromotionStatus, PromotionTransitionInput } from "./types.js";
+import { PROMOTION_APPLY_SCOPES, PROMOTION_KINDS, PROMOTION_STATUSES } from "./types.js";
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+const FORBIDDEN_BODY_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "text", "rationale", "diff", "patch", "transcript", "rawContext", "rawPrompt"]);
+const STATUS_ORDER: Record<Exclude<PromotionStatus, "rejected" | "blocked">, number> = {
+  proposal: 0,
+  prepared: 1,
+  validated: 2,
+  oracle_reviewed: 3,
+  approved: 4,
+  applied: 5,
+};
+
+export const DEFAULT_PROMOTION_GATES: PromotionGates = {
+  comsThreadRequired: true,
+  sandboxRequired: true,
+  validationRequired: true,
+  oracleRequired: true,
+  humanApprovalRequired: true,
+  rollbackRequired: true,
+};
+
+const ALLOWED_TRANSITIONS: Record<PromotionStatus, PromotionStatus[]> = {
+  proposal: ["prepared", "rejected", "blocked"],
+  prepared: ["validated", "rejected", "blocked"],
+  validated: ["oracle_reviewed", "rejected", "blocked"],
+  oracle_reviewed: ["approved", "rejected", "blocked"],
+  approved: ["applied", "rejected", "blocked"],
+  applied: [],
+  rejected: [],
+  blocked: ["proposal"],
+};
+
+function hasForbiddenBodyKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenBodyKey);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => FORBIDDEN_BODY_KEYS.has(key) || hasForbiddenBodyKey(child));
+}
+
+function isBodyFreeRecord(value: unknown): boolean {
+  return isRecord(value) && value.bodyStored === false && value.promptBodiesStored === false && value.outputBodiesStored === false && !hasForbiddenBodyKey(value);
+}
+
+function isSafeMetaId(value: string | null | undefined): boolean {
+  return value === null || value === undefined || (value.length > 0 && safeFileStem(value) === value);
+}
+
+function validateArtifactRef(repoRoot: string, ref: string, label: string): string[] {
+  const errors: string[] = [];
+  if (typeof ref !== "string" || ref.trim().length === 0) return [`${label} must be a non-empty repo-relative ref`];
+  if (ref.includes("\0")) errors.push(`${label} contains NUL byte`);
+  if (ref.startsWith("/") || ref.includes("\\") || ref.includes("..")) errors.push(`${label} must be safe repo-relative: ${ref}`);
+  const resolved = resolveRepoPath(repoRoot, ref);
+  errors.push(...resolved.errors.map((error) => `${label}: ${error}`));
+  for (const protectedPattern of DEFAULT_RULES.zeroAccessPaths) {
+    if (pathMatches(ref, protectedPattern, repoRoot, repoRoot)) errors.push(`${label} references zero-access path: ${protectedPattern}`);
+  }
+  if (/(^|\/)(node_modules|dist|build|coverage)(\/|$)/.test(ref)) errors.push(`${label} must not reference generated/vendor path: ${ref}`);
+  if (/(^|\/)\.env($|[./])|(^|\/)(\.ssh|\.aws)(\/|$)|secret|credential|\.pem$|\.p12$|\.pfx$/i.test(ref)) errors.push(`${label} must not reference secrets: ${ref}`);
+  return errors;
+}
+
+function requireExistingArtifactRef(repoRoot: string, ref: unknown, label: string): string[] {
+  if (typeof ref !== "string") return [`${label} must be a persisted artifact ref`];
+  const errors = validateArtifactRef(repoRoot, ref, label);
+  if (errors.length === 0 && !existsSync(resolveRepoPath(repoRoot, ref).path)) errors.push(`${label} does not exist: ${ref}`);
+  return errors;
+}
+
+function normalizeRepoPath(repoRoot: string, ref: string): string {
+  return resolveRepoPath(repoRoot, ref).path.replace(/\/+$/g, "");
+}
+
+function pathInsideAny(repoRoot: string, child: string, parents: string[]): boolean {
+  if (parents.length === 0) return true;
+  const normalizedChild = normalizeRepoPath(repoRoot, child);
+  return parents.some((parent) => {
+    const normalizedParent = normalizeRepoPath(repoRoot, parent);
+    return normalizedChild === normalizedParent || normalizedChild.startsWith(`${normalizedParent}/`);
+  });
+}
+
+function isAtLeast(status: PromotionStatus, minimum: Exclude<PromotionStatus, "rejected" | "blocked">): boolean {
+  if (status === "rejected" || status === "blocked") return false;
+  return STATUS_ORDER[status] >= STATUS_ORDER[minimum];
+}
+
+function mergeGates(input?: Partial<PromotionGates>): PromotionGates {
+  return { ...DEFAULT_PROMOTION_GATES, ...(input ?? {}) };
+}
+
+export function promotionReportsDir(repoRoot: string): string {
+  return join(repoRoot, "reports", "promotions");
+}
+
+export function promotionCandidateDir(repoRoot: string, candidateId: string): string {
+  return join(promotionReportsDir(repoRoot), safeFileStem(candidateId));
+}
+
+export function promotionCandidateRef(candidateId: string, relativePath = "promotion-candidate.json"): string {
+  return `reports/promotions/${safeFileStem(candidateId)}/${relativePath}`;
+}
+
+function buildCandidateId(input: PromotionCandidateInput): string {
+  if (input.candidateId) {
+    const safe = safeFileStem(input.candidateId);
+    if (safe !== input.candidateId) throw new Error(`Unsafe promotion candidateId: ${input.candidateId}`);
+    return safe;
+  }
+  return `promo_${sha256(`${input.kind}:${input.runId}:${input.sourceRef}:${Date.now()}`).slice(0, 16)}`;
+}
+
+export function createPromotionCandidate(input: PromotionCandidateInput): PromotionCandidateRecord {
+  const candidateId = buildCandidateId(input);
+  const now = new Date().toISOString();
+  const changedPaths = [...new Set(input.changedPaths ?? [])].sort();
+  const allowedPaths = [...new Set(input.allowedPaths ?? [])].sort();
+  const forbiddenPaths = [...new Set(input.forbiddenPaths ?? [])].sort();
+  return {
+    schema: "zob.promotion-candidate.v1",
+    candidateId,
+    kind: input.kind,
+    runId: input.runId,
+    goalId: input.goalId ?? null,
+    todoId: input.todoId ?? null,
+    status: "proposal",
+    sourceRef: input.sourceRef,
+    sourceHash: input.sourceHash ?? null,
+    preparedArtifactRef: input.preparedArtifactRef ?? null,
+    validationRefs: [...new Set(input.validationRefs ?? [])].sort(),
+    oracleReviewRef: input.oracleReviewRef ?? null,
+    oracleVerdict: input.oracleVerdict ?? null,
+    oracleNoShip: input.oracleNoShip ?? null,
+    approvalRef: input.approvalRef ?? null,
+    rollbackRef: input.rollbackRef ?? null,
+    comsThreadRef: input.comsThreadRef ?? null,
+    goalRoomMessageRefs: [...new Set(input.goalRoomMessageRefs ?? [])].sort(),
+    changedPaths,
+    changedPathHashes: changedPaths.map((path) => sha256(path)),
+    allowedPaths,
+    forbiddenPaths,
+    gates: mergeGates(input.gates),
+    applyScope: input.applyScope ?? "none",
+    applyPerformed: false,
+    productionWritesPerformed: false,
+    autoApply: false,
+    parentOwned: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    metadata: input.metadata ?? {},
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function validatePromotionCandidate(repoRoot: string, candidate: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(candidate)) return ["promotion candidate must be an object"];
+  if (!isBodyFreeRecord(candidate)) errors.push("promotion candidate must be body-free/hash-only and must not contain raw body-like keys");
+  if (candidate.schema !== "zob.promotion-candidate.v1") errors.push("promotion candidate schema mismatch");
+  if (typeof candidate.candidateId !== "string" || safeFileStem(candidate.candidateId) !== candidate.candidateId) errors.push("candidateId must be path-safe");
+  if (typeof candidate.runId !== "string" || safeFileStem(candidate.runId) !== candidate.runId) errors.push("runId must be path-safe");
+  if (!isSafeMetaId(candidate.goalId as string | null | undefined)) errors.push("goalId must be metadata/path safe when provided");
+  if (!isSafeMetaId(candidate.todoId as string | null | undefined)) errors.push("todoId must be metadata/path safe when provided");
+  if (typeof candidate.kind !== "string" || !PROMOTION_KINDS.includes(candidate.kind as PromotionKind)) errors.push("invalid promotion kind");
+  if (typeof candidate.status !== "string" || !PROMOTION_STATUSES.includes(candidate.status as PromotionStatus)) errors.push("invalid promotion status");
+  if (typeof candidate.sourceRef !== "string") errors.push("sourceRef is required");
+  else errors.push(...validateArtifactRef(repoRoot, candidate.sourceRef, "sourceRef"));
+  if (candidate.sourceHash !== null && candidate.sourceHash !== undefined && !SHA256_HEX.test(String(candidate.sourceHash))) errors.push("sourceHash must be sha256 hex when provided");
+  const gates = isRecord(candidate.gates) ? candidate.gates as Partial<PromotionGates> : undefined;
+  if (!gates) errors.push("promotion candidate requires gates");
+  for (const gateName of ["comsThreadRequired", "sandboxRequired", "validationRequired", "oracleRequired", "humanApprovalRequired", "rollbackRequired"] as const) {
+    if (typeof gates?.[gateName] !== "boolean") errors.push(`gate ${gateName} must be boolean`);
+  }
+  const refs: Array<[unknown, string]> = [
+    [candidate.preparedArtifactRef, "preparedArtifactRef"],
+    [candidate.oracleReviewRef, "oracleReviewRef"],
+    [candidate.approvalRef, "approvalRef"],
+    [candidate.rollbackRef, "rollbackRef"],
+    [candidate.comsThreadRef, "comsThreadRef"],
+  ];
+  for (const [ref, label] of refs) {
+    if (ref !== null && ref !== undefined) errors.push(...validateArtifactRef(repoRoot, String(ref), label));
+  }
+  for (const [field, label] of [[candidate.validationRefs, "validationRefs"], [candidate.goalRoomMessageRefs, "goalRoomMessageRefs"], [candidate.changedPaths, "changedPaths"], [candidate.allowedPaths, "allowedPaths"], [candidate.forbiddenPaths, "forbiddenPaths"]] as const) {
+    if (!Array.isArray(field) || !field.every((item) => typeof item === "string")) errors.push(`${label} must be a string array`);
+    else for (const item of field) errors.push(...validateArtifactRef(repoRoot, item, label));
+  }
+  if (!Array.isArray(candidate.changedPathHashes) || !candidate.changedPathHashes.every((hash) => typeof hash === "string" && SHA256_HEX.test(hash))) errors.push("changedPathHashes must be sha256 hex array");
+  if (Array.isArray(candidate.changedPaths) && Array.isArray(candidate.allowedPaths)) {
+    for (const changedPath of candidate.changedPaths.filter((item): item is string => typeof item === "string")) {
+      if (!pathInsideAny(repoRoot, changedPath, candidate.allowedPaths.filter((item): item is string => typeof item === "string"))) errors.push(`changed path is outside allowedPaths: ${changedPath}`);
+      for (const forbiddenPath of (candidate.forbiddenPaths as unknown[]).filter((item): item is string => typeof item === "string")) {
+        if (pathMatches(changedPath, forbiddenPath, repoRoot, repoRoot)) errors.push(`changed path matches forbiddenPaths: ${changedPath}`);
+      }
+    }
+  }
+  const status = candidate.status as PromotionStatus;
+  if (gates?.comsThreadRequired === true && typeof candidate.comsThreadRef !== "string") errors.push("comsThreadRef is required by gates");
+  if (gates?.sandboxRequired === true && isAtLeast(status, "prepared")) errors.push(...requireExistingArtifactRef(repoRoot, candidate.preparedArtifactRef, "preparedArtifactRef"));
+  if (gates?.validationRequired === true && isAtLeast(status, "validated")) {
+    if (!Array.isArray(candidate.validationRefs) || candidate.validationRefs.length === 0) errors.push("validationRefs are required by validation gate");
+    else for (const validationRef of candidate.validationRefs) errors.push(...requireExistingArtifactRef(repoRoot, validationRef, "validationRefs"));
+  }
+  if (gates?.oracleRequired === true && isAtLeast(status, "oracle_reviewed")) {
+    errors.push(...requireExistingArtifactRef(repoRoot, candidate.oracleReviewRef, "oracleReviewRef"));
+    if (candidate.oracleVerdict !== "PASS") errors.push("oracle gate requires oracleVerdict=PASS");
+    if (candidate.oracleNoShip !== false) errors.push("oracle gate requires oracleNoShip=false");
+  }
+  if (gates?.comsThreadRequired === true && isAtLeast(status, "approved")) errors.push(...requireExistingArtifactRef(repoRoot, candidate.comsThreadRef, "comsThreadRef"));
+  if (gates?.humanApprovalRequired === true && isAtLeast(status, "approved")) errors.push(...requireExistingArtifactRef(repoRoot, candidate.approvalRef, "approvalRef"));
+  if (gates?.rollbackRequired === true && status === "applied") errors.push(...requireExistingArtifactRef(repoRoot, candidate.rollbackRef, "rollbackRef"));
+  if (!PROMOTION_APPLY_SCOPES.includes(candidate.applyScope as PromotionApplyScope)) errors.push("invalid applyScope");
+  if (status === "applied") {
+    if (candidate.applyScope !== "quarantine_test_directory") errors.push("applied status is only supported for quarantine_test_directory scope in this runtime slice");
+    if (candidate.applyPerformed !== true) errors.push("applied status requires applyPerformed=true");
+  } else if (candidate.applyPerformed !== false) {
+    errors.push("applyPerformed must remain false until applied status");
+  }
+  if (candidate.productionWritesPerformed !== false) errors.push("productionWritesPerformed must remain false");
+  if (candidate.autoApply !== false) errors.push("autoApply must remain false");
+  if (candidate.parentOwned !== true) errors.push("promotion candidate must remain parent-owned");
+  return errors;
+}
+
+export function transitionAllowed(from: PromotionStatus, to: PromotionStatus): boolean {
+  return (ALLOWED_TRANSITIONS[from] ?? []).includes(to);
+}
+
+export function advancePromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord, input: PromotionTransitionInput): PromotionCandidateRecord {
+  if (!transitionAllowed(candidate.status, input.toStatus)) throw new Error(`Invalid promotion transition ${candidate.status} -> ${input.toStatus}`);
+  const updated: PromotionCandidateRecord = {
+    ...candidate,
+    status: input.toStatus,
+    preparedArtifactRef: input.preparedArtifactRef ?? candidate.preparedArtifactRef,
+    validationRefs: [...new Set([...(candidate.validationRefs ?? []), ...(input.validationRefs ?? [])])].sort(),
+    oracleReviewRef: input.oracleReviewRef ?? candidate.oracleReviewRef,
+    oracleVerdict: input.oracleVerdict ?? candidate.oracleVerdict,
+    oracleNoShip: input.oracleNoShip ?? candidate.oracleNoShip,
+    approvalRef: input.approvalRef ?? candidate.approvalRef,
+    rollbackRef: input.rollbackRef ?? candidate.rollbackRef,
+    goalRoomMessageRefs: [...new Set([...(candidate.goalRoomMessageRefs ?? []), ...(input.goalRoomMessageRefs ?? [])])].sort(),
+    applyScope: input.applyScope ?? candidate.applyScope,
+    applyPerformed: input.applyPerformed ?? (input.toStatus === "applied" ? true : candidate.applyPerformed),
+    metadata: { ...candidate.metadata, ...(input.metadata ?? {}) },
+    updatedAt: new Date().toISOString(),
+  };
+  const errors = validatePromotionCandidate(repoRoot, updated);
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  return updated;
+}
+
+export function writePromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord): string {
+  const errors = validatePromotionCandidate(repoRoot, candidate);
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  const dir = promotionCandidateDir(repoRoot, candidate.candidateId);
+  mkdirSync(dir, { recursive: true });
+  const relativeRef = promotionCandidateRef(candidate.candidateId);
+  writeFileSync(join(dir, "promotion-candidate.json"), JSON.stringify(candidate, null, 2), "utf8");
+  appendFileSync(join(dir, "promotion-ledger.jsonl"), `${JSON.stringify({ event: "candidate_written", candidateId: candidate.candidateId, status: candidate.status, applyPerformed: candidate.applyPerformed, productionWritesPerformed: false, autoApply: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, timestamp: new Date().toISOString() })}\n`, "utf8");
+  return relativeRef;
+}
+
+export function appendPromotionLedger(repoRoot: string, candidateId: string, event: Record<string, unknown>): string {
+  const dir = promotionCandidateDir(repoRoot, candidateId);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "promotion-ledger.jsonl"), `${JSON.stringify({ ...event, candidateId, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, timestamp: new Date().toISOString() })}\n`, "utf8");
+  return promotionCandidateRef(candidateId, "promotion-ledger.jsonl");
+}
+
+function latestPromotionIds(repoRoot: string, limit: number): string[] {
+  const root = promotionReportsDir(repoRoot);
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .map((entry) => ({ entry, path: join(root, entry), stat: statSync(join(root, entry)) }))
+    .filter((item) => item.stat.isDirectory())
+    .sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs)
+    .slice(0, Math.max(1, limit))
+    .map((item) => item.entry);
+}
+
+export function summarizePromotionCandidates(repoRoot: string, limit = 10): Record<string, unknown> {
+  const latest = latestPromotionIds(repoRoot, limit).flatMap((candidateId) => {
+    const candidate = readJsonObjectIfPresent(join(promotionCandidateDir(repoRoot, candidateId), "promotion-candidate.json"));
+    if (!candidate) return [];
+    const errors = validatePromotionCandidate(repoRoot, candidate);
+    return [{
+      candidateId: candidate.candidateId,
+      kind: candidate.kind,
+      status: candidate.status,
+      runId: candidate.runId,
+      todoId: candidate.todoId,
+      changedPaths: Array.isArray(candidate.changedPaths) ? candidate.changedPaths : [],
+      validationRefs: Array.isArray(candidate.validationRefs) ? candidate.validationRefs : [],
+      oracleReviewRef: candidate.oracleReviewRef,
+      approvalRef: candidate.approvalRef,
+      applyScope: candidate.applyScope,
+      applyPerformed: candidate.applyPerformed,
+      productionWritesPerformed: candidate.productionWritesPerformed,
+      autoApply: candidate.autoApply,
+      valid: errors.length === 0,
+      errors,
+      artifact: promotionCandidateRef(String(candidate.candidateId)),
+      bodyStored: false,
+    }];
+  });
+  return {
+    latest,
+    blocked: latest.filter((entry) => entry.status === "blocked" || (Array.isArray(entry.errors) && entry.errors.length > 0)),
+    awaitingOracle: latest.filter((entry) => entry.status === "validated"),
+    awaitingApproval: latest.filter((entry) => entry.status === "oracle_reviewed"),
+    eligibleApply: latest.filter((entry) => entry.status === "approved"),
+    bodySafety: { summariesBodyFree: !hasForbiddenBodyKey(latest) },
+    uiReadyMetadataOnly: true,
+  };
+}
+
+export function promotionTestWorkspaceRef(candidateId: string, suffix = "applied-test-workspace"): string {
+  return promotionCandidateRef(candidateId, suffix);
+}
+
+export function assertInsidePromotionWorkspace(repoRoot: string, candidateId: string, path: string): void {
+  const root = resolve(promotionCandidateDir(repoRoot, candidateId));
+  const resolved = resolve(repoRoot, path);
+  if (resolved !== root && !resolved.startsWith(`${root}/`)) throw new Error(`Path must stay inside promotion workspace: ${path}`);
+}

package/.pi/extensions/zob-harness/src/promotion/coms.ts

@@ -0,0 +1,127 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { sha256 } from "../utils/hashing.js";
+import { safeFileStem } from "../utils/paths.js";
+import { isRecord } from "../utils/records.js";
+import { promotionCandidateDir, promotionCandidateRef } from "./candidate.js";
+import type { PromotionCandidateRecord, PromotionComsMessageRef, PromotionComsThreadInput, PromotionComsThreadRecord } from "./types.js";
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+const ALLOWED_KINDS = new Set(["STATUS_UPDATE", "FINDING", "RISK", "BLOCKER", "NO_SHIP_ALERT", "CONTEXT_REQUEST", "DELEGATION_REQUEST", "ORACLE_REQUEST", "QUESTION", "ANSWER"]);
+const TERMINAL_BAD_STATUSES = new Set(["stale", "offline", "timeout"]);
+const FORBIDDEN_BODY_KEYS = new Set(["body", "task", "prompt", "output", "content", "message", "text", "rationale", "diff", "patch", "transcript", "rawContext", "rawPrompt"]);
+
+function hasForbiddenBodyKey(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenBodyKey);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => FORBIDDEN_BODY_KEYS.has(key) || hasForbiddenBodyKey(child));
+}
+
+function safeMeta(value: unknown): boolean {
+  return typeof value === "string" && value.length > 0 && safeFileStem(value) === value;
+}
+
+export function buildPromotionComsMessageRef(input: Omit<PromotionComsMessageRef, "parentVisible" | "hiddenPeerChat" | "workerToWorkerDirect" | "bodyStored" | "promptBodiesStored" | "outputBodiesStored">): PromotionComsMessageRef {
+  return {
+    ...input,
+    outputHash: input.outputHash ?? null,
+    artifactRefs: input.artifactRefs ?? [],
+    evidenceRefs: input.evidenceRefs ?? [],
+    parentVisible: true,
+    hiddenPeerChat: false,
+    workerToWorkerDirect: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function buildPromotionComsThread(input: PromotionComsThreadInput): PromotionComsThreadRecord {
+  const now = new Date().toISOString();
+  return {
+    schema: "zob.promotion-coms-thread.v1",
+    threadId: input.threadId ?? `pthread_${sha256(`${input.candidateId}:${Date.now()}`).slice(0, 16)}`,
+    goalId: input.goalId,
+    todoId: input.todoId ?? null,
+    candidateId: input.candidateId,
+    kind: input.kind,
+    messageRefs: input.messageRefs ?? [],
+    requiredAcks: input.requiredAcks ?? [],
+    stalePolicy: input.stalePolicy ?? "stale_blocks_completion",
+    parentVisible: true,
+    parentOwnedActions: true,
+    hiddenPeerChat: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function addPromotionComsMessageRef(thread: PromotionComsThreadRecord, message: PromotionComsMessageRef): PromotionComsThreadRecord {
+  return { ...thread, messageRefs: [...thread.messageRefs, message], updatedAt: new Date().toISOString() };
+}
+
+export function validatePromotionComsMessageRef(message: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(message)) return ["promotion coms message ref must be an object"];
+  if (hasForbiddenBodyKey(message)) errors.push("promotion coms message ref must not contain raw body-like keys");
+  if (!safeMeta(message.msgId)) errors.push("message msgId must be metadata-safe");
+  if (typeof message.kind !== "string" || !ALLOWED_KINDS.has(message.kind)) errors.push("message kind is not allowed for promotion coms");
+  if (typeof message.sender !== "string" || message.sender.length === 0) errors.push("message sender is required");
+  if (typeof message.status !== "string" || !["queued", "acked", "running", "completed", "blocked", "timeout", "stale", "offline"].includes(message.status)) errors.push("message status is invalid");
+  if (typeof message.bodyHash !== "string" || !SHA256_HEX.test(message.bodyHash)) errors.push("message bodyHash must be sha256 hex");
+  if (message.outputHash !== null && message.outputHash !== undefined && (typeof message.outputHash !== "string" || !SHA256_HEX.test(message.outputHash))) errors.push("message outputHash must be sha256 hex when provided");
+  if (!Array.isArray(message.artifactRefs) || !message.artifactRefs.every((ref) => typeof ref === "string")) errors.push("message artifactRefs must be string array");
+  if (!Array.isArray(message.evidenceRefs) || !message.evidenceRefs.every((ref) => typeof ref === "string")) errors.push("message evidenceRefs must be string array");
+  if (message.status !== "completed" && message.countsAsCompletion === true) errors.push("only completed promotion coms messages may count as completion");
+  if (TERMINAL_BAD_STATUSES.has(String(message.status)) && message.countsAsCompletion === true) errors.push("stale/offline/timeout message must not count as completion");
+  if (message.parentVisible !== true || message.hiddenPeerChat !== false || message.workerToWorkerDirect !== false) errors.push("promotion coms must be parent-visible and must not be hidden worker-to-worker chat");
+  if (message.bodyStored !== false || message.promptBodiesStored !== false || message.outputBodiesStored !== false) errors.push("promotion coms message ref must keep body flags false");
+  return errors;
+}
+
+export function validatePromotionComsThread(thread: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(thread)) return ["promotion coms thread must be an object"];
+  if (hasForbiddenBodyKey(thread)) errors.push("promotion coms thread must not contain raw body-like keys");
+  if (thread.schema !== "zob.promotion-coms-thread.v1") errors.push("promotion coms thread schema mismatch");
+  if (!safeMeta(thread.threadId)) errors.push("threadId must be metadata-safe");
+  if (!safeMeta(thread.goalId)) errors.push("goalId must be metadata-safe");
+  if (thread.todoId !== null && thread.todoId !== undefined && !safeMeta(thread.todoId)) errors.push("todoId must be metadata-safe when provided");
+  if (!safeMeta(thread.candidateId)) errors.push("candidateId must be metadata-safe");
+  if (thread.stalePolicy !== "stale_blocks_completion") errors.push("stalePolicy must be stale_blocks_completion");
+  if (thread.parentVisible !== true || thread.parentOwnedActions !== true || thread.hiddenPeerChat !== false) errors.push("promotion coms thread must be parent-visible and parent-owned");
+  if (thread.bodyStored !== false || thread.promptBodiesStored !== false || thread.outputBodiesStored !== false) errors.push("promotion coms thread must keep body flags false");
+  if (!Array.isArray(thread.messageRefs)) errors.push("messageRefs must be an array");
+  else thread.messageRefs.forEach((message, index) => validatePromotionComsMessageRef(message).forEach((error) => errors.push(`messageRefs[${index}]: ${error}`)));
+  if (!Array.isArray(thread.requiredAcks) || !thread.requiredAcks.every((ack) => typeof ack === "string")) errors.push("requiredAcks must be string array");
+  const acked = new Set(Array.isArray(thread.messageRefs) ? thread.messageRefs.filter(isRecord).filter((message) => message.status === "acked" || message.status === "completed").map((message) => String(message.msgId)) : []);
+  for (const requiredAck of Array.isArray(thread.requiredAcks) ? thread.requiredAcks : []) {
+    if (!acked.has(requiredAck)) errors.push(`required ack missing: ${requiredAck}`);
+  }
+  return errors;
+}
+
+export function validatePromotionComsReadiness(candidate: PromotionCandidateRecord, thread: PromotionComsThreadRecord): string[] {
+  const errors = validatePromotionComsThread(thread);
+  if (thread.candidateId !== candidate.candidateId) errors.push("promotion coms thread candidateId must match candidate");
+  if (thread.kind !== candidate.kind) errors.push("promotion coms thread kind must match candidate");
+  const messageKinds = new Set(thread.messageRefs.map((message) => message.kind));
+  if ((candidate.status === "approved" || candidate.status === "applied") && !messageKinds.has("ORACLE_REQUEST")) errors.push("approved/applied promotion requires ORACLE_REQUEST message ref in coms thread");
+  if ((candidate.status === "approved" || candidate.status === "applied") && !thread.messageRefs.some((message) => message.kind === "FINDING" || message.kind === "STATUS_UPDATE")) errors.push("approved/applied promotion requires FINDING or STATUS_UPDATE message ref in coms thread");
+  if (thread.messageRefs.some((message) => TERMINAL_BAD_STATUSES.has(message.status) && message.countsAsCompletion === true)) errors.push("stale/offline/timeout coms cannot count as promotion completion");
+  if (candidate.status === "applied" && !thread.messageRefs.some((message) => message.status === "completed" && message.countsAsCompletion === true)) errors.push("applied promotion requires a completed parent-visible status message");
+  return errors;
+}
+
+export function writePromotionComsThread(repoRoot: string, thread: PromotionComsThreadRecord): string {
+  const errors = validatePromotionComsThread(thread);
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  const dir = promotionCandidateDir(repoRoot, thread.candidateId);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "promotion-coms-thread.json"), JSON.stringify(thread, null, 2), "utf8");
+  return promotionCandidateRef(thread.candidateId, "promotion-coms-thread.json");
+}

package/.pi/extensions/zob-harness/src/promotion/documentation.ts

@@ -0,0 +1,142 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { sha256 } from "../utils/hashing.js";
+import { resolveRepoPath, safeFileStem } from "../utils/paths.js";
+import { parseJsonFile } from "../utils/json.js";
+import { isRecord } from "../utils/records.js";
+import { advancePromotionCandidate, createPromotionCandidate, promotionCandidateDir, promotionCandidateRef, validatePromotionCandidate, writePromotionCandidate } from "./candidate.js";
+import type { PromotionCandidateRecord } from "./types.js";
+
+export interface DocumentationPromotionDraft {
+  targetPath: string;
+  draftText: string;
+  reason?: string;
+}
+
+export interface PrepareDocumentationPromotionInput {
+  candidateId?: string;
+  runId: string;
+  goalId?: string;
+  todoId?: string;
+  sourceRef: string;
+  drafts: DocumentationPromotionDraft[];
+  approvalMode?: "proposal_only" | "auto_prepare_patch";
+}
+
+const SENSITIVE_DOC_PATTERNS = [/^AGENTS\.md$/, /^docs\//, /^\.pi\/(rules|skills|prompts|agents|output-contracts)\//];
+
+function hasForbiddenRawKeys(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasForbiddenRawKeys);
+  return Object.entries(value as Record<string, unknown>).some(([key, child]) => ["body", "task", "prompt", "output", "content", "message", "text", "rationale", "diff", "patch", "transcript", "rawContext", "rawPrompt"].includes(key) || hasForbiddenRawKeys(child));
+}
+
+function validateTargetPath(repoRoot: string, path: string): string[] {
+  const errors: string[] = [];
+  const resolved = resolveRepoPath(repoRoot, path);
+  errors.push(...resolved.errors.map((error) => `targetPath: ${error}`));
+  if (path.includes("\0") || path.startsWith("/") || path.includes("..") || path.includes("\\")) errors.push(`targetPath must be safe repo-relative: ${path}`);
+  if (/(^|\/)\.env($|[./])|secret|credential|\.pem$|\.p12$|\.pfx$/i.test(path)) errors.push(`targetPath must not reference secrets: ${path}`);
+  if (!SENSITIVE_DOC_PATTERNS.some((pattern) => pattern.test(path))) errors.push(`documentation promotion target must be a docs/guidance path: ${path}`);
+  return errors;
+}
+
+export function prepareDocumentationPromotion(repoRoot: string, input: PrepareDocumentationPromotionInput): { candidate: PromotionCandidateRecord; preparedArtifactRef: string; draftRefs: string[]; validationRef: string } {
+  const targetErrors = input.drafts.flatMap((draft) => validateTargetPath(repoRoot, draft.targetPath));
+  if (targetErrors.length > 0) throw new Error(targetErrors.join("; "));
+  const candidate = createPromotionCandidate({
+    candidateId: input.candidateId,
+    kind: "documentation_writeback",
+    runId: input.runId,
+    goalId: input.goalId,
+    todoId: input.todoId,
+    sourceRef: input.sourceRef,
+    allowedPaths: [...new Set(input.drafts.map((draft) => draft.targetPath.split("/").slice(0, -1).join("/") || draft.targetPath))],
+    changedPaths: input.drafts.map((draft) => draft.targetPath),
+    comsThreadRef: input.candidateId ? promotionCandidateRef(input.candidateId, "promotion-coms-thread.json") : undefined,
+    metadata: { lane: "documentation", approvalMode: input.approvalMode ?? "auto_prepare_patch" },
+  });
+  const candidateDir = promotionCandidateDir(repoRoot, candidate.candidateId);
+  const draftRefs: string[] = [];
+  const draftRecords = input.drafts.map((draft) => {
+    const draftRef = promotionCandidateRef(candidate.candidateId, `documentation/quarantine/${safeFileStem(draft.targetPath)}.draft.md`);
+    const draftPath = join(repoRoot, draftRef);
+    mkdirSync(dirname(draftPath), { recursive: true });
+    writeFileSync(draftPath, draft.draftText, "utf8");
+    draftRefs.push(draftRef);
+    return {
+      targetPath: draft.targetPath,
+      targetPathHash: sha256(draft.targetPath),
+      draftRef,
+      draftHash: sha256(draft.draftText),
+      reasonHash: draft.reason ? sha256(draft.reason) : null,
+      bodyStored: false,
+    };
+  });
+  const preparedArtifact = {
+    schema: "zob.documentation-promotion-prepared.v1",
+    candidateId: candidate.candidateId,
+    approvalMode: input.approvalMode ?? "auto_prepare_patch",
+    draftRecords,
+    changedPaths: candidate.changedPaths,
+    patchHash: sha256(JSON.stringify(draftRecords.map((record) => [record.targetPathHash, record.draftHash]))),
+    durableApplyPerformed: false,
+    autoApply: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const preparedArtifactRef = promotionCandidateRef(candidate.candidateId, "documentation/prepared.json");
+  mkdirSync(join(candidateDir, "documentation"), { recursive: true });
+  writeFileSync(join(repoRoot, preparedArtifactRef), JSON.stringify(preparedArtifact, null, 2), "utf8");
+  const validation = validateDocumentationPromotion(preparedArtifact);
+  const validationRef = promotionCandidateRef(candidate.candidateId, "documentation/validation.json");
+  writeFileSync(join(repoRoot, validationRef), JSON.stringify({ schema: "zob.documentation-promotion-validation.v1", candidateId: candidate.candidateId, valid: validation.length === 0, errors: validation, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const prepared = advancePromotionCandidate(repoRoot, { ...candidate, comsThreadRef: promotionCandidateRef(candidate.candidateId, "promotion-coms-thread.json") }, { toStatus: "prepared", preparedArtifactRef, validationRefs: validation.length === 0 ? [validationRef] : [], metadata: { draftRefs } });
+  writePromotionCandidate(repoRoot, prepared);
+  return { candidate: prepared, preparedArtifactRef, draftRefs, validationRef };
+}
+
+export function validateDocumentationPromotion(artifact: unknown): string[] {
+  const errors: string[] = [];
+  if (!isRecord(artifact)) return ["documentation promotion artifact must be an object"];
+  if (artifact.schema !== "zob.documentation-promotion-prepared.v1") errors.push("documentation promotion artifact schema mismatch");
+  if (hasForbiddenRawKeys(artifact)) errors.push("documentation promotion artifact must not include raw body-like keys");
+  if (!Array.isArray(artifact.draftRecords) || artifact.draftRecords.length === 0) errors.push("documentation promotion requires draftRecords");
+  if (artifact.durableApplyPerformed !== false || artifact.autoApply !== false) errors.push("documentation promotion must not auto-apply durable docs");
+  if (artifact.bodyStored !== false || artifact.promptBodiesStored !== false || artifact.outputBodiesStored !== false) errors.push("documentation promotion artifact must keep body flags false");
+  if (typeof artifact.patchHash !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.patchHash)) errors.push("documentation promotion requires patchHash");
+  return errors;
+}
+
+export function applyDocumentationPromotionInQuarantine(repoRoot: string, candidate: PromotionCandidateRecord): { candidate: PromotionCandidateRecord; appliedRefs: string[]; appliedMetadataRef: string } {
+  if (candidate.kind !== "documentation_writeback") throw new Error("candidate kind must be documentation_writeback");
+  if (candidate.status !== "approved") throw new Error("documentation quarantine apply requires approved candidate");
+  if (!candidate.preparedArtifactRef) throw new Error("documentation quarantine apply requires preparedArtifactRef");
+  const prepared = parseJsonFile(join(repoRoot, candidate.preparedArtifactRef));
+  if (!isRecord(prepared) || !Array.isArray(prepared.draftRecords)) throw new Error("documentation prepared artifact missing draftRecords");
+  const appliedRefs: string[] = [];
+  for (const record of prepared.draftRecords.filter(isRecord)) {
+    const targetPath = typeof record.targetPath === "string" ? record.targetPath : "unknown.md";
+    const draftRef = typeof record.draftRef === "string" ? record.draftRef : undefined;
+    if (!draftRef) throw new Error("draftRef missing from documentation prepared artifact");
+    const draftText = readFileSync(join(repoRoot, draftRef), "utf8");
+    const appliedRef = promotionCandidateRef(candidate.candidateId, `documentation/applied-test-workspace/${safeFileStem(targetPath)}.md`);
+    mkdirSync(dirname(join(repoRoot, appliedRef)), { recursive: true });
+    writeFileSync(join(repoRoot, appliedRef), draftText, "utf8");
+    appliedRefs.push(appliedRef);
+  }
+  const appliedMetadataRef = promotionCandidateRef(candidate.candidateId, "documentation/applied-test-workspace/apply-metadata.json");
+  writeFileSync(join(repoRoot, appliedMetadataRef), JSON.stringify({ schema: "zob.documentation-quarantine-apply.v1", candidateId: candidate.candidateId, appliedRefs, productionWritesPerformed: false, autoApply: false, bodyStored: false, promptBodiesStored: false, outputBodiesStored: false }, null, 2), "utf8");
+  const applied = advancePromotionCandidate(repoRoot, candidate, { toStatus: "applied", applyScope: "quarantine_test_directory", applyPerformed: true });
+  writePromotionCandidate(repoRoot, applied);
+  return { candidate: applied, appliedRefs, appliedMetadataRef };
+}
+
+export function validateDocumentationPromotionCandidate(repoRoot: string, candidate: PromotionCandidateRecord): string[] {
+  const errors = validatePromotionCandidate(repoRoot, candidate);
+  if (candidate.kind !== "documentation_writeback") errors.push("candidate kind must be documentation_writeback");
+  if (candidate.autoApply !== false || candidate.productionWritesPerformed !== false) errors.push("documentation candidate must not auto-apply or perform production writes");
+  return errors;
+}