Implementation Plan: Staged Issue Lifecycle for Non-Default Branch PRs

[Trecek]

Summary

The implementation pipeline fails to manage GitHub issue state correctly when PRs target
non-default branches (e.g., integration). Two bugs exist:

1. implementation.yaml has no release_issue_success step — the in-progress label is
   never removed on the success path, leaving issues permanently marked "in-progress" after
   merge into integration.
2. GitHub only auto-closes issues via "Closes #N" when PRs merge into the default branch
   (main). PRs targeting integration merge successfully but leave linked issues open with
   no indication of their actual status.

The fix introduces a three-point staged lifecycle:

• Success into non-default branch → remove in-progress, apply staged (work is done, waiting for promotion to main)
• Failure at any stage → remove in-progress only (leave open for retry)
• Integration PR to main → carry forward "Closes #N" so issues auto-close (already handled by open-integration-pr)

Additionally, the open-pr skill now blocks PRs that target stable from any branch other than main.

Requirements

STAGE — Staged Label Lifecycle

• REQ-STAGE-001: When a PR merges into integration, the pipeline must remove the in-progress label and apply a staged label to the linked issue.
• REQ-STAGE-002: The staged label must be created automatically (via gh label create --force) if it does not already exist.
• REQ-STAGE-003: The issue must remain open while the staged label is applied — it is only closed when the code reaches main.

CLOSE — Issue Close Behavior

• REQ-CLOSE-001: Issues must only be closed when the associated code merges into main (the default branch).
• REQ-CLOSE-002: The integration PR (merging integration → main) must carry forward all Closes #N references from the constituent PRs so GitHub auto-closes the issues.
• REQ-CLOSE-003: If Closes #N auto-close does not trigger (e.g. due to reference format), the pipeline must explicitly close the issue via gh issue close after confirming the merge to main.

RELEASE — Claim Release

• REQ-RELEASE-001: On the success path, release_issue must transition the issue from in-progress to staged when the target branch is not main.
• REQ-RELEASE-002: On the success path targeting main, release_issue must remove in-progress and allow the issue to close normally.
• REQ-RELEASE-003: On the failure path, release_issue must remove the in-progress label but must not apply staged, leaving the issue open for retry.

GUARD — Branch Enforcement

• REQ-GUARD-001: PRs targeting stable must be blocked unless the source branch is main.
• REQ-GUARD-002: The enforcement must be implemented via GitHub branch protection rules if possible, or via a PreToolUse hook or recipe-level guard as a fallback.
• REQ-GUARD-003: The open-pr skill or merge_worktree tool must reject attempts to target stable from any branch other than main with a clear error message.

Architecture Impact

