@codyswann/lisa 3.34.0 → 3.35.0

package/all/copy-overwrite/scripts/lisa-lint-staged-preflight.mjs

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+// This file is managed by Lisa and IS replaced on each `lisa` run.
+// Do not edit directly — durable changes belong upstream in Lisa.
+
+/**
+ * lisa-lint-staged-preflight — prove every tool lint-staged is about to run can
+ * actually be started, before lint-staged gets the chance to swallow the answer.
+ *
+ * Usage:
+ *   node scripts/lisa-lint-staged-preflight.mjs --config .lintstagedrc.json
+ *   node scripts/lisa-lint-staged-preflight.mjs --config=.lintstagedrc.json
+ *
+ * ## Why this exists
+ *
+ * `lint-staged` reports **exit 0** when a task's executable cannot be spawned
+ * with `ENOEXEC`, while printing `[FAILED] spawn ENOEXEC` to the terminal. The
+ * asymmetry is the whole problem, and it is what defeats the intuition that a
+ * broken tool would get noticed. Measured with one harness, three tasks,
+ * everything else held constant:
+ *
+ * | task                                            | 16.2.7 | 16.4.0 | 17.3.0 |
+ * | ----------------------------------------------- | ------ | ------ | ------ |
+ * | script exits 1 (ordinary failure)               | 1      | 1      | 1      |
+ * | executable absent entirely (`ENOENT`)           | 1      | 1      | 1      |
+ * | present, `chmod +x`, not executable (`ENOEXEC`) | 1      | **0**  | **0**  |
+ *
+ * A *missing* tool is caught. A tool that is present but unrunnable is not.
+ *
+ * That is precisely the state some published tools leave behind. A package
+ * whose real binary is materialized during `postinstall` installs a
+ * shebang-less placeholder shim first; the shim is written to fail loudly and
+ * explain itself, and it would, because it `exit 1`s. lint-staged spawns
+ * without a shell, so no shebang plus no shell means the kernel returns
+ * `ENOEXEC` before the shim's own `exit 1` can ever run. Skip `postinstall` —
+ * which is a route agents take routinely — and the task runs, reports nothing,
+ * and blocks nothing, while the commit proceeds.
+ *
+ * ## Why hardening the hook could not fix it
+ *
+ * Worth stating, because it is the obvious first response. The hook already
+ * captures lint-staged's status and exits on it. No exit-code check can catch
+ * a process that reports `0` for work it did not do. The answer has to arrive
+ * *before* the handoff, from something that spawns the tools itself.
+ *
+ * ## What "invocable" means here, and why it is measured rather than inferred
+ *
+ * This guard does not read the file's first bytes looking for a shebang or an
+ * object-file magic number and reason about what the kernel would do with them.
+ * It spawns each executable, shell-less, exactly as lint-staged will, and
+ * watches for the `spawn` event. `ENOEXEC`, `ENOENT` and `EACCES` all arrive as
+ * an `error` event instead, which is the signal. The probe passes when — and
+ * only when — the operating system really started the process.
+ *
+ * `--version` is the probe argument because every tool Lisa ships in
+ * `.lintstagedrc.json` answers it instantly. The exit code is deliberately
+ * ignored: a tool that rejects `--version` still *started*, which is the entire
+ * question. A tool that hangs is also a pass for the same reason — it started —
+ * so the probe kills it and moves on.
+ *
+ * ## Silence is not the success signal
+ *
+ * The defect being fixed is a control reporting success for work it no longer
+ * performs, so this file refuses to be a second instance of it:
+ *
+ * - It prints one line per executable it probed and a count. A run that proved
+ *   nothing cannot look like a run that proved everything.
+ * - A config it cannot read, cannot parse, or whose shape it does not
+ *   understand is a FAILURE, never a quiet pass.
+ * - A config that declares no tasks is a FAILURE: lint-staged would prove
+ *   nothing, and "nothing to check" is exactly the report this guard exists to
+ *   stop trusting.
+ * - Extracting zero executables from a config that has tasks is a FAILURE.
+ * - Executable-name extraction that disagrees with lint-staged's own
+ *   tokenization can only produce a name that fails to spawn, which this guard
+ *   reports loudly. It has no path to a silent pass.
+ * @module scripts/lisa-lint-staged-preflight
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+/** Default config path, matching what the shipped pre-commit hook passes. */
+const DEFAULT_CONFIG = ".lintstagedrc.json";
+
+/** Argument handed to each probed executable. */
+const PROBE_ARGS = Object.freeze(["--version"]);
+
+/**
+ * How long a probe waits before concluding the process really did start.
+ *
+ * Only reached by a tool that spawns and then neither exits nor is killed.
+ * Since spawning is the whole question, a timeout is a PASS.
+ */
+const PROBE_TIMEOUT_MS = 15_000;
+
+/**
+ * The config path named on the command line.
+ *
+ * Accepts `--config X` and `--config=X` because the hook and a human invoking
+ * this by hand write it both ways.
+ * @param {string[]} argv - Arguments after the script name.
+ * @returns {string} Config path, relative or absolute.
+ */
+export const configPathFrom = argv => {
+  const inline = argv.find(arg => arg.startsWith("--config="));
+  if (inline !== undefined) return inline.slice("--config=".length);
+  const flagAt = argv.indexOf("--config");
+  if (flagAt >= 0 && argv[flagAt + 1] !== undefined) return argv[flagAt + 1];
+  return DEFAULT_CONFIG;
+};
+
+/**
+ * The executable a lint-staged task string spawns.
+ *
+ * lint-staged splits the task with `string-argv` and spawns element zero, so
+ * this reproduces that for element zero only: quoted runs are unwrapped, and
+ * the token ends at the first unquoted whitespace. A disagreement with
+ * `string-argv` on an exotic task string yields a name that will not spawn,
+ * which this guard reports — never a name it silently skips.
+ * @param {string} command - A lint-staged task string.
+ * @returns {string} The executable name, or "" when the task is blank.
+ */
+export const executableOf = command => {
+  let token = "";
+  let quote = "";
+  for (const character of command) {
+    if (quote !== "") {
+      if (character === quote) quote = "";
+      else token += character;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (/\s/u.test(character)) {
+      if (token !== "") break;
+    } else {
+      token += character;
+    }
+  }
+  return token;
+};
+
+/**
+ * Every task string a lint-staged JSON config declares.
+ * @param {unknown} config - Parsed config contents.
+ * @returns {{ tasks: string[] } | { problem: string }} Tasks, or why not.
+ */
+export const tasksOf = config => {
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    return { problem: "the config is not a JSON object of glob → task(s)" };
+  }
+  const tasks = [];
+  for (const [glob, value] of Object.entries(config)) {
+    if (typeof value === "string") {
+      tasks.push(value);
+    } else if (
+      Array.isArray(value) &&
+      value.every(v => typeof v === "string")
+    ) {
+      tasks.push(...value);
+    } else {
+      return {
+        problem: `the entry for "${glob}" is neither a task string nor an array of them`,
+      };
+    }
+  }
+  return { tasks };
+};
+
+/**
+ * The environment a probe runs in: PATH augmented the way lint-staged's own
+ * spawner augments it, so a locally installed tool resolves identically.
+ *
+ * `node_modules/.bin` is prepended for the working directory and every ancestor
+ * of it, then the directory holding the running Node binary.
+ * @param {string} cwd - Directory the probe runs in.
+ * @returns {NodeJS.ProcessEnv} Environment for the probe.
+ */
+export const probeEnv = cwd => {
+  const binDirectories = [];
+  let current = cwd;
+  let previous = "";
+  while (current !== previous) {
+    binDirectories.push(path.resolve(current, "node_modules", ".bin"));
+    previous = current;
+    current = path.dirname(current);
+  }
+  binDirectories.push(path.dirname(process.execPath));
+
+  const key =
+    Object.keys(process.env).find(name => /^path$/iu.test(name)) ?? "PATH";
+  const existing = process.env[key] ?? "";
+  return {
+    ...process.env,
+    [key]: [
+      ...binDirectories,
+      ...(existing === "" ? [] : existing.split(path.delimiter)),
+    ].join(path.delimiter),
+  };
+};
+
+/**
+ * Start one executable and report whether the operating system started it.
+ *
+ * Shell-less on POSIX, matching how lint-staged spawns and therefore matching
+ * the `ENOEXEC` this guard exists to catch. On win32 the shell is used because
+ * that is how `.cmd` shims are invoked there; `ENOEXEC` in the sense meant here
+ * is a POSIX `execve` outcome and has no win32 counterpart.
+ * @param {string} executable - Name or path to start.
+ * @param {string} cwd - Directory to start it in.
+ * @param {NodeJS.ProcessEnv} env - Environment to start it with.
+ * @returns {Promise<{ executable: string, started: boolean, code?: string, detail?: string }>} Probe outcome.
+ */
+export const probe = (executable, cwd, env) =>
+  new Promise(resolve => {
+    let settled = false;
+    /**
+     * Resolve once, ignoring any later event from the same child.
+     * @param {{ executable: string, started: boolean, code?: string, detail?: string }} outcome - What happened.
+     * @returns {void}
+     */
+    const settle = outcome => {
+      if (settled) return;
+      settled = true;
+      resolve(outcome);
+    };
+
+    let child;
+    try {
+      child = spawn(executable, [...PROBE_ARGS], {
+        cwd,
+        env,
+        stdio: "ignore",
+        shell: process.platform === "win32",
+        timeout: PROBE_TIMEOUT_MS,
+      });
+    } catch (error) {
+      settle({
+        executable,
+        started: false,
+        code: /** @type {NodeJS.ErrnoException} */ (error).code ?? "FAILED",
+        detail: /** @type {Error} */ (error).message,
+      });
+      return;
+    }
+
+    child.on("error", error => {
+      settle({
+        executable,
+        started: false,
+        code: /** @type {NodeJS.ErrnoException} */ (error).code ?? "FAILED",
+        detail: error.message,
+      });
+    });
+    child.on("spawn", () => {
+      child.kill();
+      settle({ executable, started: true });
+    });
+  });
+
+/**
+ * Refuse to continue, saying what could not be established.
+ * @param {string} reason - Operator-readable reason.
+ * @param {string[]} [remedy] - Lines telling the reader what to do.
+ * @returns {number} Exit code 1.
+ */
+const refuse = (reason, remedy = []) => {
+  process.stderr.write(`\n❌ lint-staged preflight: ${reason}\n`);
+  for (const line of remedy) process.stderr.write(`   ${line}\n`);
+  process.stderr.write(
+    "\n   Nothing was proved about the tools lint-staged would run, so the\n" +
+      "   commit is blocked rather than allowed to look checked.\n\n"
+  );
+  return 1;
+};
+
+/**
+ * Run the preflight.
+ * @param {string[]} argv - Arguments after the script name.
+ * @param {string} cwd - Directory the probes run in.
+ * @returns {Promise<number>} Process exit code.
+ */
+export const run = async (argv, cwd) => {
+  const configPath = configPathFrom(argv);
+  const absolute = path.resolve(cwd, configPath);
+  if (!existsSync(absolute)) {
+    return refuse(`no config at ${configPath}`, [
+      "lint-staged is about to be handed this path and will fail too.",
+      "Restore the file, or point the pre-commit hook at the right one.",
+    ]);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(absolute, "utf8"));
+  } catch (error) {
+    return refuse(`${configPath} is not valid JSON`, [
+      /** @type {Error} */ (error).message,
+    ]);
+  }
+
+  const extracted = tasksOf(parsed);
+  if ("problem" in extracted) {
+    return refuse(`${configPath} has a shape this guard cannot read`, [
+      extracted.problem,
+      "This guard reads JSON configs only, which is what Lisa ships.",
+    ]);
+  }
+  if (extracted.tasks.length === 0) {
+    return refuse(`${configPath} declares no tasks`, [
+      "lint-staged would run nothing and report success.",
+      "Add the tasks back, or stop running lint-staged from the hook.",
+    ]);
+  }
+
+  const executables = [...new Set(extracted.tasks.map(executableOf))].filter(
+    name => name !== ""
+  );
+  if (executables.length === 0) {
+    return refuse(
+      `no executable name could be read from the ${extracted.tasks.length} task(s) in ${configPath}`
+    );
+  }
+
+  process.stdout.write(
+    `🔎 lint-staged preflight: probing ${executables.length} tool(s) named by ${configPath}\n`
+  );
+  const env = probeEnv(cwd);
+  const outcomes = await Promise.all(
+    executables.map(executable => probe(executable, cwd, env))
+  );
+
+  for (const outcome of outcomes) {
+    process.stdout.write(
+      outcome.started
+        ? `   ✅ ${outcome.executable}\n`
+        : `   ❌ ${outcome.executable} — could not be started (${outcome.code})\n`
+    );
+  }
+
+  const broken = outcomes.filter(outcome => !outcome.started);
+  if (broken.length > 0) {
+    return refuse(
+      `${broken.length} of ${outcomes.length} tool(s) cannot be started`,
+      [
+        ...broken.map(
+          outcome => `${outcome.executable}: ${outcome.detail ?? outcome.code}`
+        ),
+        "",
+        "lint-staged spawns these without a shell. A tool that is present but",
+        "not executable makes it print [FAILED] and still exit 0, so the scan",
+        "would run, report nothing, and block nothing.",
+        "",
+        "Most often this is an install that skipped postinstall scripts, which",
+        "leaves a placeholder where the real binary belongs. Reinstall with",
+        "scripts enabled (for example `bun install --force`) and try again.",
+      ]
+    );
+  }
+
+  process.stdout.write(
+    `   ${outcomes.length} tool(s) verified runnable; handing off to lint-staged.\n`
+  );
+  return 0;
+};
+
+/**
+ * True when `moduleUrl` names the module node was asked to run.
+ *
+ * Both sides are realpath'd: `import.meta.url` is the real path while `argv[1]`
+ * is whatever the caller typed, so through a symlinked checkout, a git
+ * worktree, or a `/tmp` path on macOS a raw comparison is false and the body
+ * never runs — for a guard, exiting 0 having proved nothing.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`.
+ * @param {string} [argv1] - Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the CLI body should run.
+ */
+export const invokedAsScript = (moduleUrl, argv1 = process.argv[1]) => {
+  if (argv1 === undefined || argv1 === "") return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+};
+
+if (invokedAsScript(import.meta.url)) {
+  run(process.argv.slice(2), process.cwd())
+    .then(code => {
+      process.exitCode = code;
+    })
+    .catch(error => {
+      process.stderr.write(
+        `\n❌ lint-staged preflight crashed: ${/** @type {Error} */ (error).message}\n` +
+          "   Nothing was proved. The commit is blocked.\n\n"
+      );
+      process.exitCode = 1;
+    });
+}

