@codyswann/lisa 4.27.9 → 4.28.1

package/plugins/lisa-cursor/scripts/repo-scope-vocabulary-audit.mjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+/**
+ * Repo-scope vocabulary audit for `/lisa:validate-tracker-mapping`.
+ *
+ * ## The gap this closes
+ *
+ * `/lisa:validate-tracker-mapping` audits LIFECYCLE roles: every pair it
+ * compares comes from a `(role, configured-name)` mapping declared in
+ * `.lisa.config.json`. The SCOPING vocabulary is declared in no config key, so
+ * the audit has nothing to compare it 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
+ * repo's build queue can see. When the repo vocabulary drifts, 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.
+ *
+ * The OPEN scoping families — `type:`, `priority:`, `points:`, `component:` —
+ * are a separate problem with a separate answer, tracked upstream on #3420.
+ * This module deliberately does not touch them, for the reason below.
+ *
+ * ## Why this family asserts membership when `component:` may not
+ *
+ * The ruling on #3420 — Lisa asserts no authority over project label
+ * vocabularies — is about vocabularies that are OPEN and PROJECT-SPECIFIC. An
+ * open vocabulary has no wrong member, only inconsistent ones, and declaring
+ * one in config would demand per-project curation that becomes its own drift
+ * surface. None of that describes `repo:`:
+ *
+ * - `config-resolution` already declares `repo:<name>` canonical and uniform
+ *   across trackers, so the canonical FORM is settled upstream, not per project.
+ * - The MEMBERS are derived, never curated: the caller resolves them from the
+ *   repo-identity ladder (config `repo` → `github.repo` → git remote basename)
+ *   and, in batch mode, from the sibling projects sharing one tracker. This
+ *   module takes them as input and adds no config key.
+ *
+ * So there is nothing here for a human to hand-maintain, and no new place for
+ * the declaration itself to drift.
+ *
+ * ## Why these findings are drift and not smells
+ *
+ * The open families need a heuristic — is `component:plugin` a typo of
+ * `component:plugins`? — and a heuristic is sometimes wrong, which is why
+ * #3420 rules that findings about them must stay advisory and must never
+ * become a gate. That constraint exists to stop a GUESS becoming a gate, and
+ * it is not weakened here, because nothing here is a guess. `assertRepoScope`
+ * (`lisa-work-item.mjs`, #1957) accepts THREE spellings as valid repo scope:
+ *
+ *     repo:<name>   canonical
+ *     <name>        bare label — Sentry-provenance items arrive carrying only this
+ *     <name>        Jira component equal to the bare name
+ *
+ * The bare branch is deliberate and load-bearing; removing it would break that
+ * ingestion path. But every build-intake scanner FILTERS on `repo:<name>`. So
+ * an item carrying only the bare spelling passes validation while being
+ * invisible to every scan that looks for it. That is not a smell about which
+ * reasonable people differ — it is a checkable disagreement between what
+ * validation accepts and what filtering finds, and it is the exact shape of the
+ * under-read this audit exists to make loud.
+ *
+ * ## Why nothing here is ever auto-repaired
+ *
+ * Every finding is `autoRepairable: false`, including under `repair=true`.
+ * `repair=true` may rewrite the CONFIG, never the tracker, and every fix
+ * available here is a tracker mutation: stamping the canonical label on an
+ * item, renaming a malformed marker, or deciding whether an undeclared scope
+ * names a real repo or a typo. A human decides; this module reports.
+ *
+ * @module plugins/src/base/scripts/repo-scope-vocabulary-audit
+ */
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** The family this module audits. Canonical marker form is `repo:<name>`. */
+export const REPO_SCOPE_FAMILY = "repo";
+
+/** The canonical separator between the family and the repo name. */
+export const CANONICAL_SEPARATOR = ":";
+
+/**
+ * Separators seen standing in for the canonical `:` on a repo marker.
+ *
+ * A label like `repo-frontend` reads to a human as a repo marker and is not
+ * one: no scanner filters on it, and `assertRepoScope` does not accept it
+ * either, so it scopes an item to nothing at all. Observed on a live tracker
+ * alongside the canonical form, carrying zero items — a vocabulary that had
+ * split without anything noticing.
+ */
+export const MALFORMED_SEPARATORS = Object.freeze(["-", "_", "/", "."]);
+
+/** Every finding this module can emit. All of them are real drift. */
+export const REPO_SCOPE_FINDING_KINDS = Object.freeze([
+  "unstamped-alias",
+  "malformed-marker",
+  "undeclared-scope",
+]);
+
+/**
+ * @typedef {{
+ *   readonly ref?: string
+ *   readonly labels?: readonly (string | { readonly name?: string })[]
+ *   readonly components?: readonly (string | { readonly name?: string })[]
+ * }} WorkItem
+ *
+ * @typedef {{
+ *   readonly family: "repo"
+ *   readonly kind: string
+ *   readonly label: string
+ *   readonly repo?: string
+ *   readonly canonical?: string
+ *   readonly items: readonly string[]
+ *   readonly severity: "drift"
+ *   readonly autoRepairable: false
+ *   readonly detail: string
+ * }} RepoScopeFinding
+ */
+
+/**
+ * Normalize a label/component list to lowercase names, as `assertRepoScope`
+ * does. Its matching is case-insensitive, so a bare `Infrastructure` label
+ * scopes an item to `infrastructure` — and is just as invisible to a
+ * `repo:infrastructure` filter as a lowercase one would be.
+ *
+ * @param {readonly (string | { readonly name?: string })[] | undefined} value
+ * @returns {string[]} lowercased names, non-strings dropped
+ */
+export function namesFrom(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map(item => (typeof item === "string" ? item : item?.name))
+    .filter(name => typeof name === "string")
+    .map(name => name.trim().toLowerCase())
+    .filter(name => name.length > 0);
+}
+
+/**
+ * The canonical repo marker for a repo short name.
+ *
+ * @param {string} repo
+ * @returns {string} e.g. `repo:frontend`
+ */
+export function canonicalRepoLabel(repo) {
+  return `${REPO_SCOPE_FAMILY}${CANONICAL_SEPARATOR}${String(repo).trim().toLowerCase()}`;
+}
+
+/**
+ * Split a label that is shaped like a repo marker into its separator and value.
+ *
+ * Returns `null` for anything that does not begin `repo<separator>` — a bare
+ * repo name is not a marker (it is an alias, handled per item, because whether
+ * it is drift depends on what else that item carries), and `component:frontend`
+ * belongs to another family entirely.
+ *
+ * @param {unknown} name
+ * @returns {{ separator: string, value: string } | null}
+ */
+export function parseRepoMarker(name) {
+  if (typeof name !== "string") return null;
+  const trimmed = name.trim().toLowerCase();
+  if (!trimmed.startsWith(REPO_SCOPE_FAMILY)) return null;
+
+  const separator = trimmed.slice(
+    REPO_SCOPE_FAMILY.length,
+    REPO_SCOPE_FAMILY.length + 1
+  );
+  if (
+    separator !== CANONICAL_SEPARATOR &&
+    !MALFORMED_SEPARATORS.includes(separator)
+  ) {
+    return null;
+  }
+
+  const value = trimmed.slice(REPO_SCOPE_FAMILY.length + 1).trim();
+  if (value.length === 0) return null;
+  return { separator, value };
+}
+
+/**
+ * Audit a tracker's repo-scoping vocabulary.
+ *
+ * Total and read-only: mutates nothing, reaches nothing over the network, and
+ * returns every finding rather than the first.
+ *
+ * @param {{
+ *   readonly knownRepos?: readonly string[]
+ *   readonly items?: readonly WorkItem[]
+ *   readonly labels?: readonly (string | { readonly name?: string })[]
+ * }} input
+ *   `knownRepos` is the derived repo vocabulary — the repo-identity ladder for
+ *   a single project, or the sibling set in batch mode. `items` are the live
+ *   work items with their labels (and Jira components). `labels` is the
+ *   tracker's declared label set, which catches a malformed marker carrying
+ *   zero items.
+ * @returns {{
+ *   readonly verdict: "VALID" | "DRIFTED" | "UNRESOLVABLE"
+ *   readonly findings: readonly RepoScopeFinding[]
+ *   readonly knownAliases: readonly { readonly label: string, readonly canonical: string, readonly items: readonly string[] }[]
+ *   readonly vocabulary: readonly string[]
+ * }}
+ */
+export function auditRepoScopeVocabulary(input = {}) {
+  const vocabulary = [
+    ...new Set(
+      (Array.isArray(input.knownRepos) ? input.knownRepos : [])
+        .filter(repo => typeof repo === "string")
+        .map(repo => repo.trim().toLowerCase())
+        .filter(repo => repo.length > 0)
+    ),
+  ];
+
+  // An empty vocabulary cannot be audited, and reporting VALID for it would
+  // reproduce the very failure this module exists to catch: a check that
+  // returns "nothing wrong" when it in fact looked at nothing.
+  if (vocabulary.length === 0) {
+    return {
+      verdict: /** @type {const} */ ("UNRESOLVABLE"),
+      findings: [],
+      knownAliases: [],
+      vocabulary,
+    };
+  }
+
+  const items = Array.isArray(input.items) ? input.items : [];
+  const { aliasFindings, knownAliases } = aliasUsage(items, vocabulary);
+
+  const findings = [
+    ...aliasFindings,
+    ...markerFindings(declaredNames(input.labels, items), vocabulary),
+  ];
+
+  return {
+    verdict: /** @type {const} */ (findings.length === 0 ? "VALID" : "DRIFTED"),
+    findings,
+    knownAliases,
+    vocabulary,
+  };
+}
+
+/**
+ * Every label name in play: the tracker's declared set unioned with the labels
+ * observed on items.
+ *
+ * The declared set is what catches a malformed marker nobody has applied yet —
+ * a label sitting at zero usage beside the canonical form is a vocabulary that
+ * has already split, and the next item to receive it disappears from the queue.
+ *
+ * @param {readonly (string | { readonly name?: string })[] | undefined} labels
+ * @param {readonly WorkItem[]} items
+ * @returns {string[]}
+ */
+function declaredNames(labels, items) {
+  return [
+    ...new Set([
+      ...namesFrom(labels),
+      ...items.flatMap(item => namesFrom(item?.labels)),
+    ]),
+  ];
+}
+
+/**
+ * Per item, per known repo: does what `assertRepoScope` accepts agree with what
+ * a canonical filter would find?
+ *
+ * An item carrying an accepted alias — the bare repo name as a label, or as a
+ * Jira component — WITHOUT the canonical `repo:<name>` beside it passes
+ * validation and is invisible to every scan. Carrying both is a known alias
+ * and harmless: the item is still found. That difference is the whole check,
+ * and it is why an alias cannot be judged from the label set alone.
+ *
+ * @param {readonly WorkItem[]} items
+ * @param {readonly string[]} vocabulary
+ * @returns {{ aliasFindings: RepoScopeFinding[], knownAliases: { label: string, canonical: string, items: string[] }[] }}
+ */
+function aliasUsage(items, vocabulary) {
+  /** @type {Map<string, { repo: string, items: string[] }>} */
+  const unstamped = new Map();
+  /** @type {Map<string, { repo: string, items: string[] }>} */
+  const stamped = new Map();
+
+  items.forEach((item, index) => {
+    const ref = itemRef(item, index);
+    const labelNames = namesFrom(item?.labels);
+    const componentNames = namesFrom(item?.components);
+
+    for (const repo of vocabulary) {
+      const aliases = [
+        labelNames.includes(repo) ? repo : undefined,
+        componentNames.includes(repo) ? `component:${repo}` : undefined,
+      ].filter(alias => alias !== undefined);
+      if (aliases.length === 0) continue;
+
+      const bucket = labelNames.includes(canonicalRepoLabel(repo))
+        ? stamped
+        : unstamped;
+      for (const alias of aliases) {
+        if (!bucket.has(alias)) bucket.set(alias, { repo, items: [] });
+        bucket.get(alias).items.push(ref);
+      }
+    }
+  });
+
+  return {
+    aliasFindings: [...unstamped].map(([label, entry]) => ({
+      family: /** @type {const} */ (REPO_SCOPE_FAMILY),
+      kind: "unstamped-alias",
+      label,
+      repo: entry.repo,
+      canonical: canonicalRepoLabel(entry.repo),
+      items: entry.items,
+      severity: /** @type {const} */ ("drift"),
+      autoRepairable: /** @type {const} */ (false),
+      detail:
+        `"${label}" is an accepted alias for repository "${entry.repo}", so ` +
+        `${entry.items.length} work item(s) carrying it pass repo-scope ` +
+        `validation — but they do not carry "${canonicalRepoLabel(entry.repo)}", ` +
+        `which is what every build-intake scan filters on. Those items are ` +
+        `invisible to that scan, and the scan reports no error. Stamping the ` +
+        `canonical label alongside the alias is a tracker change a human makes.`,
+    })),
+    knownAliases: [...stamped].map(([label, entry]) => ({
+      label,
+      canonical: canonicalRepoLabel(entry.repo),
+      items: entry.items,
+    })),
+  };
+}
+
+/**
+ * Label-set findings: markers that look canonical and are not, and canonical
+ * markers naming a repo outside the derived vocabulary.
+ *
+ * @param {readonly string[]} names
+ * @param {readonly string[]} vocabulary
+ * @returns {RepoScopeFinding[]}
+ */
+function markerFindings(names, vocabulary) {
+  return names.flatMap(name => {
+    const marker = parseRepoMarker(name);
+    if (!marker) return [];
+
+    if (marker.separator !== CANONICAL_SEPARATOR) {
+      // Only a malformed marker naming a KNOWN repo is reportable. `repo-x` for
+      // an unknown `x` is just a label whose name happens to start with "repo";
+      // calling it drift would report every unrelated label into the noise.
+      if (!vocabulary.includes(marker.value)) return [];
+      return [
+        {
+          family: /** @type {const} */ (REPO_SCOPE_FAMILY),
+          kind: "malformed-marker",
+          label: name,
+          repo: marker.value,
+          canonical: canonicalRepoLabel(marker.value),
+          items: [],
+          severity: /** @type {const} */ ("drift"),
+          autoRepairable: /** @type {const} */ (false),
+          detail:
+            `"${name}" is shaped like a repo marker but uses "${marker.separator}" ` +
+            `where the canonical form uses "${CANONICAL_SEPARATOR}". It scopes ` +
+            `nothing: no scan filters on it, and repo-scope validation does not ` +
+            `accept it either. The canonical form is ` +
+            `"${canonicalRepoLabel(marker.value)}".`,
+        },
+      ];
+    }
+
+    if (vocabulary.includes(marker.value)) return [];
+    return [
+      {
+        family: /** @type {const} */ (REPO_SCOPE_FAMILY),
+        kind: "undeclared-scope",
+        label: name,
+        repo: marker.value,
+        items: [],
+        severity: /** @type {const} */ ("drift"),
+        autoRepairable: /** @type {const} */ (false),
+        detail:
+          `"${name}" scopes work to a repository "${marker.value}" that is not ` +
+          `in the derived vocabulary (${vocabulary.join(", ")}). Either it names ` +
+          `a repository this tracker serves — in which case the project set is ` +
+          `incomplete — or it is a misspelling routing work nowhere. Both are ` +
+          `human decisions, so this is never repaired automatically.`,
+      },
+    ];
+  });
+}
+
+/**
+ * A stable, reportable identifier for a work item.
+ *
+ * @param {WorkItem} item
+ * @param {number} index
+ * @returns {string}
+ */
+function itemRef(item, index) {
+  const ref = item?.ref;
+  return typeof ref === "string" && ref.trim().length > 0
+    ? ref.trim()
+    : `item[${index}]`;
+}
+
+/**
+ * CLI: read `{ knownRepos, items, labels }` on stdin, print the audit.
+ *
+ * Exits 0 even when the verdict is DRIFTED. The verdict is what the caller
+ * reports; the exit status is not a second, quieter channel for the same
+ * answer, and a non-zero exit would make this a gate the first time something
+ * ran it under `set -e`.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const payload = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+
+  process.stdout.write(
+    `${JSON.stringify(
+      auditRepoScopeVocabulary({
+        knownRepos: payload.knownRepos,
+        items: payload.items,
+        labels: payload.labels,
+      }),
+      null,
+      2
+    )}\n`
+  );
+}
+
+/**
+ * True when `moduleUrl` names the module node was asked to run.
+ *
+ * Written out rather than imported: this is a plugin payload, which has no
+ * `./lib/` to resolve against. Same rule and same reasoning as
+ * `scripts/lib/invoked-as-script.mjs` and `lifecycle-label-trust.mjs`.
+ *
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+export function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  main().catch(error => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/plugins/lisa-cursor/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-cursor/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-cursor/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.