@codyswann/lisa 4.28.0 → 4.28.2

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-github-build-intake/SKILL.md

@@ -56,6 +56,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
 3. If `done` is a **string** in config, use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 TARGET_ENV="${target_env:-}"
@@ -478,10 +497,10 @@ A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) ass
 If the lifecycle run returned Success:
 
 1. **Confirm the PR merged.** Read the live state of the issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before relabeling; a still-running deploy is treated like an open PR (leave in `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave in `$CLAIMED`), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it in `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or close anything.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the issue in `$CLAIMED`.
-2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `github.labels.build.done` is a string, that string is terminal.
    - If `github.labels.build.done` is an object, only the production/final environment value is terminal (default: `status:done`). Intermediate env values such as `status:on-dev` and `status:on-stg` are not terminal and must stay open.

package/plugins/lisa-agy/skills/lisa-jira-build-intake/SKILL.md

@@ -39,6 +39,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup: if base is `staging`, env is `staging`).
 3. If `done` in config is a **string** (not a map), use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 # Resolve env, then DONE.
@@ -334,10 +353,10 @@ A `done` env status (`On Dev`, `On Stg`, or the terminal value) asserts that the
 
 If the lifecycle run returned Success:
 1. **Confirm the PR merged.** Read the live state of the ticket's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before transitioning; a still-running deploy is treated like an open PR (leave in `$CLAIMED` for a later cycle), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave in `$CLAIMED` for a later cycle), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the ticket under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it in `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once it is merged, applies this same env transition. Do **not** comment "Build complete" or file anything: the work is in-flight, not done.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the ticket in `$CLAIMED` for human investigation.
-2. Resolve `$DONE` for this ticket's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this ticket's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `jira.workflow.done` is a string, that status is terminal.
    - If `jira.workflow.done` is an object, only the production/final environment value is terminal (default: `Done`). Intermediate env statuses such as `On Dev` and `On Stg` are not terminal and must remain unresolved / open.

package/plugins/lisa-agy/skills/lisa-linear-build-intake/SKILL.md

@@ -42,6 +42,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
 3. If `done` is a **string** in config, use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 TARGET_ENV="${target_env:-}"
@@ -333,10 +352,10 @@ A `done` env state (`On Dev`, `On Stg`, or the terminal value) asserts that the
 
 If the lifecycle run returned Success:
 1. **Confirm the PR merged.** Read the live state of the Issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before transitioning; a still-running deploy is treated like an open PR (leave at `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave at `$CLAIMED`), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the Issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it at `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or change the native state.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the Issue at `$CLAIMED`.
-2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `linear.workflow.done` is a string, that state is terminal.
    - If `linear.workflow.done` is an object, only the production/final environment value is terminal (default: `Done`). Intermediate env states such as `On Dev` and `On Stg` are not terminal — they are typed `started`, so the Issue correctly stays open and on the board.

package/plugins/lisa-agy/skills/lisa-repair-intake/SKILL.md

@@ -352,8 +352,9 @@ the vendor build-intake runs**, skipping the claim transition (the item is alrea
 2. **On agent success**, apply the scanner's post-agent transition yourself: `claimed → done`,
    where `done` is **env-resolved** exactly as `lisa:<tracker>-build-intake` resolves it (per
    `config-resolution` env-keyed `done`: explicit `target_env` arg wins; else reverse-lookup the
-   env from the resulting PR's base branch via `deploy.branches`; if `done` is a map and env is
-   unresolvable, fail loudly — never guess). repair-intake owns this transition because it is
+   env from the resulting PR's base branch via `deploy.branches`; then **cap the resolved env by
+   the promotion-completeness gate** — see "Promotion completeness" below; if `done` is a map and
+   env is unresolvable, fail loudly — never guess). repair-intake owns this transition because it is
    standing in for the scanner that never got to finish it.
 3. **On a surfaced blocker** (agent reports it cannot proceed), leave/move the item to `blocked`
    with a `[lisa-repair-intake]` note (see Loop prevention). When the surfaced blocker is something
@@ -393,9 +394,14 @@ same reviewer. Use the same paginated REST reduction documented by
 complete and the only thing missing is the env transition the build-intake never applied (its merge
 gate left the item `claimed` because the merge landed after its agent returned). Do **not** re-dispatch
 or file anything: apply the scanner's post-agent env-resolved `claimed → done` transition (the
-resume-sequence step 2, env-resolved from the merged PR's base branch) and record it as a repair
-write. Where the env deploy is observable, confirm it did not fail first; a failed post-merge deploy
-falls through to the blocker path (step 4).
+resume-sequence step 2, env-resolved from the merged PR's base branch **and capped by the
+promotion-completeness gate below**) and record it as a repair write.
+
+**Run the gate before the write, never after.** The blocker path (step 4) assumes the item is still
+`claimed`, so a deploy failure discovered *after* a lifecycle write has nowhere to go. Resolve every
+rung first: if the rung's deploy concluded anything but `success`, write **nothing**, leave the item
+`claimed`, and fall through to the blocker path; if it has not concluded, write nothing and leave it
+`claimed` for a later cycle. Only a fully resolved gate result is ever written.
 
 **3. PR only behind its base → re-sync in place (mechanical, not a blocker).** If the PR is clean but
 behind its base — `mergeStateStatus == BEHIND` while `mergeable != CONFLICTING` and no required check
