Implementation Plan: Auto-Merge Direct Merge Fallback (Issue #401)

[Trecek]

Summary

When auto_merge == "true" and queue_available == "false", the pipeline previously dropped
the PR unmerged by routing the route_queue_mode default case to release_issue_success.
This is incorrect — GitHub's gh pr merge --squash --auto works without a merge queue by
merging directly once required checks pass. The fix adds a direct_merge step chain as
the default route, mirroring the queue path's structure (enable → poll → conflict-fix →
re-push → re-enable). The same change is applied in three recipes: implementation.yaml,
remediation.yaml, and implementation-groups.yaml.

Requirements

ROUTE — Recipe Routing Updates

• REQ-ROUTE-001: When auto_merge is "true" and queue_available is "false", both implementation.yaml and remediation.yaml must route to a direct-merge step instead of skipping to cleanup/release.
• REQ-ROUTE-002: The direct-merge step must invoke gh pr merge --squash --auto to enable GitHub-native auto-merge regardless of merge queue presence.
• REQ-ROUTE-003: The direct-merge path must poll PR state for merged completion rather than calling wait_for_merge_queue.

FAIL — Failure Handling

• REQ-FAIL-001: The direct-merge path must handle merge failures (e.g., conflicts from concurrent merges) with a resolve-and-retry pattern analogous to the queue ejection path.
• REQ-FAIL-002: If the direct merge fails due to a non-conflict error, the recipe must route to the same cleanup/release path used by the queue timeout case.

DESC — Ingredient Description

• REQ-DESC-001: The auto_merge ingredient description in both implementation.yaml and remediation.yaml must be updated to reflect that it controls automatic merging after checks pass, not specifically merge queue enrollment.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 45, 'rankSpacing': 55, 'curve': 'basis'}}}%%
flowchart TB
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;

    START([CI checks pass])

    subgraph Detection ["Queue Detection"]
        CMQ["check_merge_queue<br/>━━━━━━━━━━<br/>GraphQL: mergeQueue id?<br/>captures queue_available"]
        RQM{"● route_queue_mode<br/>━━━━━━━━━━<br/>auto_merge? queue?"}
    end

    subgraph QueuePath ["Queue Path"]
        EAM["enable_auto_merge<br/>━━━━━━━━━━<br/>gh pr merge --squash --auto<br/>→ enroll in queue"]
        WFQ["wait_for_queue<br/>━━━━━━━━━━<br/>wait_for_merge_queue<br/>900 s timeout"]
        REENROLL["reenroll_stalled_pr<br/>━━━━━━━━━━<br/>toggle_auto_merge"]
        QEF["queue_ejected_fix<br/>━━━━━━━━━━<br/>resolve-merge-conflicts"]
        RPQF["re_push_queue_fix<br/>━━━━━━━━━━<br/>push_to_remote"]
        RMQ["reenter_merge_queue<br/>━━━━━━━━━━<br/>gh pr merge --squash --auto"]
    end

    subgraph DirectPath ["★ Direct Merge Path (new)"]
        DM["★ direct_merge<br/>━━━━━━━━━━<br/>gh pr merge --squash --auto<br/>direct (no queue)"]
        WFDM["★ wait_for_direct_merge<br/>━━━━━━━━━━<br/>poll gh pr view<br/>10 s × 90 = 15 min"]
        DMCF["★ direct_merge_conflict_fix<br/>━━━━━━━━━━<br/>resolve-merge-conflicts"]
        RPDF["★ re_push_direct_fix<br/>━━━━━━━━━━<br/>push_to_remote"]
        RDM["★ redirect_merge<br/>━━━━━━━━━━<br/>gh pr merge --squash --auto<br/>re-enable after fix"]
    end

    SUCCESS["release_issue_success<br/>━━━━━━━━━━<br/>label: staged"]
    TIMEOUT["release_issue_timeout<br/>━━━━━━━━━━<br/>no staged label"]
    FAILURE["release_issue_failure<br/>━━━━━━━━━━<br/>→ cleanup_failure"]
    CONFIRM["confirm_cleanup<br/>━━━━━━━━━━<br/>delete clone? yes/no"]
    DONE([done])

    START --> CMQ
    CMQ --> RQM
    RQM -->|"auto_merge != 'true'"| CONFIRM
    RQM -->|"queue_available == true"| EAM
    RQM -->|"● default (was release_issue_success)"| DM

    EAM --> WFQ
    EAM -->|"on_failure"| CONFIRM
    WFQ -->|"merged"| SUCCESS
    WFQ -->|"ejected"| QEF
    WFQ -->|"stalled"| REENROLL
    WFQ -->|"timeout"| TIMEOUT
    REENROLL --> WFQ
    QEF -->|"resolved"| RPQF
    QEF -->|"escalation_required"| FAILURE
    RPQF --> RMQ
    RMQ --> WFQ

    DM --> WFDM
    DM -->|"on_failure"| CONFIRM
    WFDM -->|"merged"| SUCCESS
    WFDM -->|"closed"| DMCF
    WFDM -->|"timeout"| TIMEOUT
    DMCF -->|"resolved"| RPDF
    DMCF -->|"escalation_required"| FAILURE
    RPDF --> RDM
    RDM --> WFDM

    SUCCESS --> CONFIRM
    TIMEOUT --> CONFIRM
    CONFIRM -->|"yes"| DONE
    CONFIRM -->|"no"| DONE

    class START,DONE terminal;
    class CMQ phase;
    class RQM stateNode;
    class EAM,WFQ,REENROLL,QEF,RPQF,RMQ handler;
    class DM,WFDM,DMCF,RPDF,RDM newComponent;
    class CONFIRM detector;
    class SUCCESS,TIMEOUT,FAILURE output;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Terminal	Pipeline start and end states
