@codyswann/lisa 4.27.9 → 4.28.1

package/plugins/lisa-copilot/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-copilot/skills/lisa-validate-tracker-mapping/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-validate-tracker-mapping
-description: "Detect and repair drift between a project's configured Lisa status/label mappings and the live tracker/source workflow. Compares every lifecycle role in `.lisa.config.json` (JIRA `jira.workflow` statuses, GitHub/Linear `labels.{build,prd}`, Notion `notion.values` select options, Confluence `confluence.parents`) against the authoritative live names the access layer reports — catching renames, deletions, and case drift (e.g. config `On Stg` vs live `ON STG`). Read-only by default; `repair=true` rewrites the config to the canonical live names (config is fixed, never the tracker). Also reports advisory GitHub scoping-label smells that no config declares — `type:`/`priority:` outside their closed sets, `component:` synonyms of an established value, off-Fibonacci `points:` — which never gate and are never repaired. Audits the current repo by default, or sweeps a set of projects via `projects=<glob>` / `workspaces=<file>`. Safe to schedule for continuous drift detection."
+description: "Detect and repair drift between a project's configured Lisa status/label mappings and the live tracker/source workflow. Compares every lifecycle role in `.lisa.config.json` (JIRA `jira.workflow` statuses, GitHub/Linear `labels.{build,prd}`, Notion `notion.values` select options, Confluence `confluence.parents`) against the authoritative live names the access layer reports — catching renames, deletions, and case drift (e.g. config `On Stg` vs live `ON STG`). Read-only by default; `repair=true` rewrites the config to the canonical live names (config is fixed, never the tracker). Also audits the vocabularies no config key declares: `repo:` scope, where an item scoped only by an alias is valid yet invisible to every `repo:<name>` scan (DRIFTED), and `type:`/`priority:`/`component:`/`points:` smells (advisory). Neither is auto-repaired. Audits the current repo by default, or sweeps a set of projects via `projects=<glob>` / `workspaces=<file>`. Safe to schedule for continuous drift detection."
 allowed-tools: ["Skill", "Bash", "Read", "Write", "Edit", "AskUserQuestion"]
 ---
 
@@ -125,8 +125,8 @@ One role carries a further check that name-existence cannot express:
 A project's verdict:
 
 - **VALID** — every role is VALID.
-- **DRIFTED** — at least one CASE_DRIFT, MISSING, or INVERTED role, none of which is UNRESOLVABLE. An INVERTED `ready` is never VALID, no matter how cleanly it resolves.
-- **UNRESOLVABLE** — the live set couldn't be enumerated (auth mismatch, missing tracker config, access failure). Distinguish this loudly from VALID — an unresolved audit is not a passing audit.
+- **DRIFTED** — at least one CASE_DRIFT, MISSING, or INVERTED role, none of which is UNRESOLVABLE, **or** any Step 4b repo-scope finding. An INVERTED `ready` is never VALID, no matter how cleanly it resolves.
+- **UNRESOLVABLE** — the live set couldn't be enumerated (auth mismatch, missing tracker config, access failure), **or** Step 4b could not derive a repo vocabulary. Distinguish this loudly from VALID — an unresolved audit is not a passing audit.
 
 ## Step 4b — Scoping-label smells (GitHub, advisory)
 
@@ -211,6 +211,99 @@ Three finding kinds, all `severity: "advisory"`:
 Do not re-derive any of these thresholds in prose or in a second script. The
 module is the single definition; this step calls it.
 