package/dist/cli/doctor-traceability-gate.d.ts

@@ -0,0 +1,39 @@
+import type { DoctorCheck } from "./doctor.js";
+/** The gate id as the registry declares it. */
+export declare const GATE_ID = "traceability";
+/** The moment the registry permits for this gate. */
+export declare const GATE_MOMENT = "pull-request";
+/** What an undeclared project is repaired to. */
+export declare const GATE_LEVEL = "required";
+/** The subset of `.lisa.config.json` this check reads. */
+interface GateConfig {
+    readonly gates?: Record<string, unknown>;
+}
+/**
+ * Whether a config declares the traceability gate at all.
+ *
+ * Declared-as-`off` counts as declared. A repair that overwrote an explicit
+ * opt-out would make the gate un-declinable, which is worse than the hole it
+ * closes: the project could never express a considered exemption, and the next
+ * `lisa doctor` would silently undo a deliberate decision.
+ * @param config - Parsed `.lisa.config.json`
+ * @returns True when the project has already made a decision about this gate.
+ */
+export declare function declaresTraceability(config: GateConfig): boolean;
+/**
+ * Add the gate at its registry-legal moment, without touching anything else.
+ *
+ * Returns a new object rather than mutating, so a caller that decides not to
+ * write still holds the original.
+ * @param config - Parsed `.lisa.config.json`
+ * @returns A copy declaring the gate
+ */
+export declare function withTraceabilityGate<T extends GateConfig>(config: T): T;
+/**
+ * Report — and repair — an undeclared traceability gate.
+ * @param targetPath - Project path to inspect and repair
+ * @returns The doctor check result
+ */
+export declare function checkTraceabilityGate(targetPath: string): Promise<DoctorCheck>;
+export {};
+//# sourceMappingURL=doctor-traceability-gate.d.ts.map

