zob-harness 0.1.0

package/.pi/extensions/zob-harness/src/launch-apply.ts

@@ -0,0 +1,313 @@
+import { DEFAULT_RULES } from "./constants.js";
+import { sha256 } from "./utils/hashing.js";
+import { pathMatches, resolveRepoPath, safeFileStem } from "./utils/paths.js";
+import { isRecord } from "./utils/records.js";
+
+export type WorkerPoolLaneKind = "context" | "factory" | "implement" | "qa" | "oracle";
+export type ApplyGateStatus = "eligible_not_applied" | "blocked";
+
+export interface ControlledWorkerPoolLane {
+  laneId: string;
+  kind: WorkerPoolLaneKind;
+  maxWorkers: number;
+  parentOwnedDispatch: true;
+  childDirectDispatch: false;
+  workspaceClaimRequired: true;
+  goalRoomEventsRequired: true;
+  todoClaimReducerRequired: true;
+  outputContract: string;
+}
+
+export interface ControlledWorkerPoolPlan {
+  schema: "zob.controlled-worker-pool-plan.v1";
+  runId: string;
+  maxParallelWorkers: number;
+  launchAuthorizationRequired: true;
+  strictBudgetRequired: true;
+  workerPoolEnabledByLaunch: boolean;
+  lanes: ControlledWorkerPoolLane[];
+  l5ControlledWorkerPool: true;
+  parentOwnedDispatch: true;
+  childDirectDispatch: false;
+  eventContract: "agent-event.v1";
+  todoReducerContract: "zob.todo-event-reducer-decision.v1";
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface LaunchAuthorizedApplyInput {
+  runId: string;
+  launchAuthorization: Record<string, unknown>;
+  changedPaths: string[];
+  allowedPaths?: string[];
+  forbiddenPaths?: string[];
+  diffHash: string;
+  sandboxRunId?: string;
+  oracleReviewRef?: string;
+  validationRefs?: string[];
+  workerPoolPlan?: ControlledWorkerPoolPlan;
+}
+
+export interface LaunchAuthorizedApplyGate {
+  schema: "zob.launch-authorized-apply-gate.v1";
+  runId: string;
+  status: ApplyGateStatus;
+  applyEligible: boolean;
+  autoApplyAuthorizedByLaunch: boolean;
+  manualPerActionApprovalRequired: false;
+  exceptionApprovalRequiredOnlyForOutOfScope: true;
+  applyPerformed: false;
+  productionWritesPerformed: false;
+  changedPaths: string[];
+  changedPathHashes: string[];
+  diffHash: string;
+  sandboxRunIdHash?: string;
+  oracleReviewRef?: string;
+  validationRefs: string[];
+  gates: {
+    specLocked: boolean;
+    userLaunchConfirmed: boolean;
+    launchAuthorizesInScopeActions: boolean;
+    applyPolicyAutoApplyInScope: boolean;
+    workerPoolControlled: boolean;
+    changedPathsAllowed: boolean;
+    forbiddenPathsClear: boolean;
+    sandboxEvidencePresent: boolean;
+    oracleReviewPresent: boolean;
+    validationRefsPresent: boolean;
+    diffHashPresent: boolean;
+  };
+  blockers: string[];
+  l6LaunchAuthorizedApply: true;
+  parentOwnedApplyCoordinatorRequired: true;
+  rollbackRequired: true;
+  postApplyValidationRequired: true;
+  postApplyOracleRequired: true;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+}
+
+export interface LaunchAuthorizedApplySmokeReport {
+  schema: "zob.launch-authorized-apply-smoke.v1";
+  status: "passed" | "failed";
+  workerPool: ControlledWorkerPoolPlan;
+  eligibleGate: LaunchAuthorizedApplyGate;
+  blockedGate: LaunchAuthorizedApplyGate;
+  checks: Array<{ name: string; passed: boolean }>;
+  failedChecks: string[];
+  no_ship: boolean;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  generatedAt: string;
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+
+function stableStrings(values: unknown): string[] {
+  return Array.isArray(values) ? values.filter((value): value is string => typeof value === "string" && value.trim().length > 0).map((value) => value.trim()).sort() : [];
+}
+
+function hashStrings(values: string[]): string[] {
+  return values.map((value) => sha256(value)).sort();
+}
+
+function launchApplyPolicyMode(launchAuthorization: Record<string, unknown>): string | undefined {
+  const applyPolicy = isRecord(launchAuthorization.applyPolicy) ? launchAuthorization.applyPolicy : undefined;
+  return typeof applyPolicy?.mode === "string" ? applyPolicy.mode : undefined;
+}
+
+function launchAllowedPaths(launchAuthorization: Record<string, unknown>, fallback: string[] | undefined): string[] {
+  return stableStrings(fallback && fallback.length > 0 ? fallback : launchAuthorization.allowedPaths);
+}
+
+function launchForbiddenPaths(launchAuthorization: Record<string, unknown>, fallback: string[] | undefined): string[] {
+  return stableStrings(fallback && fallback.length > 0 ? fallback : launchAuthorization.forbiddenPaths);
+}
+
+function pathAllowed(repoRoot: string, path: string, allowedPaths: string[]): boolean {
+  return allowedPaths.some((allowedPath) => pathMatches(path, allowedPath, repoRoot, repoRoot));
+}
+
+function pathForbidden(repoRoot: string, path: string, forbiddenPaths: string[]): boolean {
+  return [...DEFAULT_RULES.zeroAccessPaths, ...forbiddenPaths].some((forbiddenPath) => pathMatches(path, forbiddenPath, repoRoot, repoRoot));
+}
+
+function validateChangedPaths(repoRoot: string, changedPaths: string[], allowedPaths: string[], forbiddenPaths: string[]): { allowed: boolean; forbiddenClear: boolean; blockers: string[] } {
+  const blockers: string[] = [];
+  for (const changedPath of changedPaths) {
+    const resolved = resolveRepoPath(repoRoot, changedPath);
+    blockers.push(...resolved.errors.map((error) => `changed_path:${error}`));
+    if (resolved.errors.length === 0 && !pathAllowed(repoRoot, changedPath, allowedPaths)) blockers.push(`changed_path_not_allowed:${changedPath}`);
+    if (pathForbidden(repoRoot, changedPath, forbiddenPaths)) blockers.push(`changed_path_forbidden:${changedPath}`);
+  }
+  return {
+    allowed: changedPaths.length > 0 && blockers.every((blocker) => !blocker.startsWith("changed_path_not_allowed") && !blocker.startsWith("changed_path:Path")),
+    forbiddenClear: blockers.every((blocker) => !blocker.startsWith("changed_path_forbidden")),
+    blockers,
+  };
+}
+
+export function buildControlledWorkerPoolPlan(input: { runId: string; maxParallelWorkers?: number; launchAuthorization?: Record<string, unknown> }): ControlledWorkerPoolPlan {
+  const maxParallelWorkers = Math.max(1, Math.min(8, Math.trunc(input.maxParallelWorkers ?? 4)));
+  const launchAuthorization = input.launchAuthorization ?? {};
+  const launchAuthorized = launchAuthorization.specLocked === true && launchAuthorization.userLaunchConfirmed === true && launchAuthorization.launchAuthorizesInScopeActions === true;
+  const lane = (kind: WorkerPoolLaneKind, index: number, outputContract: string): ControlledWorkerPoolLane => ({
+    laneId: safeFileStem(`${index}-${kind}`),
+    kind,
+    maxWorkers: kind === "implement" ? Math.max(1, Math.min(3, maxParallelWorkers - 1)) : 1,
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+    workspaceClaimRequired: true,
+    goalRoomEventsRequired: true,
+    todoClaimReducerRequired: true,
+    outputContract,
+  });
+  return {
+    schema: "zob.controlled-worker-pool-plan.v1",
+    runId: safeFileStem(input.runId),
+    maxParallelWorkers,
+    launchAuthorizationRequired: true,
+    strictBudgetRequired: true,
+    workerPoolEnabledByLaunch: launchAuthorized,
+    lanes: [
+      lane("context", 1, "context-pack.v1"),
+      lane("factory", 2, "factory.v1"),
+      lane("implement", 3, "implement.v1"),
+      lane("qa", 4, "qa.v1"),
+      lane("oracle", 5, "oracle.v1"),
+    ],
+    l5ControlledWorkerPool: true,
+    parentOwnedDispatch: true,
+    childDirectDispatch: false,
+    eventContract: "agent-event.v1",
+    todoReducerContract: "zob.todo-event-reducer-decision.v1",
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function evaluateLaunchAuthorizedApplyGate(repoRoot: string, input: LaunchAuthorizedApplyInput): LaunchAuthorizedApplyGate {
+  const launchAuthorization = input.launchAuthorization;
+  const changedPaths = stableStrings(input.changedPaths);
+  const allowedPaths = launchAllowedPaths(launchAuthorization, input.allowedPaths);
+  const forbiddenPaths = launchForbiddenPaths(launchAuthorization, input.forbiddenPaths);
+  const pathGate = validateChangedPaths(repoRoot, changedPaths, allowedPaths, forbiddenPaths);
+  const validationRefs = stableStrings(input.validationRefs);
+  const gates = {
+    specLocked: launchAuthorization.specLocked === true,
+    userLaunchConfirmed: launchAuthorization.userLaunchConfirmed === true,
+    launchAuthorizesInScopeActions: launchAuthorization.launchAuthorizesInScopeActions === true,
+    applyPolicyAutoApplyInScope: launchApplyPolicyMode(launchAuthorization) === "auto_apply_in_scope",
+    workerPoolControlled: input.workerPoolPlan?.l5ControlledWorkerPool === true && input.workerPoolPlan.parentOwnedDispatch === true && input.workerPoolPlan.childDirectDispatch === false,
+    changedPathsAllowed: pathGate.allowed,
+    forbiddenPathsClear: pathGate.forbiddenClear,
+    sandboxEvidencePresent: typeof input.sandboxRunId === "string" && input.sandboxRunId.trim().length > 0,
+    oracleReviewPresent: typeof input.oracleReviewRef === "string" && input.oracleReviewRef.trim().length > 0,
+    validationRefsPresent: validationRefs.length > 0,
+    diffHashPresent: SHA256_HEX.test(input.diffHash),
+  };
+  const blockers = [
+    ...(!gates.specLocked ? ["spec_not_locked"] : []),
+    ...(!gates.userLaunchConfirmed ? ["user_launch_not_confirmed"] : []),
+    ...(!gates.launchAuthorizesInScopeActions ? ["launch_does_not_authorize_in_scope_actions"] : []),
+    ...(!gates.applyPolicyAutoApplyInScope ? ["apply_policy_not_auto_apply_in_scope"] : []),
+    ...(!gates.workerPoolControlled ? ["l5_worker_pool_not_controlled"] : []),
+    ...(!gates.changedPathsAllowed ? ["changed_paths_not_allowed"] : []),
+    ...(!gates.forbiddenPathsClear ? ["changed_paths_hit_forbidden_policy"] : []),
+    ...(!gates.sandboxEvidencePresent ? ["sandbox_evidence_missing"] : []),
+    ...(!gates.oracleReviewPresent ? ["oracle_review_missing"] : []),
+    ...(!gates.validationRefsPresent ? ["validation_refs_missing"] : []),
+    ...(!gates.diffHashPresent ? ["diff_hash_missing_or_invalid"] : []),
+    ...pathGate.blockers,
+  ];
+  const applyEligible = blockers.length === 0;
+  return {
+    schema: "zob.launch-authorized-apply-gate.v1",
+    runId: safeFileStem(input.runId),
+    status: applyEligible ? "eligible_not_applied" : "blocked",
+    applyEligible,
+    autoApplyAuthorizedByLaunch: gates.specLocked && gates.userLaunchConfirmed && gates.launchAuthorizesInScopeActions && gates.applyPolicyAutoApplyInScope,
+    manualPerActionApprovalRequired: false,
+    exceptionApprovalRequiredOnlyForOutOfScope: true,
+    applyPerformed: false,
+    productionWritesPerformed: false,
+    changedPaths,
+    changedPathHashes: hashStrings(changedPaths),
+    diffHash: input.diffHash,
+    sandboxRunIdHash: input.sandboxRunId ? sha256(input.sandboxRunId) : undefined,
+    oracleReviewRef: input.oracleReviewRef,
+    validationRefs,
+    gates,
+    blockers,
+    l6LaunchAuthorizedApply: true,
+    parentOwnedApplyCoordinatorRequired: true,
+    rollbackRequired: true,
+    postApplyValidationRequired: true,
+    postApplyOracleRequired: true,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+}
+
+export function buildLaunchAuthorizedApplySmokeReport(repoRoot: string): LaunchAuthorizedApplySmokeReport {
+  const launchAuthorization = {
+    schema: "zob.launch-authorization.v1",
+    specLocked: true,
+    userLaunchConfirmed: true,
+    launchAuthorizesInScopeActions: true,
+    allowedPaths: ["docs/", ".pi/extensions/zob-harness/src/"],
+    forbiddenPaths: [".env", "**/.env*", "node_modules", "dist", "build"],
+    applyPolicy: { mode: "auto_apply_in_scope" },
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+  };
+  const workerPool = buildControlledWorkerPoolPlan({ runId: "launch-authorized-apply-smoke", maxParallelWorkers: 4, launchAuthorization });
+  const eligibleGate = evaluateLaunchAuthorizedApplyGate(repoRoot, {
+    runId: "launch-authorized-apply-smoke",
+    launchAuthorization,
+    workerPoolPlan: workerPool,
+    changedPaths: ["docs/ZOB_GENERAL_FACTORY_AGENT_L4_L6_MASTER_PLAN.md"],
+    diffHash: sha256("eligible launch-authorized smoke diff"),
+    sandboxRunId: "sandbox-launch-authorized-smoke",
+    oracleReviewRef: "reports/sandbox-manual-apply-preflight-smoke.json",
+    validationRefs: ["npm run check -- --pretty false", "npm run smoke:launch-authorized-apply"],
+  });
+  const blockedGate = evaluateLaunchAuthorizedApplyGate(repoRoot, {
+    runId: "launch-authorized-apply-smoke-blocked",
+    launchAuthorization: { ...launchAuthorization, userLaunchConfirmed: false, launchAuthorizesInScopeActions: false },
+    workerPoolPlan: workerPool,
+    changedPaths: [".env"],
+    diffHash: "invalid",
+    sandboxRunId: "sandbox-launch-authorized-smoke",
+    validationRefs: [],
+  });
+  const checks = [
+    { name: "l5_worker_pool_parent_owned", passed: workerPool.l5ControlledWorkerPool === true && workerPool.parentOwnedDispatch === true && workerPool.childDirectDispatch === false },
+    { name: "worker_pool_uses_events_and_todo_reducer", passed: workerPool.lanes.every((lane) => lane.goalRoomEventsRequired === true && lane.todoClaimReducerRequired === true) },
+    { name: "eligible_gate_authorizes_without_per_action_approval", passed: eligibleGate.applyEligible === true && eligibleGate.manualPerActionApprovalRequired === false && eligibleGate.autoApplyAuthorizedByLaunch === true },
+    { name: "eligible_gate_does_not_apply", passed: eligibleGate.applyPerformed === false && eligibleGate.productionWritesPerformed === false },
+    { name: "blocked_gate_rejects_missing_launch_and_forbidden_path", passed: blockedGate.applyEligible === false && blockedGate.blockers.includes("user_launch_not_confirmed") && blockedGate.blockers.some((blocker) => blocker.startsWith("changed_path_forbidden")) },
+    { name: "body_free", passed: eligibleGate.bodyStored === false && workerPool.bodyStored === false },
+  ];
+  const failedChecks = checks.filter((check) => !check.passed).map((check) => check.name);
+  return {
+    schema: "zob.launch-authorized-apply-smoke.v1",
+    status: failedChecks.length === 0 ? "passed" : "failed",
+    workerPool,
+    eligibleGate,
+    blockedGate,
+    checks,
+    failedChecks,
+    no_ship: failedChecks.length > 0,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    generatedAt: new Date().toISOString(),
+  };
+}

package/.pi/extensions/zob-harness/src/merge-queue.ts

@@ -0,0 +1,290 @@
+import { appendFileSync, mkdirSync, writeFileSync } 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 MergeCandidatePriority = "low" | "normal" | "high" | "critical";
+export type MergeCandidateRisk = "low" | "medium" | "high";
+export type MergeDecision = "approve_for_manual_apply" | "reject" | "needs_oracle";
+
+export interface MergeCandidateInput {
+  run_id: string;
+  submitted_by: string;
+  sandbox_run_id: string;
+  workspace_claim_ids: string[];
+  changed_paths: string[];
+  diff_hash: string;
+  validation_refs: string[];
+  summary_hash?: string;
+  todo_id?: string;
+  oracle_review_ref?: string;
+  rollback_ref?: string;
+  priority?: MergeCandidatePriority;
+  risk_level?: MergeCandidateRisk;
+}
+
+export interface MergeDecisionInput {
+  candidate_id: string;
+  decided_by: string;
+  decision: MergeDecision;
+  reason_hash: string;
+  oracle_review_ref?: string;
+}
+
+export interface MergeQueueListInput {
+  run_id?: string;
+  submitted_by?: string;
+  status?: string;
+  limit?: number;
+}
+
+export interface MergeCandidateRecord {
+  schema: "zob.merge-candidate.v1";
+  candidateId: string;
+  runId: string;
+  submittedBy: string;
+  todoId: string | null;
+  sandboxRunId: string;
+  workspaceClaimIds: string[];
+  changedPaths: string[];
+  changedPathHashes: string[];
+  diffHash: string;
+  validationRefs: string[];
+  oracleReviewRef: string | null;
+  rollbackRef: string | null;
+  summaryHash: string | null;
+  priority: MergeCandidatePriority;
+  riskLevel: MergeCandidateRisk;
+  status: "queued";
+  parentOwnedQueue: true;
+  sequentialApplyRequired: true;
+  oracleReviewRequired: boolean;
+  humanApprovalRequired: true;
+  applyPerformed: false;
+  productionWritesPerformed: false;
+  autoApply: false;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  queuedAt: string;
+}
+
+export interface MergeDecisionRecord {
+  schema: "zob.merge-decision.v1";
+  decisionId: string;
+  candidateId: string;
+  decidedBy: string;
+  decision: MergeDecision;
+  reasonHash: string;
+  oracleReviewRef: string | null;
+  parentOwnedDecision: true;
+  manualApplyOnly: true;
+  applyPerformed: false;
+  productionWritesPerformed: false;
+  autoApply: false;
+  bodyStored: false;
+  promptBodiesStored: false;
+  outputBodiesStored: false;
+  decidedAt: string;
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+const PRIORITIES = new Set<MergeCandidatePriority>(["low", "normal", "high", "critical"]);
+const RISKS = new Set<MergeCandidateRisk>(["low", "medium", "high"]);
+const DECISIONS = new Set<MergeDecision>(["approve_for_manual_apply", "reject", "needs_oracle"]);
+
+function mergeQueueDir(repoRoot: string): string {
+  return join(repoRoot, ".pi", "merge-queue");
+}
+
+function candidatesDir(repoRoot: string): string {
+  return join(mergeQueueDir(repoRoot), "candidates");
+}
+
+function candidatesPath(repoRoot: string): string {
+  return join(mergeQueueDir(repoRoot), "candidates.jsonl");
+}
+
+function decisionsPath(repoRoot: string): string {
+  return join(mergeQueueDir(repoRoot), "decisions.jsonl");
+}
+
+function eventsPath(repoRoot: string): string {
+  return join(mergeQueueDir(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 appendMergeEvent(repoRoot: string, event: Record<string, unknown>): void {
+  mkdirSync(mergeQueueDir(repoRoot), { recursive: true });
+  appendFileSync(eventsPath(repoRoot), `${JSON.stringify({ ...event, timestamp: new Date().toISOString(), bodyStored: false, promptBodiesStored: false, outputBodiesStored: false, applyPerformed: false, productionWritesPerformed: false, autoApply: false })}\n`, "utf8");
+}
+
+function validateRef(repoRoot: string, ref: string, label: string): string[] {
+  const errors: string[] = [];
+  if (typeof ref !== "string" || ref.trim().length === 0) return [`${label} contains an empty ref`];
+  if (ref.includes("\0")) errors.push(`${label} contains NUL byte: ${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}`);
+  }
+  return errors;
+}
+
+function validateCandidateInput(repoRoot: string, definition: TeamDefinition, input: MergeCandidateInput): 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.submitted_by)) errors.push(`Unknown merge candidate submitter '${input.submitted_by}'`);
+  if (!Array.isArray(input.workspace_claim_ids) || input.workspace_claim_ids.length === 0) errors.push("merge candidate requires workspace_claim_ids");
+  for (const claimId of input.workspace_claim_ids ?? []) {
+    if (!claimId || safeFileStem(claimId) !== claimId) errors.push(`workspace claim id must be path-safe: ${claimId}`);
+  }
+  if (!Array.isArray(input.changed_paths) || input.changed_paths.length === 0) errors.push("merge candidate requires changed_paths");
+  if (input.changed_paths.length > 100) errors.push("merge candidate changed_paths are capped at 100");
+  for (const changedPath of input.changed_paths ?? []) errors.push(...validateRef(repoRoot, changedPath, "changed_paths"));
+  if (!SHA256_HEX.test(input.diff_hash)) errors.push("merge candidate diff_hash must be sha256 hex");
+  if (input.summary_hash !== undefined && !SHA256_HEX.test(input.summary_hash)) errors.push("merge candidate summary_hash must be sha256 hex");
+  if (!Array.isArray(input.validation_refs) || input.validation_refs.length === 0) errors.push("merge candidate requires validation_refs");
+  for (const ref of input.validation_refs ?? []) errors.push(...validateRef(repoRoot, ref, "validation_refs"));
+  if (input.oracle_review_ref) errors.push(...validateRef(repoRoot, input.oracle_review_ref, "oracle_review_ref"));
+  if (input.rollback_ref) errors.push(...validateRef(repoRoot, input.rollback_ref, "rollback_ref"));
+  if (input.priority !== undefined && !PRIORITIES.has(input.priority)) errors.push("merge candidate priority must be low|normal|high|critical");
+  if (input.risk_level !== undefined && !RISKS.has(input.risk_level)) errors.push("merge candidate risk_level must be low|medium|high");
+  return errors;
+}
+
+function readCandidates(repoRoot: string): MergeCandidateRecord[] {
+  return readJsonl(candidatesPath(repoRoot)).filter(isMergeCandidateRecord).map((record) => record as unknown as MergeCandidateRecord);
+}
+
+function readDecisions(repoRoot: string): MergeDecisionRecord[] {
+  return readJsonl(decisionsPath(repoRoot)).filter(isMergeDecisionRecord).map((record) => record as unknown as MergeDecisionRecord);
+}
+
+function latestDecision(candidateId: string, decisions: MergeDecisionRecord[]): MergeDecisionRecord | undefined {
+  return decisions.filter((decision) => decision.candidateId === candidateId).at(-1);
+}
+
+export function submitMergeCandidate(repoRoot: string, definition: TeamDefinition, input: MergeCandidateInput): MergeCandidateRecord {
+  const errors = validateCandidateInput(repoRoot, definition, input);
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  const now = Date.now();
+  const changedPaths = [...new Set(input.changed_paths)].sort();
+  const candidateId = `merge_${sha256(`${input.run_id}:${input.submitted_by}:${input.sandbox_run_id}:${input.diff_hash}:${now}`).slice(0, 16)}`;
+  const candidate: MergeCandidateRecord = {
+    schema: "zob.merge-candidate.v1",
+    candidateId,
+    runId: input.run_id,
+    submittedBy: input.submitted_by,
+    todoId: input.todo_id ?? null,
+    sandboxRunId: input.sandbox_run_id,
+    workspaceClaimIds: [...new Set(input.workspace_claim_ids)].sort(),
+    changedPaths,
+    changedPathHashes: changedPaths.map((path) => sha256(path)),
+    diffHash: input.diff_hash,
+    validationRefs: [...new Set(input.validation_refs)].sort(),
+    oracleReviewRef: input.oracle_review_ref ?? null,
+    rollbackRef: input.rollback_ref ?? null,
+    summaryHash: input.summary_hash ?? null,
+    priority: input.priority ?? "normal",
+    riskLevel: input.risk_level ?? "medium",
+    status: "queued",
+    parentOwnedQueue: true,
+    sequentialApplyRequired: true,
+    oracleReviewRequired: input.oracle_review_ref === undefined,
+    humanApprovalRequired: true,
+    applyPerformed: false,
+    productionWritesPerformed: false,
+    autoApply: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    queuedAt: new Date(now).toISOString(),
+  };
+  mkdirSync(candidatesDir(repoRoot), { recursive: true });
+  appendFileSync(candidatesPath(repoRoot), `${JSON.stringify(candidate)}\n`, "utf8");
+  writeFileSync(join(candidatesDir(repoRoot), `${candidateId}.json`), JSON.stringify(candidate, null, 2), "utf8");
+  appendMergeEvent(repoRoot, { event: "candidate_queued", candidateId, runId: candidate.runId, submittedBy: candidate.submittedBy, applyPerformed: false, productionWritesPerformed: false, autoApply: false });
+  return candidate;
+}
+
+export function decideMergeCandidate(repoRoot: string, definition: TeamDefinition, input: MergeDecisionInput): MergeDecisionRecord {
+  if (!input.candidate_id || safeFileStem(input.candidate_id) !== input.candidate_id) throw new Error(`candidate_id must be path-safe: ${input.candidate_id}`);
+  if (!knownRoleIds(definition).has(input.decided_by)) throw new Error(`Unknown merge decision actor '${input.decided_by}'`);
+  if (!DECISIONS.has(input.decision)) throw new Error("merge decision must be approve_for_manual_apply|reject|needs_oracle");
+  if (!SHA256_HEX.test(input.reason_hash)) throw new Error("merge decision reason_hash must be sha256 hex");
+  const candidate = readCandidates(repoRoot).find((item) => item.candidateId === input.candidate_id);
+  if (!candidate) throw new Error(`merge candidate not found: ${input.candidate_id}`);
+  const errors = input.oracle_review_ref ? validateRef(repoRoot, input.oracle_review_ref, "oracle_review_ref") : [];
+  if (input.decision === "approve_for_manual_apply" && !input.oracle_review_ref && candidate.oracleReviewRequired) errors.push("approve_for_manual_apply requires oracle_review_ref when candidate lacks prior oracle review");
+  if (errors.length > 0) throw new Error(errors.join("; "));
+  const decision: MergeDecisionRecord = {
+    schema: "zob.merge-decision.v1",
+    decisionId: `mdecision_${sha256(`${input.candidate_id}:${input.decided_by}:${input.decision}:${Date.now()}`).slice(0, 16)}`,
+    candidateId: input.candidate_id,
+    decidedBy: input.decided_by,
+    decision: input.decision,
+    reasonHash: input.reason_hash,
+    oracleReviewRef: input.oracle_review_ref ?? null,
+    parentOwnedDecision: true,
+    manualApplyOnly: true,
+    applyPerformed: false,
+    productionWritesPerformed: false,
+    autoApply: false,
+    bodyStored: false,
+    promptBodiesStored: false,
+    outputBodiesStored: false,
+    decidedAt: new Date().toISOString(),
+  };
+  mkdirSync(mergeQueueDir(repoRoot), { recursive: true });
+  appendFileSync(decisionsPath(repoRoot), `${JSON.stringify(decision)}\n`, "utf8");
+  appendMergeEvent(repoRoot, { event: "decision_recorded", candidateId: decision.candidateId, decision: decision.decision, applyPerformed: false, productionWritesPerformed: false, autoApply: false });
+  return decision;
+}
+
+export function listMergeQueue(repoRoot: string, input: MergeQueueListInput = {}): Array<MergeCandidateRecord & { latestDecision?: MergeDecisionRecord }> {
+  const decisions = readDecisions(repoRoot);
+  const limit = Math.max(1, Math.min(100, Math.floor(input.limit ?? 20)));
+  return readCandidates(repoRoot)
+    .map((candidate) => ({ ...candidate, latestDecision: latestDecision(candidate.candidateId, decisions) }))
+    .filter((candidate) => !input.run_id || candidate.runId === input.run_id)
+    .filter((candidate) => !input.submitted_by || candidate.submittedBy === input.submitted_by)
+    .filter((candidate) => !input.status || candidate.latestDecision?.decision === input.status || (!candidate.latestDecision && candidate.status === input.status))
+    .slice(-limit);
+}
+
+export function mergeQueueBodyFreeViolations(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 isMergeCandidateRecord(value: unknown): value is MergeCandidateRecord {
+  return isRecord(value) && value.schema === "zob.merge-candidate.v1" && typeof value.candidateId === "string" && value.bodyStored === false && value.applyPerformed === false && value.autoApply === false;
+}
+
+export function isMergeDecisionRecord(value: unknown): value is MergeDecisionRecord {
+  return isRecord(value) && value.schema === "zob.merge-decision.v1" && typeof value.candidateId === "string" && value.bodyStored === false && value.applyPerformed === false && value.autoApply === false;
+}