+## Step 4c — Repo-scope vocabulary (all trackers, counts toward the verdict)
+
+Steps 2–4 audit **lifecycle** roles, and they can only ever audit lifecycle
+roles: every pair they compare comes from a `(role, configured-name)` mapping
+declared in `.lisa.config.json`. The **scoping** vocabulary is declared in no
+config key at all, so there is nothing to compare a live name against.
+
+`repo:` is the scoping family where that blind spot costs the most, because a
+wrong answer there is not a matter of taste: it decides which work items a
+repository's build queue can see. When the repo vocabulary splits, a scan
+filtering on the canonical spelling returns **fewer items, not an error**, and
+an empty result is indistinguishable from "nothing to do". Work sits unrouted
+and nobody is told. This step is what makes that impossible.
+
+> The **open** scoping families — `type:`, `priority:`, `points:`,
+> `component:` — are a separate problem with a separate answer, tracked
+> upstream on #3420. An open vocabulary has no wrong member, only inconsistent
+> ones, so findings about it must stay advisory and must never become a gate.
+> That constraint exists to stop a *guess* becoming a gate; it is not weakened
+> here, because nothing in this step is a guess. Do not extend this step to
+> those families.
+
+`assertRepoScope` (`lisa-work-item.mjs`, #1957) accepts **three** spellings as
+valid repo scope, while every build-intake scanner filters on one:
+
+| spelling | accepted by validation | found by a `repo:<name>` scan |
+| --- | --- | --- |
+| `repo:<name>` (canonical) | yes | **yes** |
+| bare `<name>` label | yes | **no** |
+| Jira component `<name>` | yes | **no** |
+
+The bare branch is deliberate and load-bearing — Sentry-provenance items arrive
+carrying only the bare repo name — so it is **not** to be tightened away. What
+this step reports is the *disagreement* between the two columns: an item that
+passes validation while being invisible to every scan looking for it. That is a
+checkable fact about a specific item, not a heuristic about a name, which is
+why these findings count toward the verdict.
+
+### Derive the vocabulary — never declare it in config
+
+Do **not** add a config key for this, and do not accept one if you find it. A
+hand-written repo vocabulary is per-project curation of a list that is already
+derivable, and it becomes its own drift surface — the same objection that
+rejected declaring the open vocabularies. A key nothing reads would look like
+an assertion while asserting nothing. Derive it instead:
+
+- **Single-project mode**: the current-repo identity ladder from
+  `config-resolution` — `.lisa.config.local.json` `repo` → `.lisa.config.json`
+  `repo` → `.lisa.config.json` `github.repo` → `basename -s .git` of the git
+  remote.
+- **Batch mode** (`projects=<glob>` / `workspaces=<file>`): the union of that
+  ladder across every resolved project, which is exactly the set of repos this
+  one tracker serves.
+
+If the vocabulary resolves **empty**, the verdict is `UNRESOLVABLE`, never
+`VALID`. A check that reports "nothing wrong" having looked at nothing is the
+same failure this step exists to catch.
+
+### Collect and classify
+
+Feed the derived vocabulary, the live work items with their labels (and Jira
+components), and the tracker's declared label set — the declared set is what
+catches a malformed marker carrying zero items:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/repo-scope-vocabulary-audit.mjs" \
+  < /tmp/lisa-repo-scope-input.json
+```
+
+Input is `{ knownRepos: [...], items: [{ ref, labels, components }], labels: [...] }`.
+It returns `{ verdict, findings, knownAliases, vocabulary }` and always exits
+`0` — the verdict is the answer, and the exit status is not a second, quieter
+channel for it. Three finding kinds, all `severity: "drift"`:
+
+- **`unstamped-alias`** — work items carry an accepted alias (bare label or
+  Jira component) for a known repo **without** the canonical `repo:<name>`
+  beside it. They pass validation and no scan finds them. The finding names the
+  alias and every item carrying it.
+- **`malformed-marker`** — a label shaped like a repo marker with the wrong
+  separator (`repo-frontend`, `repo_backend`). It scopes nothing at all: no
+  scan filters on it and validation does not accept it either.
+- **`undeclared-scope`** — a `repo:<value>` label naming a repo outside the
+  derived vocabulary. Either the project set is incomplete or the label is a
+  misspelling routing work nowhere.
+
+An alias on an item that **also** carries the canonical marker is reported in
+`knownAliases`, **not** as drift — every scan still finds that item, so nothing
+is wrong. That distinction is the whole check: an alias cannot be judged from
+the label set alone, only per item.
+
+Fold `DRIFTED` from this step into the project verdict exactly as a
+`CASE_DRIFT` or `MISSING` role does.
+
 ## Step 5 — Report
 
 Per project, print a terminal-first section:
@@ -236,6 +329,24 @@ An INVERTED `ready` gets a full line rather than a one-word status, because the
       via /lisa:setup:linear, then set linear.workflow.ready to it.
 ```
 
+Print the Step 4c findings **with this mapping table**, not as a separate
+advisory block — they are drift, and a reader must not mistake them for
+smells. Name the items, because "which tickets are invisible" is the operator's
+actual question:
+
+```
+  repo scope      derived vocabulary: backend, frontend, infrastructure
+    backend            2 items scoped by the bare label only    UNSTAMPED_ALIAS
+        SE-9, SE-10 pass repo-scope validation but carry no "repo:backend",
+        so every build scan for backend skips them and reports no error.
+        Stamping "repo:backend" on those items is a tracker change a human makes.
+    repo-frontend      0 items                                  MALFORMED_MARKER
+    repo:mobile        outside the derived vocabulary           UNDECLARED_SCOPE
+```
+
+A project whose repo vocabulary is in good order prints
+`repo scope: VALID` and nothing else.
+
 Print the Step 4b findings, when there are any, as a clearly separate advisory
 block **below** the mapping table so nobody reads a smell as a mapping failure:
 
@@ -250,7 +361,7 @@ Write those lines for a non-technical operator: say what was seen and what a
 person might do about it, never "FAIL". A healthy repository prints
 `scoping labels: none` and nothing else.
 
-End with a roll-up: counts of VALID / DRIFTED / UNRESOLVABLE projects and the exact next command (`… repair=true` when drift is auto-repairable; an admin note when a status is genuinely MISSING; `/lisa:setup:linear` when a `ready` is INVERTED). Scoping findings are reported alongside that roll-up as a **separate count**, never folded into DRIFTED.
+End with a roll-up: counts of VALID / DRIFTED / UNRESOLVABLE projects and the exact next command (`… repair=true` when drift is auto-repairable; an admin note when a status is genuinely MISSING; `/lisa:setup:linear` when a `ready` is INVERTED; an admin note naming the items when a repo scope is UNSTAMPED_ALIAS). Scoping-label findings are reported alongside that roll-up as a **separate count**, never folded into DRIFTED.
 
 ## Step 6 — Repair (only when `repair=true`)
 
@@ -305,6 +416,22 @@ real issue metadata on a coin flip. Report the finding, name the two spellings,
 and leave the decision to a human — and note that reconciling them means
 relabelling the issues, which is a tracker mutation this skill never performs.
 
+### Repo-scope findings — never repaired, for a different reason
+
+Step 4c findings are never auto-repaired either, but not because the right
+answer is unknowable — often it is obvious. It is because **every** available
+fix is a **tracker** mutation, and `repair=true` writes the config only:
+
+- an `unstamped-alias` is fixed by adding `repo:<name>` to the work items,
+- a `malformed-marker` by renaming or deleting a label,
+- an `undeclared-scope` by deciding whether the name is a real repository (so
+  the project set is incomplete) or a misspelling (so the label is wrong).
+
+There is no config edit that resolves any of them, and there is deliberately no
+config key to edit — see Step 4c on why the vocabulary is derived. Report the
+finding, name the items, and leave the tracker to a human.
+
+
 ### Invalidate the verification cache
 
 After any JIRA repair, clear the `setup-jira` reachability cache so it re-verifies the new mapping:
@@ -334,3 +461,7 @@ Re-print the project section showing the post-repair mapping and the new verdict
 - Reuse the config-resolution defaults and the vendor access skills (`atlassian-access`, `gh`, Linear/Notion MCP); do not invent a parallel mapping or lifecycle vocabulary.
 - Scoping-label findings (Step 4b) are **advisory**. They never change a project's verdict, never change this skill's exit status, and are never auto-repaired. Do not add a flag that turns them into a gate.
 - Never let Step 4b fail the run. A `gh` error, a non-GitHub tracker, or an empty repository means the scoping section reports "not collected" — the lifecycle verdict is unaffected either way.
+- Step 4c repo-scope findings are **drift**, not smells: they count toward the verdict and are reported with the mapping table. They are still never auto-repaired, because every fix is a tracker mutation.
+- Derive the repo vocabulary from the current-repo identity ladder (and, in batch mode, the resolved project set). Never introduce a config key declaring it, and never trust one — a hand-written vocabulary is a second thing to drift, and a key nothing reads would assert nothing while looking like an assertion.
+- An empty derived repo vocabulary is `UNRESOLVABLE`, never `VALID`. The whole point of Step 4c is that a silent zero is the failure, so a zero-length vocabulary must never read as a pass.
+- Do not extend Step 4c to the open scoping families (`type:`, `priority:`, `points:`, `component:`). Findings about those are heuristic and must stay advisory — see #3420.

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

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

package/plugins/lisa-cursor/rules/config-resolution-reference.mdc

@@ -605,9 +605,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.
@@ -639,6 +703,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-cursor/rules/config-resolution.mdc

@@ -94,4 +94,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](config-resolution-reference.mdc).