@@ -495,6 +501,48 @@ recurred (<date>, <ref>), so we're raising it once more for your review.`); a ma
 _completed_ is a regression path, not a decline. Honor the backoff window and state fingerprint
 (Loop prevention) so re-runs over the same unchanged blocker are no-ops.
 
+#### Promotion completeness: the base branch is not the delivery
+
+A merged PR's base branch names the environment the change **entered**, not the environments it has
+**reached**. A hotfix merged straight to `main` enters production out of order: the reverse-lookup
+resolves `production`, `production` is terminal, and the item closes while `staging` has none of the
+fix and cannot deploy. The evidence is real — merged PR, merge-commit ancestry in `main`, a green
+production deploy — and the inference from it is still wrong.
+
+So before writing any env-resolved `done`, walk `deploy.order` from its **lowest** rung and keep
+rungs while they are **reached**, stopping at the first that is not. A rung is reached when both
+hold for its `deploy.branches` branch:
+
+- **Ancestry** — `git fetch origin <branch> && git merge-base --is-ancestor <merge-sha> origin/<branch>`,
+  asserted for **every** env branch at or below the resolved env — never only the PR's base.
+- **Deploy health** — that branch's most recent deploy **concluded `success`**. Read the
+  `conclusion`, never the `status`: an in-flight deploy has a null conclusion and is
+  indistinguishable from a pass on the status field alone. Only `success` promotes — a null
+  conclusion and every other conclusion (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`,
+  `stale`, `action_required`) leave the rung unreached. An unconcluded deploy is unknown, not green
+  — do not write that rung this cycle; a later cycle reads a concluded run. Where a project exposes
+  no deploy surface for a branch at all, ancestry alone decides that rung.
+
+Write the highest **contiguously reached** rung at or below the resolved env — never a higher rung,
+even when the higher rung is reached and a lower one is not. A merge present in `dev` and `main` but
+absent from `staging` writes `dev` (`On Dev`), which is intermediate: the item stays natively open
+and the promotion gap is what holds it open. When no rung is reached, write nothing and leave the
+item in its current role.
+
+The refusal is named, never silent. When the gate caps the env below the resolved one, the
+`[lisa-repair-intake]` note MUST carry all three fields —
+`<first unreached env> (<its branch>) — <condition>` — where the condition is exactly one of
+`missing ancestry`, `deploy unknown: <run URL, or "no concluded run">` (an in-flight run, or a
+branch with a deploy surface but nothing concluded), or
+`deploy concluded <conclusion>: <run URL>`. A failing run named without its environment and branch,
+or an environment named without its condition, is an incomplete note.
+
+**Do not classify the gap away.** An open back-fill PR against a skipped environment branch is
+*outstanding delivery*, not branch hygiene: it is the evidence that a rung was skipped, so it holds
+the item open. Recording "the fix reached dev and production but skipped staging, so that PR is a
+branch back-fill, not outstanding delivery" and then closing anyway is this defect exactly — the
+condition observed, filed under the wrong heading, and overridden.
+
 ### Build `blocked` → re-evaluate, unblock if cleared
 
 1. Read the block reason and classify the blocker (see Blocker classification & clearing). An item
@@ -556,6 +604,18 @@ native-open / active / unresolved:
 2. Verify the terminal `done` role is the true final value per `leaf-only-lifecycle` and
    `config-resolution` env-keyed `done`. Intermediate env labels (for example `status:on-dev` or
    `status:on-stg`) are not terminal and must stay open.
+
+   Verify too that the terminal role was **earned**, not merely worn: re-run the
+   promotion-completeness gate (above) against the item's merge commit, and close **only** when the
+   gate reports the terminal rung itself as reached. On a branch with a deploy surface that means
+   `conclusion == success`; an in-flight run, or no concluded run at all, does **not** reach the
+   rung and does **not** authorize closure. Where a branch exposes no deploy surface, ancestry alone
+   decides it, exactly as the gate documents. If any env branch at or below the terminal one lacks
+   the commit or fails its deploy-health test, do **not** close: demote the item to the highest
+   contiguously reached rung, keep it open, and refresh a `[lisa-repair-intake]` note carrying the
+   full refusal reason (env, branch, condition). A terminal label applied before the gate existed is
+   exactly how an out-of-order hotfix reaches native closure — so the label alone is never
+   sufficient evidence to close.
 3. Perform the provider-native terminal action idempotently:
    - GitHub: `gh issue close <number> --repo <org>/<repo> --reason completed`.
    - Linear: move the issue to the configured Done / Completed native workflow state if available;

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.28.0",
+  "version": "4.28.2",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/rules/eager/config-resolution.md

@@ -89,4 +89,27 @@ A non-integration environment bug is fixed, merged, and verified on that
 environment branch first, then
 forward cherry-picked down to the integration branch via a linked follow-up.
 
+## Env-keyed `done` — promotion completeness
+
+A merged PR's base branch names the environment a change **entered**, never the environments it has
+**reached**. Before writing an env-keyed `done`, walk `deploy.order` from its lowest rung and write
+the highest **contiguously reached** rung at or below the resolved env. A rung is reached only when
+the merge commit is an ancestor of its `deploy.branches` branch
+(`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at or
+below the resolved one, not only the PR's base) **and** that branch's most recent deploy
+**concluded `success`** — read the `conclusion`, never the `status`, because an in-flight deploy has
+a null conclusion and looks identical to a pass. Only a concluded `success` promotes: a null
+conclusion and every other conclusion (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`,
+`stale`, `action_required`) leave the rung unreached. Where `deploy.order` is absent the ladder is
+the single resolved env; where a branch exposes no deploy surface at all, ancestry alone decides
+that rung.
+
+A hotfix straight to `main` that skipped `staging` therefore resolves to the rung below the gap and
+stays open; the terminal value, and provider-native closure with it, is earned only by a
+promotion-complete merge. The recorded reason always carries all three fields —
+`<first unreached env> (<its branch>) — <condition>`, where the condition is `missing ancestry`,
+`deploy unknown: <run URL or "no concluded run">`, or `deploy concluded <conclusion>: <run URL>`. A
+failing run named without its environment and branch is an incomplete reason. An open back-fill PR
+against a skipped environment branch is outstanding delivery, not branch hygiene.
+
 Full reference: [reference/config-resolution.md](../reference/config-resolution.md).

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -600,9 +600,73 @@ Skills that transition to `done` MUST resolve the env first:
 1. **Explicit caller arg** (`target_env=staging`) — always wins.
 2. **Branch inference** — derive from the PR's base branch via `deploy.branches`. Reverse-lookup: if base branch is `staging`, env is `staging`.
 3. **Failure** — if neither resolves and `done` is a map, fail loudly. Never pick arbitrarily.
+4. **Promotion completeness** — cap the resolved env by the gate below before writing anything. Steps 1–2 resolve a *candidate*; the gate decides what is written.
 
 If a project's terminal state is the same regardless of env, set `done` to a string instead of a map (lifecycle skills accept either shape).
 
+#### Promotion completeness: every environment at or below the resolved one
+
+A merged PR's base branch says which environment the change **entered**. It never says which
+environments the change has **reached**. A hotfix merged straight to `main` enters production by an
+out-of-order route: the reverse-lookup resolves `production`, `production` is the terminal value,
+and the item closes while `staging` has none of the fix. Reaching the terminal environment is not
+the same as being delivered, and a base branch alone cannot tell those apart.
+
+So the resolved env is not the env that gets written. Walk `deploy.order` from its **lowest** rung
+and keep rungs while they are **reached**, stopping at the first that is not. A rung is reached
+when both hold for its `deploy.branches` branch:
+
+- **Ancestry** — the merge commit is an ancestor of the remote env branch:
+  `git fetch origin <branch> && git merge-base --is-ancestor <merge-sha> origin/<branch>`. Assert
+  this for **every** env branch at or below the resolved one — never only the PR's base.
+- **Deploy health** — that branch's most recent deploy **concluded `success`**. Read the
+  `conclusion`, never the `status`: an in-flight deploy has a null conclusion and is
+  indistinguishable from a pass on the status field alone. Only `success` promotes — a null
+  conclusion and every other conclusion (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`,
+  `stale`, `action_required`) leave the rung **unreached**. "Did not fail" is not the test: a
+  cancelled or skipped run is not evidence the change deployed.
+
+The written env is the highest **contiguously reached** rung at or below the resolved one — never a
+higher rung, even when the higher rung is reached and a lower one is not. A merge present in `dev`
+and `main` but absent from `staging` resolves to `dev` (`On Dev`), not `production`: the item stays
+open at an intermediate waypoint, and the promotion gap is what holds it open. When no rung at all
+is reached, write nothing and leave the item in its current role.
+
+Refusals are named, never silent, and one schema covers every case. Whenever the gate caps the env
+below the resolved one, the recorded reason MUST carry **all three** fields — none is optional in
+any case:
+
+```
+<first unreached env> (<its branch>) — <condition>
+```
+
+`<condition>` is exactly one of:
+
+- `missing ancestry` — the merge commit is not an ancestor of that branch.
+- `deploy unknown: <run URL, or "no concluded run">` — the branch has a deploy surface, but its most
+  recent run has not concluded, or nothing has ever concluded for it.
+- `deploy concluded <conclusion>: <run URL>` — the most recent run concluded as something other than
+  `success` (`failure`, `cancelled`, `timed_out`, `neutral`, `skipped`, `stale`, `action_required`).
+
+"Merged to `main` and production deployed green" and "not in `staging`" are both facts; a reason that
+carries only the first is the defect. A failing run named without its environment and branch, or an
+environment named without the condition that failed it, is an incomplete reason and not acceptable.
+
+Two classifications this gate forbids:
+
+- An **open back-fill PR** against a skipped environment branch is *outstanding delivery*, not
+  branch hygiene. It is the evidence that a rung was skipped, so it is a reason to hold the item
+  open — never a reason to discount the gap and close anyway.
+- An **in-flight deploy** is unknown, not green. When a rung's ancestry holds but its deploy run has
+  not concluded, do not write that rung this cycle: leave the item where it is and let a later cycle
+  read a concluded run. Only a concluded success promotes. A project that exposes **no** deploy
+  surface for a branch is a different case — there, ancestry alone decides the rung; the absence of
+  a deploy system is not an unconcluded deploy.
+
+Where `deploy.order` is absent the ladder is the single resolved env, and the gate is the ancestry
+and deploy-health check on that one rung. Multi-branch projects MUST set `deploy.order` (see "Env
+order" below), so an absent order can never silently skip the ladder.
+
 ### Env → base branch (forward: the build base and PR base)
 
 `deploy.branches` is also read in the **forward** direction by the build flow (`lisa-implement`): the environment a work item targets determines the branch the work is built on and the branch the PR opens against.
@@ -634,6 +698,7 @@ The true terminal `done` value is also the only value that triggers provider-nat
 - If `done` is a string, that value is terminal.
 - If `done` is an env-keyed map, the production / final environment's value is terminal. The conventional key is `production`; project-specific final env names must be explicit in deploy config or the lifecycle skill must fail rather than guessing.
 - Intermediate env values (`dev`, `staging`, or configured equivalents) are deployment waypoints. Applying them must not close / resolve / complete the native tracker item.
+- The terminal value is earned only by a **promotion-complete** merge: every env branch at or below the terminal one carries the merge commit, and none of their most recent concluded deploys failed. A merge that reached the terminal environment out of order has not earned the terminal value — see "Promotion completeness" above.
 
 ### Env order (sync-down chain)
 

package/plugins/lisa-copilot/skills/lisa-github-build-intake/SKILL.md

@@ -56,6 +56,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
 3. If `done` is a **string** in config, use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 TARGET_ENV="${target_env:-}"
@@ -478,10 +497,10 @@ A `done` env state (`status:on-dev`, `status:on-stg`, or the terminal value) ass
 If the lifecycle run returned Success:
 
 1. **Confirm the PR merged.** Read the live state of the issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before relabeling; a still-running deploy is treated like an open PR (leave in `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave in `$CLAIMED`), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it in `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or close anything.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the issue in `$CLAIMED`.
-2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `github.labels.build.done` is a string, that string is terminal.
    - If `github.labels.build.done` is an object, only the production/final environment value is terminal (default: `status:done`). Intermediate env values such as `status:on-dev` and `status:on-stg` are not terminal and must stay open.

package/plugins/lisa-copilot/skills/lisa-jira-build-intake/SKILL.md

@@ -39,6 +39,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup: if base is `staging`, env is `staging`).
 3. If `done` in config is a **string** (not a map), use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 # Resolve env, then DONE.
@@ -334,10 +353,10 @@ A `done` env status (`On Dev`, `On Stg`, or the terminal value) asserts that the
 
 If the lifecycle run returned Success:
 1. **Confirm the PR merged.** Read the live state of the ticket's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before transitioning; a still-running deploy is treated like an open PR (leave in `$CLAIMED` for a later cycle), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave in `$CLAIMED` for a later cycle), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the ticket under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it in `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once it is merged, applies this same env transition. Do **not** comment "Build complete" or file anything: the work is in-flight, not done.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the ticket in `$CLAIMED` for human investigation.
-2. Resolve `$DONE` for this ticket's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this ticket's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `jira.workflow.done` is a string, that status is terminal.
    - If `jira.workflow.done` is an object, only the production/final environment value is terminal (default: `Done`). Intermediate env statuses such as `On Dev` and `On Stg` are not terminal and must remain unresolved / open.

package/plugins/lisa-copilot/skills/lisa-linear-build-intake/SKILL.md

@@ -42,6 +42,25 @@ For env-keyed `done`, resolve the env first, then look up `done[<env>]`:
 2. Otherwise, infer the env from the PR's base branch via `deploy.branches` (reverse lookup).
 3. If `done` is a **string** in config, use it directly regardless of env.
 4. If `done` is a **map** and env cannot be resolved, **fail loudly** — do not pick arbitrarily.
+5. **Promotion completeness caps the result.** The base branch names the environment the change
+   *entered*, never the environments it has *reached*. Walk `deploy.order` from its lowest rung and
+   write the highest **contiguously reached** rung at or below the resolved env: a rung is reached
+   only when the merge commit is an ancestor of its `deploy.branches` branch
+   (`git merge-base --is-ancestor <merge-sha> origin/<branch>`, asserted for **every** env branch at
+   or below the resolved one — not only the PR's base) **and** that branch's most recent
+   deploy **concluded `success`** (read the `conclusion`, never the `status`; only `success`
+   promotes — a null conclusion and every other conclusion, `failure` / `cancelled` / `timed_out` /
+   `neutral` / `skipped` / `stale` / `action_required`, leave the rung unreached, and an in-flight
+   deploy is unknown, not green). Where `deploy.order` is absent the ladder is the single resolved
+   env; where a branch exposes no deploy surface at all, ancestry alone decides that rung. A hotfix
+   merged straight to the production branch that skipped `staging` therefore writes the rung below
+   the gap and stays open. The recorded reason carries all three fields —
+   `<first unreached env> (<its branch>) — <condition>`, the condition being `missing ancestry`,
+   `deploy unknown: <run URL, or "no concluded run">`, or
+   `deploy concluded <conclusion>: <run URL>`; a failing run named without its environment and
+   branch is an incomplete reason. An open back-fill PR against a
+   skipped environment branch is outstanding delivery, not branch hygiene. See `config-resolution`
+   → "Promotion completeness".
 
 ```bash
 TARGET_ENV="${target_env:-}"
@@ -333,10 +352,10 @@ A `done` env state (`On Dev`, `On Stg`, or the terminal value) asserts that the
 
 If the lifecycle run returned Success:
 1. **Confirm the PR merged.** Read the live state of the Issue's PR — `gh pr view <pr> --json state,mergedAt,mergeStateStatus,url`:
-   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), confirm it did not fail before transitioning; a still-running deploy is treated like an open PR (leave at `$CLAIMED`), a failed deploy is recorded as an Error.
+   - **Merged** (`state == MERGED`) → proceed to resolve and apply `$DONE` below. Where the env deploy is observable (a deploy workflow run / deployment status keyed to the merged-into branch via `deploy.branches`), run the **promotion-completeness gate** (resolution step 5) across **every** env branch at or below the resolved env — not only the merged-into branch. A rung counts only when the merge commit is an ancestor of its branch **and** that branch's most recent deploy concluded `success`; a still-running or otherwise unconcluded deploy is treated like an open PR (leave at `$CLAIMED`), and a rung whose deploy concluded anything but `success` is recorded as an Error. Where a branch exposes no deploy surface at all, ancestry alone decides that rung.
    - **Open / not yet merged** → do **not** transition. The build is sound but the change has reached no environment yet. Record the Issue under **"PR open — awaiting merge"** in the summary (with the PR URL and its `mergeStateStatus`), leave it at `$CLAIMED`, and stop. A later `lisa-repair-intake` cycle drives the open PR to merge — re-syncing a `BEHIND` branch so the already-enabled auto-merge can land, or surfacing a real blocker — and, once merged, applies this same env transition. Do **not** comment "Build complete" or change the native state.
    - **Closed without merging** → record an Error (the PR was abandoned unmerged); leave the Issue at `$CLAIMED`.
-2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
+2. Resolve `$DONE` for this issue's PR base branch using the Workflow resolution algorithm above, **including its promotion-completeness cap** (step 5): the value written is the highest contiguously reached rung at or below the resolved env, never the resolved env by itself. If env can't be resolved and `done` is env-keyed, record an Error and skip this transition — never guess.
 3. Determine whether `$DONE` is the true terminal done value per the `leaf-only-lifecycle` rule's Terminal native closure section:
    - If `linear.workflow.done` is a string, that state is terminal.
    - If `linear.workflow.done` is an object, only the production/final environment value is terminal (default: `Done`). Intermediate env states such as `On Dev` and `On Stg` are not terminal — they are typed `started`, so the Issue correctly stays open and on the board.