| name | source-stabilization |
| description | Sub-orchestration for phase 1 of a release — getting the source branch green and landed on the release target. Sequences three steps (stabilize the source branch, open/refresh the source-to-target PR and wait for release-grade CI on the exact SHA, merge after green plus explicit approval), dispatching ci-gate-watch, ci-failure-triager, and merge-verifier, and routing on each outcome. Holds no gate definitions and no failure-classification criteria. Dispatched by release-orchestration. |
Source Stabilization — pipeline only
Phase 1 of a release. Its job is narrow: the source branch is green, and it has demonstrably landed on
the release target. Nothing about versions, changesets, or publishing belongs here.
This skill owns ordering and routing. Every constraint it invokes — which branches may open a PR against
which target, when a release-level merge is allowed, what a triage note must contain — is owned by the
rules below and is pointed at, not restated.
Rule Anchor
- publish.md — "Release State Machine" (this phase's per-step constraints),
"CI Failure Triage" (the triage-note contract), "Long-Running Gates", "Stop Conditions".
- git-branch.md — protected branches, allowed PR sources, release-level merge
approval, "Merge Landing Verification".
Steps and routing
1. Stabilize the source branch. Identify every CI blocker on the task branches feeding the source
branch, resolve them there, and merge them back into the source branch.
| Outcome | Route |
|---|
| No blockers remain | Advance to step 2. |
| A blocker exists | Dispatch ci-failure-triager on it before changing any code (the rule's ordering invariant). Then take the triage routing table below. |
| A blocker needs a decision only the user makes | Return HALT to the caller. |
2. Open or refresh the source-to-target PR, and wait for release-grade CI on the exact SHA. The SHA
matters: a check that passed on an earlier SHA has not verified this one.
| Outcome | Route |
|---|
| Checks not yet conclusive | Dispatch ci-gate-watch and route on its outcome. |
| All required checks green on the exact SHA | Advance to step 3. |
| A required check red | Dispatch ci-failure-triager; take the triage routing table below. |
| New commits landed on the source branch mid-wait | Return to step 2 against the new SHA — never carry an older SHA's green forward. |
3. Merge the source branch into the release target, then verify it landed. The merge requires the
explicit approval git-branch.md mandates; this pipeline never substitutes its
own judgement for it.
| Outcome | Route |
|---|
| Approval not given | Return HALT — the phase is complete only when the merge has landed. |
Merged → dispatch merge-verifier → MERGE VERIFIED: PASS | Return COMPLETE. |
merge-verifier reports MERGE VERIFIED: FAIL | Do not re-merge blindly. Take the verifier's finding: if the merge is absent on the target's remote head, return to step 3; if a claimed change is missing or unrelated drift landed, return HALT — a bad merge on a protected target is a user decision, not a retry. |
Triage routing (steps 1 and 2)
ci-failure-triager returns a class and a validation path; this pipeline routes on them and does not
re-judge. Track triage_attempts per distinct failure signature, cap 2.
| Class returned | Route |
|---|
product defect / CI harness infrastructure / dependency or lockfile sync | Apply the minimal fix on a task branch, run the triager's stated validation path, then return to step 1. |
test race or flake | Re-run the failing check once. Green → return to the step that dispatched the triage. Red again → treat as product defect. |
external environment or service | Re-run after the interval the triage note recommends, at most twice, then return HALT. Never patch code for an environment class. |
| The validation path does not pass after the fix | Re-triage with the new signature and increment triage_attempts. |
triage_attempts exceeds the cap for one signature | Return HALT — repeated failed validation means the classification is wrong, and looping cannot discover that. |
Outcome contract
Return exactly one to the caller, with the evidence behind it:
COMPLETE — the source branch is merged and independently verified as landed on the release target.RETRY — a transient condition cleared and the whole phase should re-run from step 1.HALT — a stop condition fired, approval is missing, or a cap was exceeded. Name which.
This phase never returns REGRESSED: it is the phase a regression returns to.