Purple	Phase	Queue detection and analysis nodes
Teal	State	● route_queue_mode — modified routing decision
Orange	Handler	Existing queue path steps
Green	New Component	★ New direct-merge path steps added by this PR
Dark Teal	Output	Terminal release / timeout / failure states
Red	Detector	confirm_cleanup gate

State Lifecycle Diagram

%%{init: {'flowchart': {'nodeSpacing': 48, 'rankSpacing': 56, 'curve': 'basis'}}}%%
flowchart TB
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    subgraph Inputs ["INIT_ONLY — Ingredient Fields (set at recipe start)"]
        direction LR
        OPR["inputs.open_pr<br/>━━━━━━━━━━<br/>default: true<br/>SKIP_GATE for all PR steps"]
        AM["● inputs.auto_merge<br/>━━━━━━━━━━<br/>default: true<br/>● desc: direct merge fallback"]
        BB["inputs.base_branch<br/>━━━━━━━━━━<br/>merge target"]
        IU["inputs.issue_url<br/>━━━━━━━━━━<br/>optional: release gate"]
    end

    subgraph Prerequisites ["SET_ONCE — Pipeline Context (captured before merge path)"]
        direction LR
        QA["context.queue_available<br/>━━━━━━━━━━<br/>SET: check_merge_queue<br/>READ: route_queue_mode"]
        PRN["context.pr_number<br/>━━━━━━━━━━<br/>SET: extract_pr_number<br/>READ: direct_merge, wait_for_direct_merge"]
        WD["context.work_dir<br/>━━━━━━━━━━<br/>SET: clone<br/>READ: all direct-merge steps"]
        MT["context.merge_target<br/>━━━━━━━━━━<br/>SET: create_branch<br/>READ: re_push_direct_fix"]
    end

    subgraph Gate ["VALIDATION GATE — skip_when_false"]
        GATE["inputs.open_pr == true<br/>━━━━━━━━━━<br/>Guards all 5 new steps:<br/>direct_merge, wait_for_direct_merge,<br/>direct_merge_conflict_fix,<br/>re_push_direct_fix, redirect_merge"]
    end

    subgraph RoutingDecision ["● route_queue_mode — State-Based Router"]
        RQM["● route_queue_mode<br/>━━━━━━━━━━<br/>reads: inputs.auto_merge<br/>reads: context.queue_available<br/>● default → direct_merge (was: release_issue_success)"]
    end

    subgraph NewCaptures ["★ CAPTURE_RESULT — New Context Fields (direct merge path)"]
        direction TB
        DMS["★ direct_merge_state<br/>━━━━━━━━━━<br/>SET: wait_for_direct_merge<br/>values: merged | closed | timeout<br/>READ: on_result conditions"]
        CER["conflict_escalation_required<br/>━━━━━━━━━━<br/>SET: direct_merge_conflict_fix<br/>values: true | false<br/>READ: on_result conditions"]
    end

    subgraph RouteContracts ["ON_RESULT CONTRACTS — Typed routing guards"]
        direction TB
        WFDMc["wait_for_direct_merge<br/>━━━━━━━━━━<br/>merged → release_issue_success<br/>closed → direct_merge_conflict_fix<br/>default → release_issue_timeout"]
        DMCFc["direct_merge_conflict_fix<br/>━━━━━━━━━━<br/>escalation_required == true → release_issue_failure<br/>default → re_push_direct_fix"]
    end

    OPR -->|"evaluated each step"| GATE
    AM -->|"read by"| RQM
    QA -->|"read by"| RQM
    BB -->|"passed to"| DMCFc
    IU -->|"gates"| RouteContracts

    PRN -->|"passed to"| Gate
    WD -->|"passed to"| Gate
    MT -->|"passed to"| Gate

    GATE -->|"pass → execute"| RQM
    RQM -->|"default route changed"| NewCaptures

    DMS -->|"consumed by"| WFDMc
    CER -->|"consumed by"| DMCFc

    class OPR,AM,BB,IU detector;
    class QA,PRN,WD,MT stateNode;
    class GATE gap;
    class RQM phase;
    class DMS newComponent;
    class CER handler;
    class WFDMc,DMCFc output;

