@codyswann/lisa 4.27.9 → 4.28.1

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.27.9",
+  "version": "4.28.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.27.9",
+  "version": "4.28.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.27.9",
+  "version": "4.28.1",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/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/src/base/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/src/base/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/src/base/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.