omp-conductor 0.17.1 → 0.18.1

package/src/config-schema.ts

@@ -31,6 +31,8 @@ import {
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_STRICTNESS,
   DRAFT_POLICIES,
   INTERRUPT_CATEGORIES,
   LEGACY_RELEASE_POLICIES,
@@ -39,6 +41,9 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   WEEKDAYS,
   DIGEST_CADENCES,
 } from "./types.ts";
@@ -65,6 +70,7 @@ const RELEASE_REQUIREMENT_LIST = quoteList(RELEASE_REQUIREMENTS);
 const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
 const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
 const LEGACY_RELEASE_POLICY_LIST = quoteList(LEGACY_RELEASE_POLICIES);
+const REVIEW_STRICTNESS_LIST = quoteList(REVIEW_STRICTNESS);
 
 // ---------------------------------------------------------------------------
 // Closed vocabularies — every one built from the exported `as const` array in
@@ -83,6 +89,7 @@ const releaseRequirementEnum = z.enum([...RELEASE_REQUIREMENTS]);
 const releaseShapeEnum = z.enum([...RELEASE_SHAPES]);
 const orchestratorModeEnum = z.enum([...ORCHESTRATOR_MODES]);
 const releasePolicyLegacyEnum = z.enum([...LEGACY_RELEASE_POLICIES]);
+const reviewStrictnessEnum = z.enum([...REVIEW_STRICTNESS]);
 
 /** The 24-hour `HH:MM` shape `digest.at` / `availability.start/end` take. */
 const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
@@ -256,6 +263,27 @@ const armSchema = z
   .strict()
   .describe("How `arm` proves a human just approved arming");
 
+/**
+ * The per-project review policy (#678): how strictly green PRs are reviewed
+ * and returned, and the hard ceiling on review rounds per PR lifecycle. Absent
+ * or a legacy config without the key loads as `medium` with
+ * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds — the recommended default for a new
+ * project, materialised deterministically for every existing one, with the
+ * schema bounds and the runtime defaults read from the same constants.
+ */
+const reviewSchema = z
+  .object({
+    strictness: reviewStrictnessEnum.default(DEFAULT_REVIEW_STRICTNESS),
+    maxRounds: z
+      .number()
+      .int()
+      .min(REVIEW_MAX_ROUNDS_MIN)
+      .max(REVIEW_MAX_ROUNDS_MAX)
+      .default(DEFAULT_REVIEW_MAX_ROUNDS),
+  })
+  .strict()
+  .describe("Review strictness and round ceiling for green PRs");
+
 const releasePolicySchema = z.union([
   releasePolicyLegacyEnum,
   z.record(z.string(), authorityHolderEnum),
@@ -304,9 +332,29 @@ const stateLabelsSchema = z
     inProgress: z.unknown(),
     blocked: z.unknown(),
     failed: z.unknown(),
+    backlog: z.unknown(),
   })
   .partial();
 
+// ---------------------------------------------------------------------------
+// Host constraints (#721)
+// ---------------------------------------------------------------------------
+
+const hostConstraintsSchema = z
+  .object({
+    description: z.string().min(1).describe("What this host is and what else it runs"),
+    path: z
+      .string()
+      .min(1)
+      .describe('The non-interactive PATH a script or `ssh host "<cmd>"` invocation must export'),
+    conventions: z
+      .record(z.string().min(1), z.string().min(1))
+      .describe("Per-repo command conventions, keyed by the brief's `owner/repo` slug"),
+  })
+  .strict()
+  .partial()
+  .describe("Operator-authored host facts rendered into every worker brief");
+
 // ---------------------------------------------------------------------------
 // Project / root
 // ---------------------------------------------------------------------------
@@ -350,6 +398,9 @@ const projectSchema = z
     // How `arm` proves a human approved arming (#613); absent loads as
     // `challenge`, preserving today's authenticated round-trip.
     arm: armSchema.optional(),
+    // Review strictness and the round ceiling (#678); absent loads as the
+    // documented migration default.
+    review: reviewSchema.optional(),
     authority: authoritySchema.optional(),
     releasePolicy: releasePolicySchema.optional(),
     policy: projectPolicySchema.optional(),
@@ -377,6 +428,11 @@ const configSchema = z
       .min(1, "must name a directory")
       .optional()
       .describe("Absolute directory for restorable conductor.db snapshots; defaults to <stateDir>/backups/db"),
+    // Cores and RAM are derived by host.ts at render time; only what the
+    // operator must type belongs in this block.
+    host: hostConstraintsSchema
+      .optional()
+      .describe("Host facts every worker brief renders; absent renders no section"),
     projects: z.array(projectSchema).min(1, `"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`),
   })
   .loose()
@@ -448,4 +504,5 @@ export {
   RELEASE_SHAPE_LIST,
   ORCHESTRATOR_MODE_LIST,
   LEGACY_RELEASE_POLICY_LIST,
+  REVIEW_STRICTNESS_LIST,
 };

