merge-steward 0.22.5 → 0.24.0

package/dist/config.d.ts

@@ -30,6 +30,9 @@ export declare const stewardConfigSchema: z.ZodObject<{
     admissionLabel: z.ZodDefault<z.ZodString>;
     priorityQueueLabel: z.ZodDefault<z.ZodString>;
     mergeQueueCheckName: z.ZodDefault<z.ZodString>;
+    evictionCheckName: z.ZodDefault<z.ZodString>;
+    specReadyCheckName: z.ZodDefault<z.ZodString>;
+    specBranchPrefix: z.ZodDefault<z.ZodString>;
     excludeBranches: z.ZodDefault<z.ZodArray<z.ZodString>>;
     autoResolvePatterns: z.ZodDefault<z.ZodArray<z.ZodObject<{
         glob: z.ZodString;

package/dist/config.js

@@ -31,6 +31,21 @@ export const stewardConfigSchema = z.object({
     admissionLabel: z.string().default("queue"),
     priorityQueueLabel: z.string().default("queue:priority"),
     mergeQueueCheckName: z.string().default(DEFAULT_MERGE_QUEUE_CHECK_NAME),
+    // Plan §2.4 — bus-contract artifact names exposed for cross-service
+    // alignment. Defaults preserve current behavior. The steward writes
+    // `evictionCheckName` (today: same as mergeQueueCheckName, kept for
+    // contract clarity) and `specReadyCheckName`; consumers read them.
+    /** Eviction check run name. Synonym for mergeQueueCheckName, surfaced
+     * under the bus-contract name so consumer code can be naming-aligned
+     * with patchrelay's resolver. */
+    evictionCheckName: z.string().default(DEFAULT_MERGE_QUEUE_CHECK_NAME),
+    /** Spec-ready check run name (default: "merge-steward/spec-ready").
+     * Read by review-quill in integration_tree mode (plan §3.5). */
+    specReadyCheckName: z.string().default("merge-steward/spec-ready"),
+    /** Prefix for spec branch names (default: "mq-spec-"); matches the
+     * existing SPEC_BRANCH_PREFIX in reconciler-core.ts. The pattern
+     * review-quill matches against is `${prefix}*`. */
+    specBranchPrefix: z.string().default("mq-spec-"),
     /** Branch name patterns to exclude from admission (glob-style). */
     excludeBranches: z.array(z.string()).default([]),
     /**

package/dist/github/check-run-reporter.d.ts

@@ -12,6 +12,8 @@ export declare class GitHubCheckRunReporter implements EvictionReporter {
     private readonly publicBaseUrl?;
     private readonly admissionLabel;
     private readonly mergeQueueCheckName;
-    constructor(repoFullName: string, serverHost: string, serverPort: number, publicBaseUrl?: string | undefined, admissionLabel?: string, mergeQueueCheckName?: string);
+    private readonly specReadyCheckName;
+    constructor(repoFullName: string, serverHost: string, serverPort: number, publicBaseUrl?: string | undefined, admissionLabel?: string, mergeQueueCheckName?: string, specReadyCheckName?: string);
     reportEviction(entry: QueueEntry, incident: IncidentRecord): Promise<void>;
+    reportSpecReady(entry: QueueEntry, specBranch: string, specSha: string): Promise<void>;
 }

package/dist/github/check-run-reporter.js

@@ -4,6 +4,9 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { exec } from "../exec.js";
 import { DEFAULT_MERGE_QUEUE_CHECK_NAME } from "../config.js";
+// Plan §5.2 default — review-quill subscribes by default; configurable
+// per project via the bus contract added in PR 1.
+const DEFAULT_SPEC_READY_CHECK_NAME = "merge-steward/spec-ready";
 /**
  * Reports evictions by creating a GitHub check run on the PR's head SHA.
  * The check run output contains the incident context as structured JSON.
@@ -16,13 +19,15 @@ export class GitHubCheckRunReporter {
     publicBaseUrl;
     admissionLabel;
     mergeQueueCheckName;
-    constructor(repoFullName, serverHost, serverPort, publicBaseUrl, admissionLabel = "queue", mergeQueueCheckName = DEFAULT_MERGE_QUEUE_CHECK_NAME) {
+    specReadyCheckName;
+    constructor(repoFullName, serverHost, serverPort, publicBaseUrl, admissionLabel = "queue", mergeQueueCheckName = DEFAULT_MERGE_QUEUE_CHECK_NAME, specReadyCheckName = DEFAULT_SPEC_READY_CHECK_NAME) {
         this.repoFullName = repoFullName;
         this.serverHost = serverHost;
         this.serverPort = serverPort;
         this.publicBaseUrl = publicBaseUrl;
         this.admissionLabel = admissionLabel;
         this.mergeQueueCheckName = mergeQueueCheckName;
+        this.specReadyCheckName = specReadyCheckName;
     }
     async reportEviction(entry, incident) {
         const title = formatTitle(incident);
@@ -70,6 +75,52 @@ export class GitHubCheckRunReporter {
             "--remove-label", this.admissionLabel,
         ], { timeoutMs: 15_000, githubRepoFullName: this.repoFullName }).catch(() => { });
     }
+    // Plan §5.2: a "spec is ready" event on the PR head — not a verdict.
+    // Conclusion is `neutral` so branch-protection rules treat it as a
+    // signal rather than a gate. Best-effort: failures are logged in the
+    // exec layer and not propagated.
+    async reportSpecReady(entry, specBranch, specSha) {
+        const targetUrl = `https://github.com/${this.repoFullName}/commit/${specSha}`;
+        const summary = [
+            `Spec branch \`${specBranch}\` is at \`${specSha.slice(0, 12)}\`.`,
+            ``,
+            `This is the integration tree the lander will run CI on. Reviewers`,
+            `subscribed to integration_tree mode use this commit as the head`,
+            `they review.`,
+        ].join("\n");
+        const body = JSON.stringify({
+            name: this.specReadyCheckName,
+            head_sha: entry.headSha,
+            status: "completed",
+            conclusion: "neutral",
+            details_url: targetUrl,
+            output: {
+                title: `Spec ready (${specBranch})`,
+                summary,
+                text: JSON.stringify({ specBranch, specSha, prNumber: entry.prNumber, queueEntryId: entry.id }),
+            },
+        });
+        const tmpPath = join(tmpdir(), `steward-specready-${randomUUID()}.json`);
+        try {
+            writeFileSync(tmpPath, body);
+            await exec("gh", [
+                "api",
+                `repos/${this.repoFullName}/check-runs`,
+                "--method", "POST",
+                "--input", tmpPath,
+            ], { timeoutMs: 30_000, githubRepoFullName: this.repoFullName });
+        }
+        catch {
+            // Best-effort — review-quill can also fall back to polling the
+            // spec branch directly if it never sees this check_run.
+        }
+        finally {
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch { }
+        }
+    }
 }
 function buildIncidentProjection(incident, detailsUrl) {
     return {

package/dist/interfaces.d.ts

@@ -64,4 +64,13 @@ export interface GitHubPRApi {
  */
 export interface EvictionReporter {
     reportEviction(entry: QueueEntry, incident: IncidentRecord): Promise<void>;
+    /**
+     * Plan §5.2: emit a "spec ready" check_run on the PR's head SHA when
+     * a fresh spec branch has been pushed. Lets review-quill (and other
+     * consumers) subscribe to integration-tree availability via the
+     * GitHub bus instead of polling. Optional — implementations that
+     * cannot or should not write this check (sim, in-memory, dry-run)
+     * may omit or no-op.
+     */
+    reportSpecReady?(entry: QueueEntry, specBranch: string, specSha: string): Promise<void>;
 }

package/dist/reconciler-prepare.js

@@ -161,6 +161,13 @@ export async function prepareEntry(ctx, entry, isHead, prevEntry) {
     const specSha = result.sha ?? entry.headSha;
     emit(ctx, entry, "spec_build_succeeded", { specBranch: specName, ...(prevEntry ? { dependsOn: prevEntry.id } : {}) });
     await ctx.git.push(specName, true);
+    // Plan §5.2: emit `merge-steward/spec-ready` on the PR head so
+    // review-quill (and any other consumer) can react to spec
+    // availability via the GitHub bus instead of polling. Best-effort —
+    // failures are caught inside the reporter; CI still triggers.
+    if (ctx.eviction.reportSpecReady) {
+        await ctx.eviction.reportSpecReady(entry, specName, specSha).catch(() => undefined);
+    }
     const runId = await ctx.ci.triggerRun(specName, specSha);
     emit(ctx, entry, "ci_triggered", { ciRunId: runId, specBranch: specName });
     ctx.store.transition(entry.id, "validating", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merge-steward",
-  "version": "0.22.5",
+  "version": "0.24.0",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {