merge-steward 0.25.0 → 0.26.0

package/dist/db/schema.js

@@ -76,6 +76,8 @@ export function ensureSchema(connection) {
     ensureColumn(connection, "queue_entries", "post_merge_checked_at", "TEXT");
     ensureColumn(connection, "queue_entries", "wait_detail", "TEXT");
     ensureColumn(connection, "queue_entries", "pr_title", "TEXT");
+    // Plan §8.4: stack-aware admission ordering needs the PR's base ref.
+    ensureColumn(connection, "queue_entries", "base_ref_name", "TEXT");
     // Plan §5.3: cached identity for patch-id-aware updateHead.
     ensureColumn(connection, "queue_entries", "head_patch_id", "TEXT");
     ensureColumn(connection, "queue_entries", "spec_tree_id", "TEXT");

package/dist/db/sqlite-store.js

@@ -30,6 +30,7 @@ function mapEntry(row) {
         postMergeSummary: row.post_merge_summary === null || row.post_merge_summary === undefined ? null : String(row.post_merge_summary),
         postMergeCheckedAt: row.post_merge_checked_at === null || row.post_merge_checked_at === undefined ? null : String(row.post_merge_checked_at),
         prTitle: row.pr_title === null || row.pr_title === undefined ? null : String(row.pr_title),
+        baseRefName: row.base_ref_name === null || row.base_ref_name === undefined ? null : String(row.base_ref_name),
         headPatchId: row.head_patch_id === null || row.head_patch_id === undefined ? null : String(row.head_patch_id),
         specTreeId: row.spec_tree_id === null || row.spec_tree_id === undefined ? null : String(row.spec_tree_id),
         enqueuedAt: String(row.enqueued_at),
@@ -128,9 +129,9 @@ export class SqliteStore {
           priority, generation, ci_run_id, ci_retries, retry_attempts,
           max_retries, last_failed_base_sha, issue_key, wait_detail,
           post_merge_status, post_merge_sha, post_merge_summary, post_merge_checked_at,
-          pr_title,
+          pr_title, base_ref_name,
           enqueued_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.prTitle ?? null, entry.enqueuedAt, entry.updatedAt);
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(entry.id, entry.repoId, entry.prNumber, entry.branch, entry.headSha, entry.baseSha, entry.status, entry.position, entry.priority, entry.generation, entry.ciRunId, entry.ciRetries, entry.retryAttempts, entry.maxRetries, entry.lastFailedBaseSha, entry.issueKey ?? null, entry.waitDetail ?? null, entry.postMergeStatus ?? null, entry.postMergeSha ?? null, entry.postMergeSummary ?? null, entry.postMergeCheckedAt ?? null, entry.prTitle ?? null, entry.baseRefName ?? null, entry.enqueuedAt, entry.updatedAt);
             this.writeEvent(entry.id, null, entry.status);
         })();
     }

package/dist/github/pr-client.js

