@patronage/software-factory 1.0.0-alpha.36 → 1.0.0-alpha.37

package/README.md

@@ -4,7 +4,7 @@
 
 The factory admits a pull request from evidence bound to its candidate. It validates policy and proof; it does not schedule workers, choose models, or run reviews. Those are jobs for the harness or operator.
 
-Admission is fail closed. A clean-session review and required verification produce typed proof, then readiness decides whether the candidate may proceed. Evidence stays current when the candidate patch is unchanged; the push-triggered Verify workflow covers integration risk on every factory merge target — `main` and the `epic/**` integration branches. When a target goes red, the factory refuses new readiness decisions and authorized arming against that target; candidates armed before the target went red can still land. Epic policy, including review minimums and auto-merge authority, lives in the boundary manifest. HQ observes this work; it never blocks a gate.
+Admission is fail closed. A clean-session review and required verification produce typed proof, then readiness decides whether the candidate may proceed. Evidence stays current when the candidate patch is unchanged; the push-triggered Verify workflow covers integration risk on every factory merge target — `main` and the `epic/**` integration branches. When a target goes red, the factory refuses new readiness decisions and authorized arming against that target; candidates armed before the target went red can still land. `pr:ready` arms GitHub native auto-merge for every admitted pull request. It does not arm when the repository does not allow auto-merge, when the pull request carries the `factory:hold` label, or when a boundary wave keeps the candidate attended. Epic policy, including review minimums and the auto-merge decision for its members, lives in the boundary manifest. HQ observes this work; it never blocks a gate.
 
 ## Develop the package
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
-import { z } from "zod";
 import { existsSync, readFileSync, rmSync } from "node:fs";
+import { z } from "zod";
 import { PreviewProofRegistration } from "@patronage/factory-ci";
 import { JsonValue, Questions, SystemOneRequest, choice, noul, score } from "@typesafe-ai/sdk";
 
