@codyswann/lisa 4.32.2 → 4.33.0

package/all/copy-overwrite/scripts/lib/gate-failure-diagnosis.mjs

@@ -29,6 +29,13 @@
  * measurement when the suite that produced it finished.
  * @module lib/gate-failure-diagnosis
  */
+import { availableParallelism, loadavg } from "node:os";
+
+/** Default load-average source for {@link machineLoad}. */
+const osLoadavg = () => loadavg();
+
+/** Default core-count source for {@link machineLoad}. */
+const osCores = () => availableParallelism();
 
 /** What a failed gate's output was recognised as. */
 export const DIAGNOSIS = Object.freeze({
@@ -445,9 +452,11 @@ function wasKilled(code) {
  * sitting on top of. Nothing the output says is a verdict once the run was
  * terminated.
  * @param {number|null} code The exit code, or null when none was obtained.
+ * @param {LoadReading|null} [load] The machine's load at diagnosis time, from
+ *   {@link machineLoad}. Omitted or null when it could not be read.
  * @returns {Diagnosis} The verdict.
  */
-function killedVerdict(code) {
+function killedVerdict(code, load) {
   const named = SIGNAL_EXITS[code];
   const cause =
     named === undefined
@@ -460,10 +469,85 @@ function killedVerdict(code) {
       `reached no verdict, and its output is a truncated transcript rather ` +
       `than a result. Re-run it on a quieter machine before reading anything ` +
       `into what it printed`,
-    evidence: [],
+    evidence: loadEvidence(load ?? null),
   };
 }
 
+/**
+ * The machine's run-queue pressure, or `null` when it cannot be read.
+ * @typedef {object} LoadReading
+ * @property {number} load1 One-minute load average.
+ * @property {number} cores Logical cores available to this process.
+ * @property {number} ratio `load1 / cores` — runnable work per core.
+ */
+
+/**
+ * Read the machine's current run-queue pressure.
+ *
+ * Injected rather than called inline so a test can state a load instead of
+ * inheriting whatever the test machine happened to be doing, which would make
+ * the assertion a coin flip on a busy box — the very condition this reading
+ * exists to describe.
+ * @param {() => number[]} [readLoadavg] Load-average source.
+ * @param {() => number} [readCores] Core-count source.
+ * @returns {LoadReading|null} The reading, or null when either source fails.
+ */
+export function machineLoad(readLoadavg = osLoadavg, readCores = osCores) {
+  try {
+    const load1 = readLoadavg()[0];
+    const cores = readCores();
+    if (!Number.isFinite(load1) || !Number.isFinite(cores) || cores <= 0) {
+      return null;
+    }
+    return { load1, cores, ratio: load1 / cores };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Turn a load reading into the one line an operator needs beside a kill.
+ *
+ * A kill that says only "the machine was busy" is still prose. What decides
+ * whether to re-run or to investigate is the NUMBER, and the number cuts both
+ * ways on purpose: an oversubscribed box says re-run, and a quiet one says the
+ * saturation story does not hold here, go and find the real killer. Reporting
+ * only the first case would make this a rubber stamp for "not my change".
+ *
+ * The reading is taken when the failure is diagnosed, which is after the kill,
+ * so it lags — load is falling by then. The line says so rather than implying a
+ * precision it does not have.
+ * @param {LoadReading|null} load The reading, or null when unavailable.
+ * @returns {string[]} Zero or one evidence line.
+ */
+function loadEvidence(load) {
+  if (load === null) return [];
+  const ratio = load.ratio.toFixed(1);
+  const where = `load1 ${load.load1.toFixed(1)} across ${load.cores} core(s), ${ratio}x per core`;
+  return load.ratio >= SATURATED_RATIO
+    ? [
+        `machine at diagnosis (after the kill, so this is a floor): ${where}. ` +
+          `A box at this level terminates processes to survive; read this as ` +
+          `saturation, not as a defect in the change.`,
+      ]
+    : [
+        `machine at diagnosis (after the kill, so this is a floor): ${where}. ` +
+          `That is not saturation, so contention does not explain this kill — ` +
+          `look for a timeout, an OOM, or an operator interrupt.`,
+      ];
+}
+
+/**
+ * Runnable work per core above which the box is treated as saturated.
+ *
+ * Two, not one. A load average equal to the core count is a machine that is
+ * fully used, which is what a test suite is supposed to do; twice that is a
+ * machine where every runnable thread is waiting behind another one. The
+ * sighting behind this issue was 21x, and the state after the fleet had already
+ * been asked to throttle was 8.3x, so the boundary is not close to either arm.
+ */
+const SATURATED_RATIO = 2;
+
 /**
  * The verdict for a failure whose transcript never reached this module.
  *
@@ -530,10 +614,11 @@ function emptyTranscriptVerdict() {
  *   when the runner could not capture it.
  * @param {number|null|undefined} code The command's exit code, or null when the
  *   runner could not obtain one.
+ * @param {LoadReading|null} load The machine's load at diagnosis time.
  * @returns {object} What the failure was, before it is attributed.
  */
-function classify(output, code) {
-  if (wasKilled(code)) return killedVerdict(code ?? null);
+function classify(output, code, load) {
+  if (wasKilled(code)) return killedVerdict(code ?? null, load);
 
   if (typeof output !== "string") return unavailableVerdict();
 
@@ -597,9 +682,12 @@ function classify(output, code) {
  * @param {number|null|undefined} [code] The command's exit code. Omitted by a
  *   caller that has none; a caller that HAS one must pass it, because a kill is
  *   only legible in the exit code and never in the output.
+ * @param {LoadReading|null} [load] The machine's load, for a kill's evidence
+ *   line. Defaults to reading this machine; pass `null` to suppress the line,
+ *   or a fixed reading to make the output deterministic.
  * @returns {Diagnosis} What the failure was, and whose it was.
  */
-export function diagnoseFailure(output, code) {
-  const verdict = classify(output, code);
+export function diagnoseFailure(output, code, load = machineLoad()) {
+  const verdict = classify(output, code, load);
   return { ...verdict, proves: ATTRIBUTION[verdict.kind] ?? null };
 }

package/all/copy-overwrite/scripts/lisa-gates.mjs

@@ -69,11 +69,30 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import {
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, parse } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { invokedAsScript } from "./lib/invoked-as-script.mjs";
 
+/**
+ * The npm manifest filename, named once.
+ *
+ * Three call sites read one: two resolve a project's own scripts, and the
+ * third walks up from a resolved package entry to find the manifest that owns
+ * it. A literal repeated across all three is a typo away from a lookup that
+ * silently answers "no manifest" — which every one of those readers is written
+ * to treat as an ordinary absence.
+ */
+const PACKAGE_MANIFEST = "package.json";
+
 /** Enforcement levels a moment may carry. */
 export const LEVELS = ["required", "optional", "off"];
 
@@ -3798,7 +3817,7 @@ export function readGates(cwd = process.cwd()) {
  * @returns {Record<string, string>|null} The scripts, or null when unknown.
  */
 export function projectScripts(cwd = process.cwd()) {
-  const path = join(cwd, "package.json");
+  const path = join(cwd, PACKAGE_MANIFEST);
   if (!existsSync(path)) return null;
   try {
     const scripts = JSON.parse(readFileSync(path, "utf8"))?.scripts;
@@ -3852,7 +3871,7 @@ function aliasFor({ declared, registryTask, shippedAs, scripts }) {
  * @returns {Record<string, string>} The scripts block.
  */
 export function readScripts(cwd = process.cwd()) {
-  const path = join(cwd, "package.json");
+  const path = join(cwd, PACKAGE_MANIFEST);
   if (!existsSync(path)) return {};
   let manifest;
   try {
@@ -5994,6 +6013,217 @@ function readPostedNames(source) {
   return [...names];
 }
 
+/* ─── Which Lisa produced this report ───────────────────────────────────── */
+
+/**
+ * The package whose version answers "which Lisa is installed here".
+ *
+ * Named once. `registryVersion()` resolves it and then checks the manifest it
+ * lands on carries this exact name, and the two must not be able to disagree —
+ * a resolution checked against a different literal is a version attached to
+ * whatever package happened to answer.
+ */
+const LISA_PACKAGE = "@codyswann/lisa";
+
+/**
+ * What an unestablished identity field renders as.
+ *
+ * A word rather than an empty string, and never a fallback value. An operator
+ * comparing two gate reports has to be able to tell "this ran a Lisa whose
+ * version could not be resolved" from "this report has no version field at
+ * all", and a blank renders as the second. Guessing renders as neither: the
+ * host application's version in this slot is the specific failure
+ * `registryVersion()` returns null to avoid.
+ */
+export const IDENTITY_UNKNOWN = "unknown";
+
+/**
+ * The shipped enforcement artifacts whose COPY decides a verdict.
+ *
+ * A workflow ref answers "which wrapper ran". It does not answer "which copy
+ * of the checked-in script did that wrapper execute", and when the enforcement
+ * is a file living in the consuming repository those are independent facts —
+ * the second one is the one that produces the verdict. Four live copies of one
+ * enforcement script have been observed at once (a repository's default
+ * branch, a pull request's head, an installed release, and upstream), two of
+ * them sharing a version string, so the identity emitted here is a digest of
+ * the bytes rather than a declared version.
+ */
+const IDENTITY_ARTIFACTS = Object.freeze([
+  "lisa-gates.mjs",
+  "lisa-run-gates.mjs",
+]);
+
+/** The directory the executing copy of this registry lives in. */
+const SCRIPTS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The `@codyswann/lisa` version that owns the resolver behind this run.
+ *
+ * Resolve the package entry from this file, then walk to the owning manifest.
+ * That works in both shipped layouts: inside the installed package and after
+ * Lisa emits this registry into a host project's `scripts/` directory. Reading
+ * a fixed relative path from the emitted copy escapes the package, while
+ * reading `../package.json` confidently reports the host application's version.
+ *
+ * The package-name check stays load-bearing. It makes an unexpected resolution
+ * return null rather than attaching another package's version to this registry.
+ * @returns {string|null} The version, or null when it cannot be established.
+ */
+export function registryVersion() {
+  try {
+    const entry = createRequire(import.meta.url).resolve(LISA_PACKAGE);
+    const root = parse(entry).root;
+    let directory = dirname(entry);
+    while (true) {
+      const manifest = join(directory, PACKAGE_MANIFEST);
+      if (existsSync(manifest)) {
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        if (parsed.name === LISA_PACKAGE) return parsed.version ?? null;
+      }
+      if (directory === root) return null;
+      directory = dirname(directory);
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A content digest of one file, or null when its bytes cannot be read.
+ *
+ * Twelve hex characters, not sixty-four. The question this answers is "did
+ * these two surfaces run the same bytes", which is a comparison between two
+ * printed lines an operator reads side by side; a full digest is not more
+ * comparable and is materially less readable. Null rather than a placeholder
+ * string, so a caller can tell "absent" from a digest that happens to look odd.
+ * @param {string} file Path to the artifact.
+ * @returns {string|null} `sha256:<12 hex>`, or null when unreadable.
+ */
+export function artifactDigest(file) {
+  try {
+    const hex = createHash("sha256").update(readFileSync(file)).digest("hex");
+    return `sha256:${hex.slice(0, 12)}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * WHICH Lisa is running: the surface, the version, the ref, and the bytes.
+ *
+ * ONE COMPUTATION, SEVERAL RENDERINGS. A gate report from CI and a gate report
+ * from a pre-push hook are claims about different code at different versions —
+ * a consumer pins `@codyswann/lisa` for the local hook and calls the reusable
+ * workflow at a floating ref for CI — and neither report used to say which. So
+ * an observation about gate behaviour could not be dated, and a true warning
+ * went stale with nothing in either repository able to notice.
+ *
+ * Every renderer below reads this object rather than resolving a version of
+ * its own, because a second resolution path is a second answer that can
+ * disagree with the first.
+ * @param {object} [options] Inputs.
+ * @param {Record<string,string|undefined>} [options.env] The environment.
+ * @param {string} [options.directory] Where the enforcement scripts live.
+ * @returns {object} The identity record.
+ */
+export function lisaIdentity({
+  env = process.env,
+  directory = SCRIPTS_DIRECTORY,
+} = {}) {
+  return {
+    surface: env.GITHUB_ACTIONS === "true" ? "ci" : "local",
+    registry_version: registryVersion(),
+    workflow_ref: env.GITHUB_WORKFLOW_REF ?? null,
+    workflow_sha: env.GITHUB_WORKFLOW_SHA ?? null,
+    artifacts: Object.fromEntries(
+      IDENTITY_ARTIFACTS.map(name => [
+        name,
+        artifactDigest(join(directory, name)),
+      ])
+    ),
+  };
+}
+
+/**
+ * The workflow half of an identity, rendered for a reader.
+ * @param {object} identity As returned by `lisaIdentity`.
+ * @returns {string} `<ref>@<sha>`, or `unknown` when nothing was established.
+ */
+function identityWorkflow(identity) {
+  if (!identity.workflow_ref) return IDENTITY_UNKNOWN;
+  return `${identity.workflow_ref}@${identity.workflow_sha ?? IDENTITY_UNKNOWN}`;
+}
+
+/**
+ * One operator-readable line naming which Lisa produced a report.
+ *
+ * Cheap enough to appear in ORDINARY output, which is the property that
+ * matters. A stamp only an adjudicator sees helps a reader who is already
+ * suspicious; the observations that go stale unchallenged are the ones nobody
+ * had a reason to check.
+ * @param {object} identity As returned by `lisaIdentity`.
+ * @returns {string} The line, with `unknown` wherever nothing was established.
+ */
+export function formatIdentityLine(identity) {
+  return [
+    `🔖 Lisa identity — surface=${identity.surface}`,
+    `package=${LISA_PACKAGE}@${identity.registry_version ?? IDENTITY_UNKNOWN}`,
+    `workflow=${identityWorkflow(identity)}`,
+    ...Object.entries(identity.artifacts ?? {}).map(
+      ([name, sha]) => `${name}=${sha ?? IDENTITY_UNKNOWN}`
+    ),
+  ].join(" · ");
+}
+
+/**
+ * The same identity as a run-summary block.
+ * @param {object} identity As returned by `lisaIdentity`.
+ * @returns {string} Markdown for `$GITHUB_STEP_SUMMARY`.
+ */
+export function formatIdentityMarkdown(identity) {
+  const version = identity.registry_version ?? IDENTITY_UNKNOWN;
+  const rows = [
+    ["surface", identity.surface],
+    ["package", `${LISA_PACKAGE}@${version}`],
+    ["workflow ref", identity.workflow_ref ?? IDENTITY_UNKNOWN],
+    ["workflow sha", identity.workflow_sha ?? IDENTITY_UNKNOWN],
+    ...Object.entries(identity.artifacts ?? {}).map(([name, sha]) => [
+      name,
+      sha ?? IDENTITY_UNKNOWN,
+    ]),
+  ];
+  return [
+    "### 🔖 Which Lisa ran this",
+    "",
+    "| field | value |",
+    "| --- | --- |",
+    ...rows.map(([field, value]) => `| ${field} | \`${value}\` |`),
+    "",
+    "Every gate report on this run was produced by the Lisa above. A report " +
+      "from the other surface — the local pre-push gate — prints the same " +
+      "fields, so the two can be compared without either repository: equal " +
+      "digests mean the same enforcement bytes ran, and a differing " +
+      "`workflow sha` dates any claim made from this run.",
+  ].join("\n");
+}
+
+/**
+ * Append a block to the run summary, or report that there was nowhere to.
+ * @param {string} markdown The block to append.
+ * @returns {boolean} Whether it was written.
+ */
+function appendRunSummary(markdown) {
+  const target = process.env.GITHUB_STEP_SUMMARY;
+  if (!target) return false;
+  try {
+    appendFileSync(target, `${markdown}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * CLI entry point.
  */
@@ -6003,6 +6233,30 @@ function main() {
     const hit = rest.find(arg => arg.startsWith(`--${name}=`));
     return hit ? hit.slice(name.length + 3) : null;
   };
+  // FIRST, AND BEFORE ANY GATE IS RESOLVED. This command answers "which Lisa
+  // is about to run", so it must be answerable on a project whose declarations
+  // are the thing under suspicion — including one whose config this registry
+  // would refuse. It reads no gates and cannot fail on them.
+  if (command === "identity") {
+    const identity = lisaIdentity();
+    if (rest.includes("--json")) {
+      console.log(JSON.stringify(identity, null, 2));
+      return;
+    }
+    const line = formatIdentityLine(identity);
+    if (flag("format") === "github") {
+      // The annotation AND the run summary, not one of them: an annotation is
+      // what a reader sees beside a failing gate, and the summary is what
+      // survives into a link somebody pastes into a ticket a week later. The
+      // stale claim this exists to refute is always read later.
+      console.log(`::notice title=Lisa identity::${line}`);
+      appendRunSummary(formatIdentityMarkdown(identity));
+      return;
+    }
+    console.log(line);
+    return;
+  }
+
   const { runner, gates, policy, config } = readGates();
   // Read once, here, so every subcommand answers about the same project. The
   // resolver is handed the result rather than reading the disk itself, which
@@ -6399,7 +6653,7 @@ function main() {
   }
 
   throw new Error(
-    "usage: lisa-gates.mjs validate|list|legs|quality-plan|reuse-plan|needs|contexts|retired-contexts|verify-contexts|skip-jobs|audit-config|inventory|unconfigured|seed"
+    "usage: lisa-gates.mjs validate|list|legs|quality-plan|reuse-plan|needs|contexts|retired-contexts|verify-contexts|skip-jobs|audit-config|inventory|unconfigured|identity|seed"
   );
 }
 

package/all/copy-overwrite/scripts/lisa-run-gates.mjs

@@ -49,9 +49,8 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { dirname, join, parse, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { DIAGNOSIS, diagnoseFailure } from "./lib/gate-failure-diagnosis.mjs";
@@ -62,6 +61,8 @@ import {
   configurationProblems,
   declarationsAt,
   digest,
+  formatIdentityLine,
+  lisaIdentity,
   momentsExecutedBy,
   planDigest,
   projectScripts,
@@ -1196,40 +1197,6 @@ const EVIDENCE_STATUS_FOR = Object.freeze({
   [STATE.NOT_RUN]: "unknown",
 });
 
-/**
- * The `@codyswann/lisa` version that owns the resolver behind this run.
- *
- * Resolve the package entry from this file, then walk to the owning manifest.
- * That works in both shipped layouts: inside the installed package and after
- * Lisa emits this runner into a host project's `scripts/` directory. Reading a
- * fixed relative path from the emitted copy escapes the package, while reading
- * `../package.json` confidently reports the host application's version.
- *
- * The package-name check stays load-bearing. It makes an unexpected resolution
- * return null rather than attaching another package's version to this registry.
- * @returns {string|null} The version, or null when it cannot be established.
- */
-function registryVersion() {
-  try {
-    const entry = createRequire(import.meta.url).resolve("@codyswann/lisa");
-    let directory = dirname(entry);
-    const root = parse(directory).root;
-    while (true) {
-      const manifest = join(directory, "package.json");
-      if (existsSync(manifest)) {
-        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
-        if (parsed.name === "@codyswann/lisa") {
-          return parsed.version ?? null;
-        }
-      }
-      if (directory === root) return null;
-      directory = dirname(directory);
-    }
-  } catch {
-    return null;
-  }
-}
-
 /**
  * One revision from git, or null when git cannot answer.
  *
@@ -1316,9 +1283,15 @@ function evidenceContract({ moment, gates, runner, scripts = null }) {
     moment,
     runner: runner ?? null,
     gates_digest: planDigest({ gates, moment, runner, scripts }),
-    registry_version: registryVersion(),
-    workflow_ref: process.env.GITHUB_WORKFLOW_REF ?? null,
-    workflow_sha: process.env.GITHUB_WORKFLOW_SHA ?? null,
+    // SPREAD, not three hand-copied fields. The printed header and this
+    // document have to be the same claim: a reader comparing a pasted gate
+    // line against a stored envelope and finding them disagree learns nothing
+    // except that Lisa has two answers. `surface` and `artifacts` ride along,
+    // and they are the half that says WHICH COPY of the enforcement script
+    // produced the verdict — a fact a workflow ref cannot carry, because the
+    // wrapper's identity and the enforcement's identity are independent when
+    // the enforcement is a file living in the consuming repository.
+    ...lisaIdentity(),
     inputs_digest: inputsDigest(),
   };
 }
@@ -1619,6 +1592,14 @@ function main() {
     return EXIT.RUNNER_FAILED;
   }
 
+  // PRINTED BEFORE ANY GATE RUNS, so it is present whether they pass, fail,
+  // are optional, or never run at all. Every early return below is a report an
+  // operator may quote later, and a quoted report that cannot be dated is the
+  // defect this line exists to close: the local hook runs the version this
+  // project PINNED, while CI runs a floating ref, so two reports about "the
+  // gate" are routinely claims about different code.
+  console.log(formatIdentityLine(lisaIdentity()));
+
   /**
    * Record this run, and refuse to report a verdict we could not record.
    *

package/all/merge/.claude/settings.json

@@ -33,9 +33,7 @@
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
   "permissions": {
-    "deny": [
-      "Read(./.entire/metadata/**)"
-    ]
+    "deny": []
   },
   "plansDirectory": "./plans",
   "hooks": {

package/cdk/merge/.claude/settings.json

@@ -27,7 +27,7 @@
     "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
   },
   "permissions": {
-    "deny": ["Read(./.entire/metadata/**)"]
+    "deny": []
   },
   "plansDirectory": "./plans"
 }

package/dist/cli/doctor-declared-contexts.d.ts

@@ -15,7 +15,7 @@
  * operator to delete a required check; those warn and say what to declare.
  * @module cli/doctor-declared-contexts
  */
-import type { DeclarationDriftReport } from "../core/gate-declaration-drift.js";
+import { type DeclarationDriftReport } from "../core/gate-declaration-drift.js";
 import type { DoctorCheck } from "./doctor.js";
 /**
  * Turn a completed comparison into one operator-readable line.

package/dist/cli/doctor-declared-contexts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor-declared-contexts.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-declared-contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAEV,sBAAsB,EACvB,MAAM,mCAAmC,CAAC;AAM3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuB/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,GAC7B,WAAW,CA8Db;AAsDD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}
+{"version":3,"file":"doctor-declared-contexts.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-declared-contexts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,mCAAmC,CAAC;AAM3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAuB/C;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,sBAAsB,GAC7B,WAAW,CAyDb;AAqFD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,WAAW,CAAC,CAiCtB"}

package/dist/cli/doctor-declared-contexts.js

@@ -1,3 +1,21 @@
+/**
+ * Report where the settings file and the ruleset that enforces it disagree.
+ *
+ * The machine payload under `--json` carries the whole comparison, three states
+ * and all. This is the line an operator reads without asking for JSON, and it
+ * is deliberately the OFFLINE half: doctor is documented as making no network
+ * call, and the template is what a repository's protection is provisioned
+ * from, so a disagreement with it is drift the moment anyone provisions —
+ * whether or not the live ruleset has caught up. The live half runs in
+ * `lisa health`, which already reaches GitHub.
+ *
+ * A `warn` here is not a softer `fail`. Two of the verdicts are contradictions
+ * — the two surfaces state opposite things and one of them is wrong — and
+ * those fail. The other two are silences, and a silence must not send an
+ * operator to delete a required check; those warn and say what to declare.
+ * @module cli/doctor-declared-contexts
+ */
+import { isContradiction, isGap, } from "../core/gate-declaration-drift.js";
 import { readConfig } from "./gate-report-config.js";
 import { readFacadeFacts } from "./gate-report-facade.js";
 import { buildDeclarationDrift } from "./gate-report-joins.js";
@@ -41,8 +59,9 @@ export function declaredContextsCheck(report) {
             detail: `${named(retired.map(entry => entry.context))} can never report: Lisa renamed the job that used to post ${retired.length === 1 ? "it" : "them"}. ${retired[0]?.detail ?? ""} Run \`lisa health\` to sweep the LIVE rulesets, including any this repository hand-made, for the same name.`,
         };
     }
-    const contradictions = report.entries.filter(entry => entry.verdict === "declared-not-enforced" ||
-        entry.verdict === "enforced-declared-off");
+    // Asked of the comparator rather than re-listed here — see the note on the
+    // same call in `health/declared-checks-inspection`.
+    const contradictions = report.entries.filter(entry => isContradiction(entry.verdict));
     if (contradictions.length > 0) {
         return {
             name: NAME,
@@ -50,9 +69,7 @@ export function declaredContextsCheck(report) {
             detail: `The settings file and the ruleset template say opposite things about ${named(contradictions.map(entry => entry.context))}. ${contradictions[0]?.detail ?? ""} Fix whichever is wrong; nothing here proposes removing a check.`,
         };
     }
-    const undeclared = report.entries.filter(entry => entry.verdict === "enforced-undeclared");
-    const optional = report.entries.filter(entry => entry.verdict === "enforced-declared-optional");
-    if (undeclared.length === 0 && optional.length === 0) {
+    if (!report.entries.some(entry => isGap(entry.verdict))) {
         return {
             name: NAME,
             status: "ok",
@@ -69,14 +86,38 @@ export function declaredContextsCheck(report) {
         // whose gate IS declared — which is untrue and sends the operator looking
         // for a declaration that is already there.
         detail: [
-            undeclaredClause(undeclared),
-            optionalClause(optional),
+            undeclaredClause(entriesWith(report, "enforced-undeclared")),
+            optionalClause(entriesWith(report, "enforced-declared-optional")),
+            awaitedClause(entriesWith(report, "enforced-awaited-elsewhere")),
             "Do NOT remove the required check to make this line go away.",
         ]
             .filter(clause => clause.length > 0)
             .join(" "),
     };
 }
+/**
+ * The entries carrying one verdict.
+ * @param report - The comparison
+ * @param verdict - The verdict to collect
+ * @returns The matching entries
+ */
+function entriesWith(report, verdict) {
+    return report.entries.filter(entry => entry.verdict === verdict);
+}
+/**
+ * The clause for contexts a gate's declaration awaits a different signal for.
+ * @param entries - The awaited-elsewhere entries
+ * @returns One sentence, or an empty string
+ */
+function awaitedClause(entries) {
+    if (entries.length === 0)
+        return "";
+    const gates = gateIdsOf(entries);
+    const awaited = named([
+        ...new Set(entries.flatMap(entry => entry.awaitedInstead === null ? [] : [entry.awaitedInstead])),
+    ]);
+    return `The template also requires ${named(entries.map(entry => entry.context))} while the settings file declares ${gates} with an \`await:\` at pull-request, which promises ${awaited} as the merge condition instead. An awaited gate posts no job of its own, so unless a hand-written job posts these exact names they will never report and every pull request waits on them.`;
+}
 /**
  * The clause for contexts whose gate the settings file never mentions.
  * @param entries - The undeclared entries