Loading

Color Legend:

Color	Category	Description
Red	INIT_ONLY	Ingredient fields — set once at recipe start, never mutated
Teal	SET_ONCE	Pipeline context fields — captured before merge path, read by new steps
Yellow/Orange	SKIP_GATE	inputs.open_pr validation gate protecting all new steps
Purple	Modified Router	● route_queue_mode — routing logic changed by this PR
Green	New Capture	★ direct_merge_state — new field introduced by this PR
Orange	Existing Capture	conflict_escalation_required — existing field, also written by new step
Dark Teal	Route Contracts	on_result typed routing guards (consume captured fields)

Closes #401

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/impl-20260320-165150-373150/temp/make-plan/direct_merge_fallback_plan_2026-03-20_000001.md

Token Usage Summary

Token Summary\n\n(Token data accumulated server-side)

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested (22 findings: 4 critical, 17 warning)

[Trecek]

[warning] defense: direct_merge step has no retries; a transient network error on 'gh pr merge' immediately routes to confirm_cleanup with no retry attempt. Add retries: 1 with on_exhausted: confirm_cleanup.

[Trecek]

Investigated — this is intentional. The direct_merge step intentionally has no retries to prevent double-merge (gh pr merge --squash --auto on an already-merging PR). Transient failure degrades gracefully to confirm_cleanup per design. See step note: 'On failure (PR already merged, not mergeable), degrades gracefully to confirm_cleanup.'

[Trecek]

[warning] arch: re_push_direct_fix (push_to_remote) is missing an on_exhausted handler; retry exhaustion has no defined route, leaving the pipeline in an undefined state.

[Trecek]

Investigated — this is intentional. on_exhausted is only applicable when retries: is defined. re_push_direct_fix has no retries: field, so on_exhausted would be semantically undefined. Single-attempt push failure is handled by on_failure: release_issue_failure. Adding on_exhausted without retries would be schema-invalid.

[Trecek]

[warning] arch: re_push_direct_fix (push_to_remote) is missing an on_exhausted handler; retry exhaustion has no defined route.

[Trecek]

Investigated — this is intentional. re_push_direct_fix in remediation.yaml has no retries: field. on_exhausted is only applicable with a retry count defined. on_failure: release_issue_failure handles single-attempt failure.

[Trecek]

AutoSkillit review found 22 blocking issues. See inline comments. (Note: REQUEST_CHANGES submitted as COMMENT because reviewer is the PR author — verdict is still changes_requested.)