@codyswann/lisa 4.27.8 → 4.28.0

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-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.