@@ -948,10 +948,18 @@ declare const blockedReasonSchema: z.ZodObject<{
 type BlockedReason = z.infer<typeof blockedReasonSchema>;
 //#endregion
 //#region src/arm-auto-merge.d.ts
+/**
+ * How GitHub merges the candidate. `pr:ready` chooses `merge` for a
+ * recognized faithful catch-up merge (ADR 0028), because a squash drops the
+ * second parent and the target loses the merged base as an ancestor (#829).
+ * Every other candidate is squashed.
+ */
+type AutoMergeMethod = "merge" | "squash";
 interface ArmAutoMergeInput {
   cwd: string;
   /** The validated PR head this arming is a compare-and-set against. */
   headSha: string;
+  mergeMethod: AutoMergeMethod;
   owner: string;
   pr: number;
   repo: string;
@@ -1660,8 +1668,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    stale: "stale";
     active: "active";
+    stale: "stale";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1950,9 +1958,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1962,9 +1970,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -2611,11 +2619,13 @@ interface PrReadyProof {
   schemaVersion: 3;
   /**
    * What GitHub actually did when this run armed native auto-merge (#477).
-   * Present exactly when a ready wave authorizes machine merge and arming ran;
-   * read back from the PR rather than inferred from the invocation, because `gh pr merge
-   * --auto` arms, merges, or does nothing with the same exit code and the same
-   * empty output. `not-armed` means the candidate is admitted but nothing will
-   * merge it, and `followUp` carries the re-dispatch.
+   * Present exactly when a ready run called the arming module (#1299): not
+   * for an `autoMerge: false` wave, and not when a notice names why the run
+   * did not arm. Read back from the PR rather than inferred from the
+   * invocation, because `gh pr merge --auto` arms, merges, or does nothing
+   * with the same exit code and the same empty output. `not-armed` means the
+   * candidate is admitted but nothing will merge it, and `followUp` carries
+   * the re-dispatch.
    */
   arming?: {
     detail?: string;
@@ -2687,13 +2697,61 @@ interface PrReadyProof {
    */
   waivedDemands?: WaivedDemand[];
 }
+/** An issue's sub-issue parent, as the membership rule reads it (#1299). */
+interface IssueParent {
+  labels: string[];
+  number: number;
+  state: string;
+}
+/** What `pr:ready` reads about one pull request before it arms (#1299). */
+interface PullRequestArmingFacts {
+  /** GitHub's per-repository "Allow auto-merge" setting. */
+  autoMergeAllowed: boolean;
+  /**
+   * GitHub's closing references for the pull request to issues in its own
+   * repository, with their parents.
+   */
+  closingIssues: {
+    number: number;
+    parent: IssueParent | null;
+  }[];
+  /**
+   * GitHub has more closing references than the one page `pr:ready` reads,
+   * so `closingIssues` is not the whole set.
+   */
+  closingIssuesIncomplete: boolean;
+  labels: string[];
+}
+/**
+ * The GitHub reads behind the reasons not to arm an admitted candidate
+ * (#1299). A read throws when GitHub cannot answer; `pr:ready` then does not
+ * arm, and its notice says which read failed.
+ */
+interface ArmingPolicyReads {
+  /** One issue's sub-issue parent, or `null` when it has none. */
+  readIssueParent: (input: {
+    issue: number;
+    owner: string;
+    repo: string;
+  }) => IssueParent | null;
+  readPullRequest: (input: {
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => PullRequestArmingFacts;
+}
 interface PrReadyDependencies {
   /**
-   * Arms GitHub native auto-merge only for a passing boundary wave that
-   * authorizes machine merge (#477). Defaults to the real `gh pr merge --auto`
-   * call plus the read-back that says what actually happened.
+   * Arms GitHub native auto-merge for an admitted candidate (#477, #1299).
+   * Defaults to the real `gh pr merge --auto` call plus the read-back that
+   * says what actually happened.
    */
   armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
+  /**
+   * The GitHub reads behind the reasons not to arm (#1299). Defaults to the
+   * real GraphQL reads.
+   */
+  armingPolicy?: ArmingPolicyReads;
   /**
    * Reads the authoritative base review policy (#922): the profile committed at
    * the live tip of the PR's own base ref. Defaults to the real GitHub reads,
@@ -2935,9 +2993,9 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
   "not-required": "not-required";
+  stale: "stale";
   blocked: "blocked";
   current: "current";
-  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -3445,11 +3503,12 @@ interface PrPublishHandoff {
   routeOwnedRepairs: ReadinessRepair[];
   /**
    * Whether the merge is actually on GitHub's schedule (#477, #515 review).
-   * An admitted candidate is not a handed-off one: `pr:ready` arms only when a
-   * boundary wave authorized it, and the arming can fail to take effect. A
+   * An admitted candidate is not a handed-off one: `pr:ready` does not arm
+   * when the repository does not allow auto-merge, the pull request carries
+   * `factory:hold`, a boundary wave keeps it attended, or it is an epic member
+   * run without `--epic` (#1299), and the arming can fail to take effect. A
    * readiness status of `ready` says the candidate passed, never that anything
-   * will merge it — only an auto-merge-authorized boundary wave can schedule
-   * one — so publish reads this before claiming nothing is owed.
+   * will merge it, so publish reads this before claiming nothing is owed.
    */
   scheduled: boolean;
   status: PrReadyProof["status"];
@@ -4824,11 +4883,125 @@ interface EvaluationInput {
   waivers?: DemandWaiver[];
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  humanBlockingReasons: string[];
+  ledger: {
+    baseSha: string;
+    blockingReasons: string[];
+    classification: "docs/process-only" | "trivial" | "non-trivial";
+    github: {
+      draft: boolean;
+      mergeStateStatus: string;
+      mergeable: string;
+      requiredChecks: "unknown" | "pending" | "passed" | "failed" | "none";
+      unresolvedReviewThreads: number;
+      reviewDecision?: string | null | undefined;
+    };
+    headSha: string;
+    patchId: string;
+    pr: number;
+    repairs: {
+      action: string;
+      code: "undraft-pr" | "await-post-undraft-checks";
+      command: string;
+    }[];
+    reviews: {
+      correctness: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      };
+      security?: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      } | undefined;
+    };
+    schemaVersion: 2;
+    verification: {
+      command: "patronage-factory pr:verify";
+      prVerify: "missing";
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "stale";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "passed-via-head";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      docsOnlyVerifiedHeadSha: string;
+      prVerify: "docs-only-delta";
+      verifiedHeadSha?: string | undefined;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "trivial-delta";
+      trivialVerifiedHeadSha: string;
+      verifiedHeadSha?: string | undefined;
+    };
+    externalChecks?: {
+      checkType: "review" | "verify";
+      name: string;
+      scopeReason: string;
+      status: "satisfied" | "unmet" | "out-of-scope";
+      reason?: string | undefined;
+      scope?: {
+        classifications: ("docs/process-only" | "trivial" | "non-trivial")[];
+      } | undefined;
+    }[] | undefined;
+    mergeBaseSha?: string | undefined;
+    reviewCycleState?: {
+      autoBlockingFindings: number;
+      countsBySeverity: {
+        critical: number;
+        high: number;
+        low: number;
+        medium: number;
+        unknown: number;
+      };
+      nonBlockingFindings: number;
+      openFindings: number;
+      windowExhausted: boolean;
+      highestBlockingSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      highestOpenSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      maxReviewCycles?: number | undefined;
+      reviewCycle?: number | undefined;
+      staleRepeatFindings?: number | undefined;
+    } | undefined;
+    reviewLadder?: {
+      cycleCounts: {
+        gate: number;
+        interior: number;
+      };
+      nextAction: "run-interior-cycle" | "advance-to-gate" | "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human";
+      stage: "interior" | "gate" | "interior-complete";
+      forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
+    } | undefined;
+    reviewRuns?: PrReviewResult[] | undefined;
+    reviewTerminalState?: "blocked" | "accepted-with-findings" | "clean" | undefined;
+  };
+  /**
+   * Facts a reader needs that are not refusals (#477): the settle-window
+   * arming notice, and every waived demand rendered so it can never read as
+   * a met one.
+   */
+  notices: string[];
+  repairs: {
+    action: string;
+    code: "undraft-pr" | "await-post-undraft-checks";
+    command: string;
+  }[];
+  status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
+  waivedDemands: WaivedDemand[];
+  catchUpRecognition: CatchUpRecognition;
   blockedReasons: {
     code: string;
     detail: string;
   }[];
   blockingReasons: string[];
+} | {
   humanBlockingReasons: string[];
   ledger: {
     baseSha: string;
@@ -4853,13 +5026,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4941,6 +5114,12 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
   }[];
   status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
   waivedDemands: WaivedDemand[];
+  catchUpRecognition?: undefined;
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
+  blockingReasons: string[];
 };
 //#endregion
 //#region src/evidence-emit.d.ts