State Lifecycle Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 70, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    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;

    %% TERMINAL %%
    IssueOpen(["Issue: Open<br/>━━━━━━━━━━<br/>No pipeline labels"])

    subgraph InitOnly ["INIT_ONLY FIELDS (set once)"]
        direction LR
        InputURL["inputs.issue_url<br/>━━━━━━━━━━<br/>INIT_ONLY<br/>Never modified"]
        InputBranch["inputs.base_branch<br/>━━━━━━━━━━<br/>INIT_ONLY<br/>Never modified"]
    end

    subgraph ClaimGate ["VALIDATION GATE: claim_issue"]
        direction TB
        IdempotencyCheck{"Label already<br/>in-progress?<br/>━━━━━━━━━━<br/>Idempotency Guard"}
        ClaimTool["● claim_issue MCP tool<br/>━━━━━━━━━━<br/>ensure_label: in-progress<br/>add_labels: in-progress"]
        EscalateStop["escalate_stop<br/>━━━━━━━━━━<br/>Another session owns it<br/>→ abort pipeline"]
    end

    subgraph InProgressState ["MUTABLE STATE: In-Progress"]
        InProgressLabel["Issue Label: in-progress<br/>━━━━━━━━━━<br/>MUTABLE<br/>Added by claim_issue"]
    end

    subgraph BranchGate ["★ VALIDATION GATE: Branch Check (NEW)"]
        direction TB
        BranchDerived{"target_branch<br/>━━━━━━━━━━<br/>DERIVED<br/>== default_base_branch?"}
    end

    subgraph ReleaseGate ["★ VALIDATION GATE: release_issue (EXTENDED)"]
        direction TB
        SkipCheck{"skip_when_false:<br/>inputs.issue_url<br/>━━━━━━━━━━<br/>Guard: no URL → skip"}
        ReleaseSuccess["★ release_issue_success step<br/>━━━━━━━━━━<br/>tool: release_issue<br/>with: target_branch=inputs.base_branch"]
        ReleaseFailure["release_issue_failure step<br/>━━━━━━━━━━<br/>tool: release_issue<br/>no target_branch → failure path"]
    end

    subgraph StagedConfig ["APPEND_ONLY CONFIG"]
        direction TB
        StagedLabelCfg["★ github.staged_label<br/>━━━━━━━━━━<br/>APPEND_ONLY config<br/>Default: 'staged'<br/>Color: #0075ca"]
        EnsureLabel["● release_issue MCP tool<br/>━━━━━━━━━━<br/>ensure_label (422-safe)<br/>add_labels: staged<br/>remove_label: in-progress"]
    end

    subgraph IssueStates ["FINAL ISSUE STATES"]
        direction LR
        StateStagedNew["★ Issue: open + staged<br/>━━━━━━━━━━<br/>Merged to integration<br/>Awaiting promotion to main"]
        StateOpenRetry["Issue: open<br/>━━━━━━━━━━<br/>Failure path: no staged<br/>Available for retry"]
        StateClosed["Issue: closed<br/>━━━━━━━━━━<br/>Merged to main<br/>Closes #N triggered"]
    end

    subgraph StableGuard ["★ STABLE BRANCH GUARD (NEW)"]
        StableCheck{"base_branch == stable<br/>AND feature != main?<br/>━━━━━━━━━━<br/>open-pr pre-flight"}
        GuardExit["Exit code 1<br/>━━━━━━━━━━<br/>Block PR to stable<br/>from non-main source"]
    end

    %% FLOW %%
    IssueOpen --> InitOnly
    InputURL --> IdempotencyCheck
    InputBranch --> BranchDerived

    IdempotencyCheck -->|"not claimed"| ClaimTool
    IdempotencyCheck -->|"already claimed"| EscalateStop
    ClaimTool --> InProgressLabel

    InProgressLabel --> SkipCheck
    SkipCheck -->|"issue_url present"| ReleaseSuccess
    SkipCheck -->|"no issue_url"| StateClosed

    ReleaseSuccess --> BranchDerived
    BranchDerived -->|"target == main (default)"| StateOpenRetry
    BranchDerived -->|"target != main (staging)"| StagedLabelCfg

    StagedLabelCfg --> EnsureLabel
    EnsureLabel --> StateStagedNew

    StateOpenRetry -->|"Closes #N on main merge"| StateClosed

    InProgressLabel -->|"any failure path"| ReleaseFailure
    ReleaseFailure --> StateOpenRetry

    StateStagedNew -->|"Integration PR → main"| StateClosed

    %% STABLE GUARD %%
    InputBranch --> StableCheck
    StableCheck -->|"stable + non-main source"| GuardExit
    StableCheck -->|"allowed"| ClaimTool

    %% CLASS ASSIGNMENTS %%
    class IssueOpen terminal;
    class InputURL,InputBranch detector;
    class IdempotencyCheck,SkipCheck,BranchDerived,StableCheck detector;
    class ClaimTool,ReleaseFailure phase;
    class InProgressLabel stateNode;
    class ReleaseSuccess,StagedLabelCfg,EnsureLabel,StableGuard,BranchGate,ReleaseGate newComponent;
    class StateStagedNew newComponent;
    class StateOpenRetry stateNode;
    class StateClosed output;
    class EscalateStop,GuardExit gap;

