sequant 2.2.0 → 2.4.0

package/dist/src/lib/workflow/phase-mapper.js

@@ -7,61 +7,69 @@
  *
  * @module phase-mapper
  */
+import { phaseRegistry } from "./phase-registry.js";
 /**
- * UI-related labels that trigger automatic test phase
- */
-export const UI_LABELS = ["ui", "frontend", "admin", "web", "browser"];
-/**
- * Bug-related labels that skip spec phase
+ * Bug-related labels (used by downstream metadata consumers).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. The registry-driven
+ * `detectPhasesFromLabels` below does not consult this list. It stays
+ * here because `batch-executor.ts` and other modules read it for
+ * `issueType` propagation and similar non-phase concerns.
  */
 export const BUG_LABELS = ["bug", "fix", "hotfix", "patch"];
 /**
- * Documentation labels that skip spec phase
+ * Documentation labels (used for issueType propagation and downstream metadata).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. See BUG_LABELS comment.
  */
 export const DOCS_LABELS = ["docs", "documentation", "readme"];
 /**
- * Complex labels that enable quality loop
+ * Complex labels that enable quality loop.
+ *
+ * Quality-loop trigger — NOT a phase-trigger rule (does not add the loop
+ * *phase*; only flips the `qualityLoop` flag on the run config). Kept
+ * out of the phase registry by design.
  */
 export const COMPLEX_LABELS = ["complex", "refactor", "breaking", "major"];
 /**
- * Security-related labels that trigger security-review phase
+ * Look up label-based detect rules from the registry, returning the set
+ * of phases whose `detect.labels` intersect the issue's labels. Comparison
+ * is case-insensitive (labels lowercased at the call site).
  */
-export const SECURITY_LABELS = [
-    "security",
-    "auth",
-    "authentication",
-    "permissions",
-    "admin",
-];
+function detectPhasesFromRegistry(lowerLabels) {
+    const matched = new Set();
+    for (const def of phaseRegistry.list()) {
+        const triggers = def.detect?.labels;
+        if (!triggers || triggers.length === 0)
+            continue;
+        const hit = triggers.some((t) => lowerLabels.includes(t.toLowerCase()));
+        if (hit)
+            matched.add(def.name);
+    }
+    return matched;
+}
 /**
- * Detect phases based on issue labels (like /assess logic)
+ * Detect phases based on issue labels (like /assess logic).
+ *
+ * Label → phase mapping now lives in `PhaseDefinition.detect.labels`. Only
+ * the *insertion position* of detected phases remains baked in here, because
+ * pipeline ordering depends on the phase's role (security-review goes after
+ * spec; test goes before qa).
  */
 export function detectPhasesFromLabels(labels) {
     const lowerLabels = labels.map((l) => l.toLowerCase());
-    // Check for bug/fix labels → exec → qa (skip spec)
-    const isBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label === bugLabel));
-    // Check for docs labels → exec → qa (skip spec)
-    const isDocs = lowerLabels.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
-    // Check for UI labels → add test phase
-    const isUI = lowerLabels.some((label) => UI_LABELS.some((uiLabel) => label === uiLabel));
-    // Check for complex labels → enable quality loop
+    // Quality loop is a registry-independent label trigger (see COMPLEX_LABELS).
     const isComplex = lowerLabels.some((label) => COMPLEX_LABELS.some((complexLabel) => label === complexLabel));