package/dist/cli/doctor-traceability-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-traceability-gate.d.ts","sourceRoot":"","sources":["../../src/cli/doctor-traceability-gate.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAsB/C,+CAA+C;AAC/C,eAAO,MAAM,OAAO,iBAAiB,CAAC;AAEtC,qDAAqD;AACrD,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAE1C,iDAAiD;AACjD,eAAO,MAAM,UAAU,aAAa,CAAC;AAErC,0DAA0D;AAC1D,UAAU,UAAU;IAClB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAQvE;AA8BD;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAoDtB"}

package/dist/cli/doctor-traceability-gate.js

@@ -0,0 +1,164 @@
+/**
+ * Ensure a project actually declares the Work-Item Traceability gate.
+ *
+ * Every upstream layer already sanctions it — the gate registry declares it at
+ * `pull-request`, the TypeScript ruleset template names the context as
+ * required, and the promotion ledger grandfathers it. Lisa's own repository
+ * enforces it. Measured 2026-08-18, **no consumer did**: `traceability` was
+ * absent from all five projects' `.lisa.config.json`.
+ *
+ * WHAT AN UNDECLARED GATE COSTS, RESTATED AFTER #2680. An earlier draft of this
+ * check said an undeclared gate meant "the job never ran at all". That was true
+ * when the job's `if:` keyed on `skip_jobs` and ignored the config. Since #2680
+ * it is false: the job runs on every pull request, and with the gate undeclared
+ * (`configured=false`) the built-in validation step still runs and still reds.
+ *
+ * The real cost is narrower and easier to miss. `contextsFor` filters on
+ * `gate.level === "required"`, so an undeclared gate emits no required status
+ * context — the job reds and **merges anyway**. Declaring it is what converts an
+ * ignorable red into a blocking one. Do not restore the stronger claim without
+ * re-measuring: it was wrong once already, and a repair that overstates what it
+ * fixes is the same defect class as a check that reports work it never did.
+ *
+ * Two independent layers decide whether a missing trailer blocks, and
+ * conflating them is why this went unseen:
+ *
+ *   1. the gate's level in `.lisa.config.json` — does the JOB run and fail?
+ *   2. branch-protection required contexts — does a failing job BLOCK a merge?
+ *
+ * This check repairs layer 1, which is the one that produces any signal at all,
+ * and only REPORTS layer 2. Promoting a context is governed by its own control
+ * (`check-required-check-promotions.mjs`), and mutating live branch protection
+ * belongs to `scripts/lisa-github-rulesets.sh`.
+ * @module cli/doctor-traceability-gate
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+const CHECK_NAME = "Work-Item Traceability declared?";
+/**
+ * What this check can and cannot see about layer 2.
+ *
+ * `lisa doctor` runs offline, so it never observes live branch protection. A
+ * declared gate therefore proves the job will FAIL, never that the failure will
+ * BLOCK — `contextsFor` only emits the context, and the ruleset has to require
+ * it. Saying nothing here would let a green doctor read as "traceability is
+ * enforced" when the context may not be required at all, which is the exact
+ * conflation #2677 was filed about. So both branches say it, and both name
+ * where layer 2 IS observed rather than leaving the reader to find it.
+ */
+const LAYER_TWO_NOTE = `Whether a failure BLOCKS a merge is a separate layer that \`lisa doctor\` ` +
+    `cannot see: it runs offline and never reads live branch protection. Check ` +
+    `it with \`lisa health\` (the \`github.rulesets\` finding names any context ` +
+    `that "runs without blocking"), and apply the ruleset with ` +
+    `scripts/lisa-github-rulesets.sh if the context is missing.`;
+/** The gate id as the registry declares it. */
+export const GATE_ID = "traceability";
+/** The moment the registry permits for this gate. */
+export const GATE_MOMENT = "pull-request";
+/** What an undeclared project is repaired to. */
+export const GATE_LEVEL = "required";
+/**
+ * Whether a config declares the traceability gate at all.
+ *
+ * Declared-as-`off` counts as declared. A repair that overwrote an explicit
+ * opt-out would make the gate un-declinable, which is worse than the hole it
+ * closes: the project could never express a considered exemption, and the next
+ * `lisa doctor` would silently undo a deliberate decision.
+ * @param config - Parsed `.lisa.config.json`
+ * @returns True when the project has already made a decision about this gate.
+ */
+export function declaresTraceability(config) {
+    return Object.hasOwn(config.gates ?? {}, GATE_ID);
+}
+/**
+ * Add the gate at its registry-legal moment, without touching anything else.
+ *
+ * Returns a new object rather than mutating, so a caller that decides not to
+ * write still holds the original.
+ * @param config - Parsed `.lisa.config.json`
+ * @returns A copy declaring the gate
+ */
+export function withTraceabilityGate(config) {
+    return {
+        ...config,
+        gates: {
+            ...(config.gates ?? {}),
+            [GATE_ID]: { [GATE_MOMENT]: GATE_LEVEL },
+        },
+    };
+}
+/**
+ * Read the config file, or `null` when there is none.
+ * @param configPath - Absolute path to `.lisa.config.json`
+ * @returns File contents, or `null` when absent or unreadable
+ */
+async function readConfigText(configPath) {
+    try {
+        return await readFile(configPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the config, reporting the failure rather than throwing.
+ * @param raw - File contents
+ * @returns The parsed config, or the parse error's message
+ */
+function parseConfig(raw) {
+    try {
+        return { config: JSON.parse(raw) };
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/**
+ * Report — and repair — an undeclared traceability gate.
+ * @param targetPath - Project path to inspect and repair
+ * @returns The doctor check result
+ */
+export async function checkTraceabilityGate(targetPath) {
+    const configPath = path.join(targetPath, ".lisa.config.json");
+    const raw = await readConfigText(configPath);
+    if (raw === null) {
+        // Not a Lisa project, or not one yet. Nothing to declare and nothing to
+        // repair — reporting a gap here would fire on every unrelated directory.
+        return {
+            name: CHECK_NAME,
+            status: "ok",
+            detail: "no .lisa.config.json — nothing to declare",
+        };
+    }
+    const parsed = parseConfig(raw);
+    if ("error" in parsed) {
+        return {
+            name: CHECK_NAME,
+            status: "warn",
+            detail: `.lisa.config.json is not valid JSON, so the gate could not be ` +
+                `checked: ${parsed.error}`,
+        };
+    }
+    const config = parsed.config;
+    if (declaresTraceability(config)) {
+        return {
+            name: CHECK_NAME,
+            status: "ok",
+            detail: `gates.${GATE_ID} is declared — left as the project set it. ${LAYER_TWO_NOTE}`,
+        };
+    }
+    // Two-space indent and a trailing newline: the convention every Lisa-written
+    // JSON in a host project uses, so the repair does not show up as a whole-file
+    // reformat in the diff that carries it.
+    await writeFile(configPath, `${JSON.stringify(withTraceabilityGate(config), null, 2)}\n`, "utf-8");
+    return {
+        name: CHECK_NAME,
+        status: "warn",
+        detail: `gates.${GATE_ID} was undeclared, so a missing Work-Item trailer reddened ` +
+            `the check and merged anyway — an undeclared gate emits no required ` +
+            `status context. ADDED as {"${GATE_MOMENT}": "${GATE_LEVEL}"} — commit ` +
+            `it. Declare it as "off" instead if this project is deliberately opting ` +
+            `out; that decision is preserved. ${LAYER_TWO_NOTE}`,
+    };
+}
+//# sourceMappingURL=doctor-traceability-gate.js.map

package/dist/cli/doctor-traceability-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-traceability-gate.js","sourceRoot":"","sources":["../../src/cli/doctor-traceability-gate.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAoBnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,mDAAmD;AACnD,KAAK,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAO3C,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;CACjD;AAaD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,EAChD,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,WAAW,CAAC,CAyBtB;AA4MD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,aAAa,EACtB,YAAY,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAC7C,OAAO,CAAC,YAAY,CAAC,CAsEvB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAqBnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,mDAAmD;AACnD,KAAK,YAAY,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAO3C,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,KAAK,CAAC;IACxB,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;CACjD;AAaD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,EAChD,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,WAAW,CAAC,CAyBtB;AA4MD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,aAAa,EACtB,YAAY,GAAE,OAAO,CAAC,kBAAkB,CAAM,GAC7C,OAAO,CAAC,YAAY,CAAC,CA4EvB"}

package/dist/cli/doctor.js

@@ -19,6 +19,7 @@ import { checkRepositoryReadiness } from "./doctor-readiness.js";
 import { checkReusableWorkflowRefs } from "./doctor-reusable-workflow-refs.js";
 import { checkWorkerEpoch } from "./doctor-worker-epoch.js";
 import { checkSerializeLegsContract } from "./doctor-serialize-legs-contract.js";
+import { checkTraceabilityGate } from "./doctor-traceability-gate.js";
 import { checkWorktreeHygiene } from "./doctor-worktree-hygiene.js";
 import { checkWorktreeWorkAtRisk } from "./doctor-worktree-work-at-risk.js";
 import { STARTERS } from "./starters.js";
@@ -262,6 +263,12 @@ export async function runDoctor(targetPath, options, dependencies = {}) {
         await checkApplyFreshness(resolvedTarget),
         checkYamlRuntime(),
         await checkProjectConfig(resolvedTarget),
+        // Immediately after the config check, because it repairs the same file and
+        // an operator reading the output wants both config findings together. It
+        // is mutating: an undeclared gate is ADDED rather than merely reported,
+        // since an undeclared gate means the job never runs and there is no signal
+        // to notice (CodySwannGT/lisa#2677).
+        await checkTraceabilityGate(resolvedTarget),
         await checkKaneProvider(resolvedTarget, deps),
         await checkSonarProvider(resolvedTarget, deps),
         await checkLegacyMonitorThresholds(resolvedTarget),