package/src/config.ts

@@ -28,6 +28,9 @@ import {
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DEFAULT_REVIEW_MAX_ROUNDS,
+  DEFAULT_REVIEW_POLICY,
+  DEFAULT_REVIEW_STRICTNESS,
   DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
   LEGACY_RELEASE_POLICIES,
@@ -37,12 +40,16 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_MAX_ROUNDS_MAX,
+  REVIEW_MAX_ROUNDS_MIN,
+  REVIEW_STRICTNESS,
   INTERRUPT_CATEGORIES,
   DIGEST_CADENCES,
   WEEKDAYS,
   type Caps,
   type ConductorConfig,
   type DigestCadence,
+  type HostConstraints,
   type InterruptCategory,
   type MergePreconditions,
   type PlanUsageCap,
@@ -53,6 +60,8 @@ import {
   type ReleaseRequirement,
   type ReportScope,
   type ReportingPolicy,
+  type ReviewPolicy,
+  type ReviewStrictness,
   type Weekday,
   type WeeklyAvailability,
   type RepoTarget,
@@ -71,6 +80,7 @@ import {
   ORCHESTRATOR_MODE_LIST,
   RELEASE_REQUIREMENT_LIST,
   RELEASE_SHAPE_LIST,
+  REVIEW_STRICTNESS_LIST,
   REPORT_SCOPE_LIST,
   WEEKDAY_LIST,
   quoteList,
@@ -98,10 +108,13 @@ const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
  * Used when a project omits `stateLabels`. Namespaced so a human scanning the
  * tracker can tell dispatcher-written labels from their own.
  */
-const DEFAULT_STATE_LABELS: ProjectConfig["stateLabels"] = {
+export const DEFAULT_STATE_LABELS: ProjectConfig["stateLabels"] = {
   inProgress: "agent:in-progress",
   blocked: "agent:blocked",
   failed: "agent:failed",
+  // The operator's park gesture (#507): unnamed by design — it is theirs, and
+  // the operator adds it by hand until setup grows a confirm step (slice 2).
+  backlog: "backlog",
 };
 
 /**
@@ -330,6 +343,20 @@ export function resolveArmProof(p: ProjectConfig): ArmProof {
   return p.arm?.proof === "claim-only" ? "claim-only" : DEFAULT_ARM_PROOF;
 }
 
+/**
+ * The project's review policy (#678), complete.
+ *
+ * The loader always materialises `review` (finalizeProject), so this is only
+ * ever the fallback for a `ProjectConfig` that never went through it — a
+ * hand-built one in a test, or a config written before the key existed.
+ * Absent resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration
+ * default every existing install deterministically upgrades to. A fresh object
+ * each call, so mutating the result cannot reach the config it came from.
+ */
+export function resolveReview(p: ProjectConfig): ReviewPolicy {
+  return { ...(p.review ?? DEFAULT_REVIEW_POLICY) };
+}
+
 /**
  * A policy with no array shared with its source.
  *
@@ -861,6 +888,12 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
     if (rel.length === 1 && relStr === "policy") {
       return `policy must be an object with "merge" and "release" sections`;
     }
+    if (rel.length === 1 && relStr === "review") {
+      return `review must be an object with "strictness" and "maxRounds"`;
+    }
+    if (rel.length === 2 && rel[0] === "review" && rel[1] === "maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     if (rel.length === 2 && relStr === "policy") return `${pathStr} must be an object`;
     if (rel.length === 1 && relStr === "caps") return `caps must be an object`;
     if (rel.length === 2 && relStr === "caps" && rel[1] === "planUsage") {
@@ -911,6 +944,7 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   if (issue.code === "unrecognized_keys") {
     const keys = (issue.keys ?? []).join(", ");
     if (pathStr === "policy") return `policy has unknown key(s): ${keys} — expected "merge" or "release"`;
+    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness" and "maxRounds"`;
     if (pathStr === "policy.merge") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_MERGE_KEYS}`;
     if (pathStr === "policy.release") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_RELEASE_KEYS}`;
     if (pathStr === "caps.planUsage") {
@@ -960,6 +994,9 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
 
   // Regex / custom-message failures carry the finding in issue.message.
   if (issue.code === "too_small") {
+    if (pathStr === "review.maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     // Empty array (reporting.interruptOn, availability.days) has its own line.
     if (parentOf(rel) === "reporting.interruptOn") return `reporting.interruptOn must name at least one category`;
     if (pathStr === "reporting.availability.days") return `reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`;
@@ -975,6 +1012,9 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   }
 
   if (issue.code === "too_big") {
+    if (pathStr === "review.maxRounds") {
+      return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
+    }
     if (rel.length === 2 && rel[0] === "caps") return capProblem(rel[1] as string, found());
     if (pathStr === "caps.planUsage.maxUsedFraction") {
       return `caps.planUsage.maxUsedFraction must be a fraction between 0 and 1 (0.85 holds at 85% of the allowance), found ${found()}`;
@@ -1053,8 +1093,48 @@ function finalize(data: unknown, path: string): ConductorConfig {
     });
   }
 
+  const rawHost = root["host"] as Raw | undefined;
+  const host = finalizeHost(rawHost);
+  const rawDbBackupDir = root["dbBackupDir"];
+  const dbBackupDir = typeof rawDbBackupDir === "string" ? rawDbBackupDir : undefined;
+
   if (problems.length > 0) throw new Error(problemEnvelope(path, problems));
-  return { version: CONFIG_VERSION, defaults, projects };
+  // `ConductorConfig` is rebuilt here, so every optional top-level key must be
+  // spelled out or it silently vanishes from every loaded config. `dbBackupDir`
+  // and `host` are the two today; a third needs its own line below (#773).
+  return {
+    version: CONFIG_VERSION,
+    defaults,
+    projects,
+    ...(dbBackupDir === undefined ? {} : { dbBackupDir }),
+    ...(host === undefined ? {} : { host }),
+  };
+}
+
+/**
+ * The typed host-constraints block (#721), or `undefined` when nothing usable
+ * was configured — matching the schema's "absent renders no section" promise.
+ * Trimming and empty-drop mirror the other hand-edited string fields; an
+ * object whose every key is empty loads as if the field were absent.
+ */
+function finalizeHost(parsed: Raw | undefined): HostConstraints | undefined {
+  if (parsed === undefined) return undefined;
+  const out: HostConstraints = {};
+  const description = parsed["description"];
+  if (typeof description === "string" && description.trim() !== "") out.description = description.trim();
+  const path = parsed["path"];
+  if (typeof path === "string" && path.trim() !== "") out.path = path.trim();
+  const conventions = parsed["conventions"];
+  if (typeof conventions === "object" && conventions !== null && !Array.isArray(conventions)) {
+    const kept: Record<string, string> = {};
+    for (const [slug, value] of Object.entries(conventions as Record<string, unknown>)) {
+      if (typeof value === "string" && value.trim() !== "" && slug.trim() !== "") {
+        kept[slug.trim()] = value.trim();
+      }
+    }
+    if (Object.keys(kept).length > 0) out.conventions = kept;
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
 }
 
 function finalizeProject(
@@ -1101,6 +1181,7 @@ function finalizeProject(
     );
   }
   const policy = finalizePolicy(p["policy"], label, problems);
+  const review = finalizeReview(p["review"] as Raw | undefined);
   const caps = reconcileCaps(p["caps"], `${label}: caps`, problems, legacyCaps);
   const reporting = finalizeReporting(p["reporting"], label, problems);
   const recoveryMerges = (p["recoveryMerges"] as RecoveryMergeAuthorization[] | undefined)?.map(
@@ -1199,6 +1280,7 @@ function finalizeProject(
       inProgress: pickString(stateLabels?.["inProgress"], DEFAULT_STATE_LABELS.inProgress),
       blocked: pickString(stateLabels?.["blocked"], DEFAULT_STATE_LABELS.blocked),
       failed: pickString(stateLabels?.["failed"], DEFAULT_STATE_LABELS.failed),
+      backlog: pickString(stateLabels?.["backlog"], DEFAULT_STATE_LABELS.backlog),
     },
     routing: { labelPrefix, repos },
     caps,
@@ -1208,6 +1290,7 @@ function finalizeProject(
     ...(effectiveOmpSettings === undefined ? {} : { ompSettings: effectiveOmpSettings }),
     escalation,
     arm,
+    review,
     authority,
     releasePolicy,
     policy,
@@ -1231,6 +1314,23 @@ function finalizeArm(parsed: Raw | undefined): ProjectConfig["arm"] {
   return { proof: (parsed["proof"] as ArmProof | undefined) ?? DEFAULT_ARM_PROOF };
 }
 
+/**
+ * The project's review policy (#678), complete. A config written before the
+ * key existed — or one that never answered — materialises as
+ * {@link DEFAULT_REVIEW_POLICY}, the documented migration default, so an
+ * upgrade changes no existing project's behaviour beyond what its operators
+ * then choose in setup. zod has already rejected anything outside the
+ * strictness vocabulary or the validated round range, so this only fills the
+ * absent-case default.
+ */
+function finalizeReview(parsed: Raw | undefined): ProjectConfig["review"] {
+  if (parsed === undefined) return { ...DEFAULT_REVIEW_POLICY };
+  return {
+    strictness: (parsed["strictness"] as ReviewStrictness | undefined) ?? DEFAULT_REVIEW_STRICTNESS,
+    maxRounds: (parsed["maxRounds"] as number | undefined) ?? DEFAULT_REVIEW_MAX_ROUNDS,
+  };
+}
+
 function finalizeEscalation(parsed: Raw | undefined): ProjectConfig["escalation"] {
   if (parsed === undefined) {
     return { fallbackToIssueComment: true, orchestrator: "embedded" };