-    // Check for security labels → add security-review phase
-    const isSecurity = lowerLabels.some((label) => SECURITY_LABELS.some((secLabel) => label === secLabel));
-    // Build phase list
-    let phases;
-    if (isBugFix || isDocs) {
-        // Simple workflow: exec → qa
-        phases = ["exec", "qa"];
-    }
-    else if (isUI) {
-        // UI workflow: spec → exec → test → qa
-        phases = ["spec", "exec", "test", "qa"];
-    }
-    else {
-        // Standard workflow: spec → exec → qa
-        phases = ["spec", "exec", "qa"];
-    }
+    const matched = detectPhasesFromRegistry(lowerLabels);
+    const isUI = matched.has("test");
+    const isSecurity = matched.has("security-review");
+    // Build phase list — spec is always included by default (#533).
+    // Bug/docs labels no longer short-circuit spec; downstream consumers
+    // (e.g. `issueType: "docs"` propagation) still use DOCS_LABELS for
+    // metadata purposes, not for phase selection.
+    const phases = isUI
+        ? ["spec", "exec", "test", "qa"]
+        : ["spec", "exec", "qa"];
     // Add security-review phase after spec if security labels detected
     if (isSecurity && phases.includes("spec")) {
         const specIndex = phases.indexOf("spec");
@@ -89,18 +97,10 @@ export function parseRecommendedWorkflow(output) {
         .split(/\s*→\s*|\s*->\s*|\s*,\s*/)
         .map((p) => p.trim().toLowerCase())
         .filter((p) => p.length > 0);
-    // Validate and convert to Phase type
+    // Validate against the registry — accepts any registered phase.
     const validPhases = [];
     for (const name of phaseNames) {
-        if ([
-            "spec",
-            "security-review",
-            "testgen",
-            "exec",
-            "test",
-            "qa",
-            "loop",
-        ].includes(name)) {
+        if (phaseRegistry.has(name)) {
             validPhases.push(name);
         }
     }
@@ -115,10 +115,21 @@ export function parseRecommendedWorkflow(output) {
     return { phases: validPhases, qualityLoop };
 }
 /**
- * Check if an issue has UI-related labels
+ * Check if an issue has UI-related labels.
+ *
+ * Sources the label list from the `test` phase's `detect.labels` entry in
+ * the registry — same data as `detectPhasesFromLabels` consults, just
+ * exposed as a boolean for callers that only need the yes/no answer
+ * (e.g. test phase insertion in `determinePhasesForIssue`).
  */
 export function hasUILabels(labels) {
-    return labels.some((label) => UI_LABELS.some((uiLabel) => label.toLowerCase() === uiLabel));
+    const testTriggers = phaseRegistry.has("test")
+        ? (phaseRegistry.get("test").detect?.labels ?? [])
+        : [];
+    if (testTriggers.length === 0)
+        return false;
+    const lowered = new Set(testTriggers.map((t) => t.toLowerCase()));
+    return labels.some((label) => lowered.has(label.toLowerCase()));
 }
 /**
  * Determine phases to run based on options and issue labels
@@ -132,6 +143,14 @@ export function determinePhasesForIssue(basePhases, labels, options) {
             phases.splice(specIndex + 1, 0, "testgen");
         }
     }
+    // Add security-review phase after spec if requested.
+    // Idempotent vs label-based auto-detection in detectPhasesFromLabels.
+    if (options.securityReview && phases.includes("spec")) {
+        const specIndex = phases.indexOf("spec");
+        if (!phases.includes("security-review")) {
+            phases.splice(specIndex + 1, 0, "security-review");
+        }
+    }
     // Auto-detect UI issues and add test phase
     if (hasUILabels(labels) && !phases.includes("test")) {
         // Add test phase before qa if present, otherwise at the end

package/dist/src/lib/workflow/phase-registry.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Phase registry — single source of truth for workflow phase definitions.
+ *
+ * Replaces scattered constants (`PHASE_PROMPTS`, `AIDER_PHASE_PROMPTS`,
+ * `ISOLATED_PHASES`, `UI_LABELS`, `SECURITY_LABELS`) with a uniform record
+ * per phase. All 9 built-in phases register here at module load — no
+ * special-casing inside consumer code.
+ *
+ * Built-in registrations live at the bottom of this file rather than in a
+ * separate `built-in-phases.ts` module. The colocated layout follows the
+ * existing `drivers/index.ts` pattern and avoids the ESM-cycle pitfall of
+ * a separate bootstrap module that re-imports the registry singleton
+ * before the singleton is fully initialized.
+ *
+ * User-extensibility (filesystem discovery of `.sequant/phases/`) is
+ * deliberately deferred — see issue #505 descoping comment.
+ */
+/**
+ * Per-driver overrides for a phase. Today only `promptTemplate` is supported;
+ * extend the inner record when additional fields need per-driver values.
+ */
+export interface DriverOverride {
+    promptTemplate?: string;
+}
+/**
+ * Retry policy for a single phase. Phases without this field fall back to
+ * the global cold-start retry defaults in `phase-executor.ts`. The fields
+ * are deliberately optional — a phase only needs to specify what differs.
+ */
+export interface RetryStrategy {
+    /** Override the cold-start retry attempt count for this phase. */
+    maxRetries?: number;
+    /** Initial backoff in ms before the first retry. */
+    backoffMs?: number;
+    /** Override the cold-start threshold (seconds). */
+    coldStartThreshold?: number;
+    /** Extra retries beyond cold-start (e.g. for transient API errors). */
+    extraRetries?: number;
+}
+/**
+ * Auto-detection rules consumed by phase-mapper.ts.
+ * `labels` is an exact-match list (case-insensitive at the call site).
+ */
+export interface DetectRules {
+    labels?: string[];
+}
+/**
+ * Definition of a workflow phase. Registered at startup via
+ * `phaseRegistry.register(...)` and consumed by phase-executor, phase-mapper,
+ * and the CLI validator.
+ */
+export interface PhaseDefinition {
+    /** Phase name (matches the skill template directory + CLI `--phases` token). */
+    name: string;
+    /** Skill template directory under `templates/skills/<skill>/SKILL.md`. */
+    skill: string;
+    /**
+     * Natural-language prompt for the default (Claude Code) driver. The token
+     * `{issue}` is substituted with the GitHub issue number at execution time.
+     */
+    promptTemplate: string;
+    /**
+     * When true, phase-executor runs this phase inside the issue worktree.
+     * `spec`, `verify`, and `merger` run in the main repo (no worktree).
+     */
+    requiresWorktree: boolean;
+    /** Optional per-phase retry overrides. */
+    retryStrategy?: RetryStrategy;
+    /** Optional auto-detection rules. */
+    detect?: DetectRules;
+    /**
+     * Per-driver overrides. Keyed by agent name (e.g. `"aider"`). When the
+     * orchestrator runs a non-Claude driver, the corresponding override's
+     * `promptTemplate` (if present) replaces the default.
+     */
+    driverOverrides?: Record<string, DriverOverride>;
+    /**
+     * Insertion order hint. Used by phase-mapper to sort label-detected phases
+     * into a deterministic pipeline position. Defaults to 0.
+     */
+    order?: number;
+}
+/**
+ * In-memory registry of phase definitions. Single mutable instance lives
+ * in this module — see the exported `phaseRegistry` constant.
+ *
+ * The class is intentionally minimal (no lifecycle hooks, no async). All
+ * mutations happen synchronously at module load by the built-in registrations
+ * at the bottom of this file.
+ */
+export declare class PhaseRegistry {
+    private readonly definitions;
+    /**
+     * Register a phase definition. Throws on duplicate names so misconfigured
+     * bootstrap modules surface immediately instead of silently overwriting.
+     */
+    register(definition: PhaseDefinition): void;
+    /**
+     * Retrieve a phase by name. Throws with a "did you mean" list when the
+     * lookup fails — clearer than a downstream "undefined.promptTemplate".
+     */
+    get(name: string): PhaseDefinition;
+    /** True when a phase with this name is registered. */
+    has(name: string): boolean;
+    /**
+     * All registered phase definitions in insertion order. Insertion order
+     * is also the canonical pipeline order (see registrations below).
+     */
+    list(): PhaseDefinition[];
+    /**
+     * All registered phase names in insertion order. Replaces the
+     * `PhaseSchema.options` array literal exposed by the previous typed-enum
+     * `PhaseSchema`.
+     */
+    names(): string[];
+}
+/**
+ * Singleton registry instance. All consumer modules (phase-executor,
+ * phase-mapper, types.ts, CLI) read from this same instance — there is
+ * no second registry.
+ */
+export declare const phaseRegistry: PhaseRegistry;
+/**
+ * Convenience accessor for the registered phase names. Used by Zod refines,
+ * tests, and CLI validation in place of the removed `PhaseSchema.options`.
+ */
+export declare function getPhaseNames(): string[];

package/dist/src/lib/workflow/phase-registry.js

@@ -0,0 +1,233 @@
+/**
+ * Phase registry — single source of truth for workflow phase definitions.
+ *
+ * Replaces scattered constants (`PHASE_PROMPTS`, `AIDER_PHASE_PROMPTS`,
+ * `ISOLATED_PHASES`, `UI_LABELS`, `SECURITY_LABELS`) with a uniform record
+ * per phase. All 9 built-in phases register here at module load — no
+ * special-casing inside consumer code.
+ *
+ * Built-in registrations live at the bottom of this file rather than in a
+ * separate `built-in-phases.ts` module. The colocated layout follows the
+ * existing `drivers/index.ts` pattern and avoids the ESM-cycle pitfall of
+ * a separate bootstrap module that re-imports the registry singleton
+ * before the singleton is fully initialized.
+ *
+ * User-extensibility (filesystem discovery of `.sequant/phases/`) is
+ * deliberately deferred — see issue #505 descoping comment.
+ */
+/**
+ * In-memory registry of phase definitions. Single mutable instance lives
+ * in this module — see the exported `phaseRegistry` constant.
+ *
+ * The class is intentionally minimal (no lifecycle hooks, no async). All
+ * mutations happen synchronously at module load by the built-in registrations
+ * at the bottom of this file.
+ */
+export class PhaseRegistry {
+    definitions = new Map();
+    /**
+     * Register a phase definition. Throws on duplicate names so misconfigured
+     * bootstrap modules surface immediately instead of silently overwriting.
+     */
+    register(definition) {
+        if (this.definitions.has(definition.name)) {
+            throw new Error(`PhaseRegistry: phase "${definition.name}" is already registered`);
+        }
+        this.definitions.set(definition.name, definition);
+    }
+    /**
+     * Retrieve a phase by name. Throws with a "did you mean" list when the
+     * lookup fails — clearer than a downstream "undefined.promptTemplate".
+     */
+    get(name) {
+        const def = this.definitions.get(name);
+        if (!def) {
+            const available = this.names().join(", ");
+            throw new Error(`PhaseRegistry: unknown phase "${name}". Available: ${available}`);
+        }
+        return def;
+    }
+    /** True when a phase with this name is registered. */
+    has(name) {
+        return this.definitions.has(name);
+    }
+    /**
+     * All registered phase definitions in insertion order. Insertion order
+     * is also the canonical pipeline order (see registrations below).
+     */
+    list() {
+        return [...this.definitions.values()];
+    }
+    /**
+     * All registered phase names in insertion order. Replaces the
+     * `PhaseSchema.options` array literal exposed by the previous typed-enum
+     * `PhaseSchema`.
+     */
+    names() {
+        return [...this.definitions.keys()];
+    }
+}
+/**
+ * Singleton registry instance. All consumer modules (phase-executor,
+ * phase-mapper, types.ts, CLI) read from this same instance — there is
+ * no second registry.
+ */
+export const phaseRegistry = new PhaseRegistry();
+/**
+ * Convenience accessor for the registered phase names. Used by Zod refines,
+ * tests, and CLI validation in place of the removed `PhaseSchema.options`.
+ */
+export function getPhaseNames() {
+    return phaseRegistry.names();
+}
+// ─── Built-in phase registrations ────────────────────────────────────────
+//
+// Insertion order below IS the canonical pipeline order — preserved from the
+// pre-registry `PhaseSchema` literal (`spec, security-review, exec, testgen,
+// test, verify, qa, loop, merger`). Reordering these entries changes the
+// order returned by `phaseRegistry.list()` / `getPhaseNames()` and the
+// downstream `WORKFLOW_PHASES` constant in `state-schema.ts`.
+// Spec — runs in the main repo (planning only, no worktree mutation)
+phaseRegistry.register({
+    name: "spec",
+    skill: "spec",
+    promptTemplate: "Review GitHub issue #{issue} and create an implementation plan with verification criteria. Run the /spec {issue} workflow.",
+    requiresWorktree: false,
+    // Spec has a higher transient failure rate (~8.6%) than other phases due
+    // to GitHub API issues and rate limits. phase-executor.ts reads these
+    // values directly from the registry at module load (see
+    // SPEC_RETRY_BACKOFF_MS / SPEC_EXTRA_RETRIES).
+    retryStrategy: { extraRetries: 1, backoffMs: 5000 },
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Read GitHub issue #{issue} using 'gh issue view #{issue}'.
+Create a spec comment on the issue with:
+1. Implementation plan
+2. Acceptance criteria as a checklist
+3. Risk assessment
+Post the comment using 'gh issue comment #{issue} --body "<comment>"'.`,
+        },
+    },
+});
+// Security review — worktree-isolated, label-triggered
+phaseRegistry.register({
+    name: "security-review",
+    skill: "security-review",
+    promptTemplate: "Perform a deep security analysis for GitHub issue #{issue} focusing on auth, permissions, and sensitive operations. Run the /security-review {issue} workflow.",
+    requiresWorktree: true,
+    detect: {
+        labels: ["security", "auth", "authentication", "permissions", "admin"],
+    },
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Perform a security review for GitHub issue #{issue}.
+Read the issue with 'gh issue view #{issue}'.
+Check for auth, permissions, injection, and sensitive data issues.
+Post findings as a comment on the issue.`,
+        },
+    },
+});
+// Exec — worktree-isolated
+phaseRegistry.register({
+    name: "exec",
+    skill: "exec",
+    promptTemplate: "Implement the feature for GitHub issue #{issue} following the spec. Run the /exec {issue} workflow.",
+    requiresWorktree: true,
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Implement the feature described in GitHub issue #{issue}.
+Read the issue and any spec comments with 'gh issue view #{issue} --comments'.
+Follow the implementation plan from the spec.
+Write tests for new functionality.
+Ensure the build passes with 'npm test' and 'npm run build'.`,
+        },
+    },
+});
+// Testgen — worktree-isolated
+phaseRegistry.register({
+    name: "testgen",
+    skill: "testgen",
+    promptTemplate: "Generate test stubs for GitHub issue #{issue} based on the specification. Run the /testgen {issue} workflow.",
+    requiresWorktree: true,
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Generate test stubs for GitHub issue #{issue}.
+Read the spec comments on the issue with 'gh issue view #{issue} --comments'.
+Create test files with describe/it blocks covering the acceptance criteria.
+Use the project's existing test framework.`,
+        },
+    },
+});
+// Test — worktree-isolated, label-triggered (UI/frontend issues)
+phaseRegistry.register({
+    name: "test",
+    skill: "test",
+    promptTemplate: "Execute structured browser-based testing for GitHub issue #{issue}. Run the /test {issue} workflow.",
+    requiresWorktree: true,
+    detect: { labels: ["ui", "frontend", "admin", "web", "browser"] },
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Test the implementation for GitHub issue #{issue}.
+Run 'npm test' and verify all tests pass.
+Check for edge cases and error handling.`,
+        },
+    },
+});
+// Verify — runs in main repo (CLI-only feature verification)
+phaseRegistry.register({
+    name: "verify",
+    skill: "verify",
+    promptTemplate: "Verify the implementation for GitHub issue #{issue} by running commands and capturing output. Run the /verify {issue} workflow.",
+    requiresWorktree: false,
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Verify the implementation for GitHub issue #{issue}.
+Run relevant commands and capture their output for review.`,
+        },
+    },
+});
+// QA — worktree-isolated
+phaseRegistry.register({
+    name: "qa",
+    skill: "qa",
+    promptTemplate: "Review the implementation for GitHub issue #{issue} against acceptance criteria. Run the /qa {issue} workflow.",
+    requiresWorktree: true,
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Review the changes for GitHub issue #{issue}.
+Run 'npm test' and 'npm run build' to verify everything works.
+Check each acceptance criterion from the issue comments.
+Output a verdict: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, or AC_NOT_MET
+with format "### Verdict: <VERDICT>" followed by an explanation.`,
+        },
+    },
+});
+// Loop — worktree-isolated. `maxRetries: 0` encodes the
+// "skip cold-start retries" rule consumed by phase-executor.ts (#488).
+phaseRegistry.register({
+    name: "loop",
+    skill: "loop",
+    promptTemplate: "Parse test/QA findings for GitHub issue #{issue} and iterate until quality gates pass. Run the /loop {issue} workflow.",
+    requiresWorktree: true,
+    retryStrategy: { maxRetries: 0 },
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Review test and QA findings for GitHub issue #{issue}.
+Fix any issues identified in the QA feedback.
+Re-run 'npm test' and 'npm run build' until all quality gates pass.`,
+        },
+    },
+});
+// Merger — runs in main repo (multi-worktree integration)
+phaseRegistry.register({
+    name: "merger",
+    skill: "merger",
+    promptTemplate: "Integrate and merge completed worktrees for GitHub issue #{issue}. Run the /merger {issue} workflow.",
+    requiresWorktree: false,
+    driverOverrides: {
+        aider: {
+            promptTemplate: `Integrate and merge completed worktrees for GitHub issue #{issue}.
+Ensure all branches are up to date and merge cleanly.`,
+        },
+    },
+});