Loading

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 70, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    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;

    PipelineStart(["Pipeline Start<br/>━━━━━━━━━━<br/>inputs: issue_url, base_branch"])

    subgraph StableGuardPhase ["★ STABLE BRANCH GUARD (open-pr/SKILL.md)"]
        direction TB
        StableCheck{"● open-pr pre-flight<br/>━━━━━━━━━━<br/>base_branch == 'stable'<br/>AND feature != 'main'?"}
        BlockedExit["Exit code 1<br/>━━━━━━━━━━<br/>Error: stable-only from main<br/>No PR created"]
    end

    subgraph PipelineCore ["PIPELINE CORE (plan → implement → test → merge)"]
        direction TB
        PipelineSteps["plan / implement / test<br/>━━━━━━━━━━<br/>Worktree creation, implementation,<br/>test_check, merge_worktree, push_to_remote"]
        FailureAny["Any step on_failure<br/>━━━━━━━━━━<br/>Routes: release_issue_failure"]
    end

    subgraph MergeQueueRouting ["MERGE QUEUE ROUTING (● implementation.yaml)"]
        direction TB
        CheckMQ["check_merge_queue step<br/>━━━━━━━━━━<br/>gh api GraphQL<br/>captures: queue_available"]
        RouteMQ{"● route_queue_mode<br/>━━━━━━━━━━<br/>queue_available == true?"}
        EnableAutoMerge["enable_auto_merge step<br/>━━━━━━━━━━<br/>Sets up auto-merge on PR"]
        WaitForQueue["wait_for_queue step<br/>━━━━━━━━━━<br/>wait_for_merge_queue tool<br/>captures: pr_state"]
        QueueResult{"● wait_for_queue<br/>━━━━━━━━━━<br/>pr_state == ?"}
        QueueEjected["queue_ejected_fix<br/>━━━━━━━━━━<br/>Resolve ejection → retry"]
    end

    subgraph ReleaseRouting ["★ RELEASE ROUTING (NEW in implementation.yaml)"]
        direction TB
        ReleaseSuccess["★ release_issue_success step<br/>━━━━━━━━━━<br/>tool: release_issue<br/>with: target_branch=inputs.base_branch<br/>optional: true"]
        SkipGuard{"skip_when_false:<br/>━━━━━━━━━━<br/>inputs.issue_url present?"}
    end

    subgraph ReleaseTool ["★ release_issue MCP TOOL LOGIC (● tools_integrations.py)"]
        direction TB
        RemoveInProgress["remove_label: in-progress<br/>━━━━━━━━━━<br/>Always called on success path"]
        BranchDecision{"★ Branch Gate<br/>━━━━━━━━━━<br/>target_branch<br/>== default_base_branch?"}
        EnsureStaged["★ ensure_label: staged<br/>━━━━━━━━━━<br/>422-safe create<br/>Color: #0075ca"]
        AddStaged["★ add_labels: staged<br/>━━━━━━━━━━<br/>Apply staged label<br/>to issue"]
        ReturnStaged["return staged=True<br/>━━━━━━━━━━<br/>staged_label in response"]
        ReturnNoStaged["return staged=False<br/>━━━━━━━━━━<br/>No staging for main target"]
    end

    subgraph FailurePath ["FAILURE PATH (release_issue_failure)"]
        direction TB
        ReleaseFailureTool["release_issue_failure step<br/>━━━━━━━━━━<br/>tool: release_issue<br/>NO target_branch → no staging"]
        CleanupFailure["cleanup_failure<br/>━━━━━━━━━━<br/>Worktree teardown"]
    end

    subgraph SuccessPath ["SUCCESS TERMINAL"]
        direction TB
        ConfirmCleanup["confirm_cleanup<br/>━━━━━━━━━━<br/>Worktree teardown"]
        IssueStaged["Issue: staged<br/>━━━━━━━━━━<br/>★ staged label applied<br/>Awaiting promotion"]
        IssueDone["Issue: released<br/>━━━━━━━━━━<br/>in-progress removed<br/>Normal close flow"]
    end

    %% FLOW %%
    PipelineStart --> StableCheck
    StableCheck -->|"blocked"| BlockedExit
    StableCheck -->|"allowed"| PipelineSteps

    PipelineSteps --> CheckMQ
    PipelineSteps --> FailureAny
    FailureAny --> ReleaseFailureTool
    ReleaseFailureTool --> CleanupFailure

    CheckMQ --> RouteMQ
    CheckMQ -->|"on_failure"| ReleaseSuccess

    RouteMQ -->|"queue == true"| EnableAutoMerge
    RouteMQ -->|"queue == false (● was confirm_cleanup)"| ReleaseSuccess

    EnableAutoMerge --> WaitForQueue
    WaitForQueue --> QueueResult

    QueueResult -->|"merged (● was confirm_cleanup)"| ReleaseSuccess
    QueueResult -->|"ejected"| QueueEjected
    QueueResult -->|"timeout/other (● was confirm_cleanup)"| ReleaseSuccess
    QueueEjected -->|"retry"| WaitForQueue

    ReleaseSuccess --> SkipGuard
    SkipGuard -->|"no issue_url"| ConfirmCleanup
    SkipGuard -->|"issue_url present"| RemoveInProgress

    RemoveInProgress --> BranchDecision
    BranchDecision -->|"target != main"| EnsureStaged
    BranchDecision -->|"target == main"| ReturnNoStaged
    EnsureStaged --> AddStaged
    AddStaged --> ReturnStaged
    ReturnStaged --> IssueStaged
    ReturnNoStaged --> IssueDone
    IssueStaged --> ConfirmCleanup
    IssueDone --> ConfirmCleanup

    %% CLASS ASSIGNMENTS %%
    class PipelineStart terminal;
    class StableCheck,BranchDecision,QueueResult,SkipGuard,RouteMQ detector;
    class BlockedExit gap;
    class PipelineSteps,FailureAny,CheckMQ,EnableAutoMerge,WaitForQueue,QueueEjected handler;
    class ReleaseSuccess,RemoveInProgress,EnsureStaged,AddStaged,ReturnStaged,IssueStaged newComponent;
    class ReleaseFailureTool,CleanupFailure,ConfirmCleanup phase;
    class ReturnNoStaged,IssueDone stateNode;

Loading

Closes #382

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/impl-382-20260314-205351-453631/temp/make-plan/pipeline_staged_issue_lifecycle_plan_2026-03-14_210500.md

Token Usage Summary

No token data collected.

🤖 Generated with Claude Code via AutoSkillit

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested (8 actionable findings, 3 decision findings)

[Trecek]

[warning] cohesion: release_issue_success has optional:true but the visible sibling release_issue_failure does not appear to have optional:true. Symmetric counterparts should have matching optionality, or document the asymmetry.

[Trecek]

AutoSkillit review found 8 blocking issues. See inline comments.

Verdict: changes_requested

8 actionable findings (clear fixes), 3 decision findings (require human judgment).

Key issues:

• tools_integrations.py: Inconsistent error response schema — remove_label/staging failure paths omit fields present in success path
• tests/server/test_tools_integrations_release.py: Weak mock assertions (no arg verification on remove_label/ensure_label)
• implementation.yaml: Timeout path routes to release_issue_success identically to merge success — consider whether timed-out PRs should receive the staged label