@@ -24,7 +24,9 @@ export class GitHubPRClient {
         const result = await exec("gh", [
             "pr", "view", String(prNumber),
             "--repo", this.repoFullName,
-            "--json", "number,title,headRefName,headRefOid,reviewDecision,state,mergeStateStatus",
+            // Plan §8.4 change 3a: include baseRefName so the queue can
+            // detect stacked PRs at admission time.
+            "--json", "number,title,headRefName,headRefOid,baseRefName,reviewDecision,state,mergeStateStatus",
         ], { githubRepoFullName: this.repoFullName });
         const data = JSON.parse(result.stdout);
         return {
@@ -32,6 +34,7 @@ export class GitHubPRClient {
             branch: data.headRefName,
             headSha: data.headRefOid,
             ...(data.title ? { title: data.title } : {}),
+            ...(data.baseRefName ? { baseRefName: data.baseRefName } : {}),
             mergeable: data.state === "OPEN",
             mergeStateStatus: data.mergeStateStatus,
             reviewDecision: data.reviewDecision,

package/dist/service-queue.d.ts

@@ -19,6 +19,12 @@ export declare class MergeStewardQueueCommands {
         issueKey?: string;
         priority?: number;
         prTitle?: string;
+        /**
+         * Plan §8.4: PR's base ref. When this matches another open PR's
+         * `branch` (head ref), the entry is stacked and admission orders
+         * it immediately behind the parent.
+         */
+        baseRefName?: string;
     }): QueueEntry | undefined;
     scanStartupAdmissions(): Promise<void>;
     scanEligibleOpenPrs(): Promise<{
@@ -34,4 +40,5 @@ export declare class MergeStewardQueueCommands {
     private findAffectedEntriesAfterPriorityChange;
     private requeueAffectedEntries;
     private nextPosition;
+    private findActiveEntryByBranch;
 }

package/dist/service-queue.js

@@ -66,6 +66,7 @@ export class MergeStewardQueueCommands {
             headPatchId: null,
             specTreeId: null,
             prTitle: params.prTitle ?? null,
+            baseRefName: params.baseRefName ?? null,
             enqueuedAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
         };
@@ -185,12 +186,36 @@ export class MergeStewardQueueCommands {
                     return false;
                 }
             }
+            // Plan §8.4: stack-aware admission. When the PR's base ref
+            // names another open PR's branch (head ref), the entry is
+            // stacked. Enqueue it only when the parent is already in the
+            // queue — otherwise the child's spec would build against the
+            // unmerged parent's pre-spec content. Positions are monotonic
+            // (`nextPosition`), so the child's position is always greater
+            // than the parent's; sibling PRs admitted between the parent's
+            // enqueue and the child's tryAdmit can sit between them. That's
+            // fine: queue head selection orders by (priority, position), so
+            // the parent is still processed before the child. The functional
+            // guarantee is "parent before child", not strict adjacency.
+            const baseRefName = status.baseRefName ?? null;
+            if (baseRefName && baseRefName !== this.config.baseBranch) {
+                const parentEntry = this.findActiveEntryByBranch(baseRefName);
+                if (!parentEntry) {
+                    this.logger.debug({
+                        prNumber,
+                        baseRefName,
+                        repoBaseBranch: this.config.baseBranch,
+                    }, "Deferring admission for stacked PR — parent branch is not in the queue yet");
+                    return false;
+                }
+            }
             this.enqueue({
                 prNumber,
                 branch,
                 headSha,
                 priority,
                 ...(status.title ? { prTitle: status.title } : {}),
+                ...(baseRefName ? { baseRefName } : {}),
             });
             return true;
         }
@@ -279,4 +304,10 @@ export class MergeStewardQueueCommands {
         }
         return next;
     }
+    // Plan §8.4: lookup helper used by stack-aware admission. Returns
+    // the active queue entry whose `branch` (head ref) matches `name`,
+    // or undefined when no such entry is in the queue.
+    findActiveEntryByBranch(name) {
+        return this.store.listActive(this.config.repoId).find((entry) => entry.branch === name);
+    }
 }

package/dist/types.d.ts

@@ -50,6 +50,13 @@ export interface QueueEntry {
     postMergeSummary: string | null;
     /** Timestamp of the most recent post-merge verification attempt. */
     postMergeCheckedAt: string | null;
+    /**
+     * Plan §8.4: PR's base ref captured at admission. When this names
+     * another open PR's `branch` (head ref), the entry is stacked and
+     * the queue holds it behind the parent until the parent is itself
+     * admitted. `null` when the PR was opened against the repo default.
+     */
+    baseRefName: string | null;
     /**
      * Plan §5.3: stable patch-id (`git patch-id --stable`) of the
      * current `headSha` against the entry's `baseSha`. Cached at spec
@@ -198,6 +205,12 @@ export interface PRStatus {
     branch: string;
     headSha: string;
     title?: string | undefined;
+    /**
+     * Plan §8.4: PR's base ref. When this names another open PR's
+     * `branch` (head ref), the PR is stacked and admission must defer
+     * until the parent is in the queue.
+     */
+    baseRefName?: string | undefined;
     mergeable: boolean;
     mergeStateStatus?: string | undefined;
     reviewDecision?: string | undefined;

package/package.json

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