package/dist/src/lib/workflow/platforms/github.d.ts

@@ -94,7 +94,7 @@ export declare class GitHubProvider implements PlatformProvider {
      * Create a PR via `gh pr create` CLI, returning raw result.
      * Used by worktree-manager.ts which needs access to stdout for URL extraction.
      */
-    createPRCliSync(title: string, body: string, head: string, cwd?: string): CreatePRCliResult;
+    createPRCliSync(title: string, body: string, head: string, cwd?: string, base?: string): CreatePRCliResult;
     /**
      * Batch fetch issue and PR status in a single GraphQL call.
      * Returns a map keyed by issue/PR number.

package/dist/src/lib/workflow/platforms/github.js

@@ -137,8 +137,25 @@ export class GitHubProvider {
      * Create a PR via `gh pr create` CLI, returning raw result.
      * Used by worktree-manager.ts which needs access to stdout for URL extraction.
      */
-    createPRCliSync(title, body, head, cwd) {
-        const result = spawnSync("gh", ["pr", "create", "--title", title, "--body", body, "--head", head], { stdio: "pipe", cwd, timeout: 30000 });
+    createPRCliSync(title, body, head, cwd, base) {
+        const args = [
+            "pr",
+            "create",
+            "--title",
+            title,
+            "--body",
+            body,
+            "--head",
+            head,
+        ];
+        if (base) {
+            args.push("--base", base);
+        }
+        const result = spawnSync("gh", args, {
+            stdio: "pipe",
+            cwd,
+            timeout: 30000,
+        });
         return {
             stdout: result.stdout?.toString() ?? "",
             stderr: result.stderr?.toString() ?? "",
@@ -415,7 +432,7 @@ export class GitHubProvider {
         });
     }
     async createPR(opts) {
-        const result = this.createPRCliSync(opts.title, opts.body, opts.head);
+        const result = this.createPRCliSync(opts.title, opts.body, opts.head, undefined, opts.base);
         if (result.exitCode !== 0) {
             const error = result.stderr.trim() || "Unknown error";
             throw new Error(`gh pr create failed: ${error}`);

package/dist/src/lib/workflow/pr-status.d.ts

@@ -28,16 +28,32 @@ export declare function checkPRMergeStatus(prNumber: number): PRMergeStatus;
 /**
  * Check if a branch has been merged into a base branch using git
  *
+ * "Merged" here means the branch was the source of an actual merge commit on
+ * the base branch — i.e., the branch tip appears as a non-first parent of some
+ * merge commit reachable from baseBranch. This deliberately excludes the case
+ * where the branch tip is just an ancestor of baseBranch with no commits ever
+ * added (e.g., a worktree branch created from main that was abandoned before
+ * any commits were made). Those branches are reachable from main but were
+ * never merged in any meaningful sense; the older `git branch --merged` check
+ * misclassified them as merged and caused subsequent runs to skip the still-
+ * open issue.
+ *
+ * Squash-merged branches do not satisfy this check (their tip is not on main
+ * after squash) — callers that need to detect squash merges should rely on
+ * commit-message detection (see {@link isIssueMergedIntoMain}'s `--grep` path)
+ * or a PR API check.
+ *
  * @param branchName - The branch name to check (e.g., "feature/33-some-title")
  * @param baseBranch - The base branch to check against (default: "main")
- * @returns true if the branch is merged into the base branch, false otherwise
+ * @returns true if a merge commit on baseBranch records branchName's tip as a
+ *   non-first parent, false otherwise
  */
 export declare function isBranchMergedIntoMain(branchName: string, baseBranch?: string): boolean;
 /**
  * Check if a feature branch for an issue is merged into a base branch
  *
  * Tries multiple detection methods:
- * 1. Check if branch exists and is merged via `git branch --merged <baseBranch>`
+ * 1. Find `feature/<N>-*` branches with `git branch -a` and check via {@link isBranchMergedIntoMain}
  * 2. Check for merge commits mentioning the issue
  *
  * @param issueNumber - The issue number to check