@codyswann/lisa 3.16.0 → 3.17.0

package/package.json

@@ -37,17 +37,21 @@
     "check:upstream-evidence-manifest": "node scripts/generate-upstream-evidence-manifest.mjs --check",
     "build:lisa-owned-hash-ledger": "node scripts/generate-lisa-owned-hash-ledger.mjs",
     "check:lisa-owned-hash-ledger": "node scripts/generate-lisa-owned-hash-ledger.mjs --check",
+    "check:artifacts": "status=0; bun run check:upstream-evidence-manifest || status=1; bun run check:lisa-owned-hash-ledger || status=1; exit $status",
     "refresh:upstream-public-commits": "node scripts/generate-upstream-evidence-manifest.mjs --refresh-public-commits",
     "check:rules-pairing": "bash scripts/check-rules-pairing.sh",
     "check:workflow-inputs": "node scripts/detect-stale-workflow-inputs.mjs --project . --project typescript/create-only --project rails/create-only --json",
     "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
     "check:duplicate-versions": "node scripts/check-duplicate-versions.mjs",
     "check:required-check-promotions": "node scripts/check-required-check-promotions.mjs",
+    "check:work-item": "node scripts/lisa-work-item.mjs validate-pr",
+    "check:thresholds": "node plugins/src/base/hooks/threshold-ratchet.mjs --base HEAD^",
     "verify:health-contract": "bun run build:dist && node scripts/verify-health-contract-built.mjs",
     "verify:health-deterministic": "bun run build:dist && node scripts/verify-health-deterministic-built.mjs",
     "verify:learner-frontmatter-built": "bun run build:dist && node scripts/verify-learner-frontmatter-built.mjs",
     "verify:health-agentic": "bun run build:dist && node scripts/verify-health-agentic-built.mjs",
-    "verify:health-consumer": "bun run build:dist && node scripts/verify-health-consumer-built.mjs"
+    "verify:health-consumer": "bun run build:dist && node scripts/verify-health-consumer-built.mjs",
+    "lint:staged": "lint-staged"
   },
   "engines": {
     "npm": "please-use-bun",
@@ -125,7 +129,7 @@
     }
   },
   "name": "@codyswann/lisa",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -193,6 +193,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/secrets-preflight.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

package/plugins/lisa/.codex-plugin/hooks.json

@@ -114,6 +114,15 @@
             "command": "${PLUGIN_ROOT}/hooks/setup-jira-cli.sh"
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/secrets-preflight.sh"
+          }
+        ]
       }
     ],
     "SubagentStart": [

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-doctor/SKILL.md

@@ -422,14 +422,93 @@ The verdict ladder is:
 - `READY_WITH_WARNINGS` — no `FAIL`, but one or more `WARN`.
 - `NOT_READY` — one or more `FAIL`.
 
+## Gate configuration
+
+```sh
+node scripts/lisa-gates.mjs validate                    # shape + unknown gate ids
+node scripts/lisa-gates.mjs list --moment=pull-request
+node scripts/lisa-gates.mjs contexts                    # branch-protection contexts
+```
+
+A gate is a **property** — *credential leakage* — not a tool. `gitleaks` is one way to prove
+that property, and which way is the project's choice: each gate names a task in the project's own
+runner, so swapping the tool changes one line of project config and nothing in Lisa.
+
+`validate` refuses an unknown gate id rather than ignoring it. A misspelled `credential-leakge`
+would otherwise read as an enabled guarantee and run nothing at all — the same silent-hole shape
+as a skipped required check. Gates a project invents carry an `x-` prefix, which Lisa runs without
+pretending to understand.
+
+`contexts` is the value that replaces a hand-transcribed branch-protection list. It is scoped to
+one environment: a gate required before a production deploy is **not** thereby a merge blocker on a
+pull request, and collapsing the two would promote every deploy-time gate into branch protection.
+
+When reconciling a ruleset against it, pass `--previous=` with any label retired in the last
+release. Downstream repositories call the shared workflow unpinned, so a renamed job reaches every
+repository before any of them has reconciled — and a required context that never reports leaves
+pull requests waiting indefinitely. The fastest way out of that is deleting the requirement, which
+is how a rename ends up removing a guarantee. Emitting both labels for one release avoids it.
+
+### Reconciling against the live ruleset
+
+`contexts` says what the repository *should* require. Reconciliation asks whether GitHub agrees:
+
+```sh
+node scripts/lisa-reconcile-policy.mjs --dry-run              # read-only: what would change
+node scripts/lisa-reconcile-policy.mjs --on-drift=report      # report, write nothing
+node scripts/lisa-reconcile-policy.mjs --on-drift=block       # exit 1 on any drift, for CI
+node scripts/lisa-reconcile-policy.mjs                        # honors policy.on_drift
+node scripts/lisa-reconcile-policy.mjs --previous="🧽 Lint"   # keep a renamed context required
+node scripts/lisa-reconcile-policy.mjs --prune                # also remove EXTRA contexts
+```
+
+It reads the live ruleset and repository settings through `gh`, compares them against the derived
+contexts and the `policy` block, and reports three sets: **MISSING** (declared, not live), **EXTRA**
+(live, not declared), **MATCHED**. `--dry-run` never writes, whatever `policy.on_drift` says.
+
+Three behaviors need an operator to understand them before reading a report.
+
+**1. `UNPROVEN` is not a pass.** If `gh` is missing, unauthenticated, or the API errors — a private
+repository on a plan without rulesets answers `403` — the verdict is `UNPROVEN` and the exit code is
+`2`. It is neither of its neighbours, and the distinction is the same one the secrets preflight
+draws with `unreachable`: reported as clean it is a vacuous green, clean precisely because nothing
+was learned; reported as drift it sends someone to fix a ruleset that may be perfectly correct. The
+drift sets come back `null` rather than empty, because empty is what a clean repository looks like.
+`on_drift` does not soften this — not even `report` — because `on_drift` decides what to do about a
+drift that was *measured*, and here nothing was. Map it to doctor's `WARN`/`FAIL` on the same rule
+as any other unavailable check surface: never `PASS`.
+
+**2. An `EXTRA` context is reported, never removed.** Lisa does not own the whole required list.
+`SonarCloud Code Analysis`, `GitGuardian Security Checks`, and `CodeRabbit` are posted by external
+apps that no gates block declares, so `contextsFor` cannot derive them and every one of them is
+EXTRA by construction. Under `repair` the script therefore ADDS what is missing and leaves what is
+extra alone, naming each one. Removing them requires `--prune`, and the right way to clear the list
+is one at a time: each EXTRA context is either an app to keep, or a gate that belongs in
+`.lisa.config.json` — decide which before pruning anything.
+
+**3. Keep both names during a rename.** `--previous=<old label>` requires the old and the new
+context simultaneously for one release. Without it the reconciliation reports the still-live old
+context as EXTRA (and `--prune` would delete it) while in-flight pull requests wait on a context
+that will never report again.
+
+Repair writes exactly two things: required contexts on a ruleset, and repository settings. Policy
+carried by the *shape* of a rule — linear history, signed commits, force-push and deletion
+protection, conversation resolution — is compared here and repaired by
+`scripts/lisa-github-rulesets.sh`, which owns rule construction; the reconciler reports those and
+names that script rather than reshaping rules it did not build. When more than one ruleset requires
+status checks it refuses to guess which owns the derived contexts and asks for `--ruleset=<name>`,
+because writing to the wrong one enforces a context under a different ref-name condition.
+
 ## Secrets configuration
 
 Run the secrets health checks through the skill that owns the contract, rather than reimplementing
 any part of it here:
 
 ```sh
-node .claude/skills/lisa-secrets-access/scripts/validate-config.mjs   # shape
-node .claude/skills/lisa-secrets-access/scripts/doctor-secrets.mjs    # health
+node .claude/skills/lisa-secrets-access/scripts/validate-config.mjs      # shape
+node .claude/skills/lisa-secrets-access/scripts/preflight-secrets.mjs    # credential readiness
+node .claude/skills/lisa-setup-remote-env/scripts/preflight-tools.mjs    # tooling readiness
+node .claude/skills/lisa-secrets-access/scripts/doctor-secrets.mjs       # health
 ```
 
 Run the validator first. It checks only the *shape* of the `secrets`, `remoteEnv`, and
@@ -438,6 +517,33 @@ would otherwise surface somewhere unhelpful: a container failing mid-setup, a sc
 never fires, a dispatch naming a surface nobody provisioned. The health check then asks whether the
 credentials actually resolve.
 
+The preflight in the middle is the same check the SessionStart hook runs, and it is here for the
+half the hook deliberately cannot do. The hook injects its verdict into an agent's context and
+never blocks — killing a session over a credential it may not need would tax every session for a
+minority need, and a control people route around enforces nothing. Doctor is where the same
+verdict is allowed to be a non-zero exit.
+
+It reports three outcomes, and the third carries the weight. `ok` and `missing` are self-evident.
+**`unreachable`** means the provider itself could not be asked — no CLI, no bootstrap token, an API
+that errored — and it is neither of its neighbours. Reported as `ok` it would be a vacuous green,
+clean precisely because nothing was learned. Reported as `missing` it would blame the vault for a
+fault in this machine's access and send someone to grant a credential that was never absent. Both
+fail; they differ in what they tell the reader to fix.
+
+The tooling preflight asks the same question about CLIs, and it is a *caller* of
+`planToolchain` rather than a second implementation — that distinction is the point.
+`verify-remote-env.mjs` previously ran its own toolchain loop which never consulted
+`minVersion`, so a container verified clean against a `node` older than the manifest
+demanded while the plan-side check rejected exactly that. One function now answers the
+question everywhere.
+
+It needs only two verdicts. A local binary cannot fail to be asked the way a vault can,
+and the analogous trap — a tool present at an unparseable version — already fails closed
+upstream, because an unknown version loses every `minVersion` comparison. What it does add
+is a split credentials have no equivalent for: a missing tool with a pinned, checksummed
+`install` entry is something Lisa can place itself, so it reports an action and exits zero,
+while a tool nothing can provision blocks and exits non-zero.
+
 It reports without ever printing a value, and compares two copies of the same credential by digest.
 Map its findings into the doctor's own verdicts: `error` → `FAIL`, `warn` → `WARN`.
 

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/preflight-secrets.mjs

@@ -0,0 +1,324 @@
+/**
+ * Prove, before an agent starts work, that the credentials it needs resolve.
+ *
+ * The contract has always claimed this. `secrets.require` is documented as an
+ * assertion — "a listed name that does not resolve is a startup error, not a
+ * late surprise" — and that sentence is the literal text of an error message in
+ * `doctor-secrets.mjs`. But nothing ran it at startup. The only caller of
+ * either presence check was a bash line inside `lisa-doctor`'s SKILL.md, which
+ * an agent had to read and choose to execute. The guarantee was prose; the
+ * plumbing to deliver it did not exist.
+ *
+ * This module is the missing caller, and it answers the question the gate
+ * actually asks. `AGENTS.md` requires intake to establish that the factory has
+ * the tooling "*and provable access to that tooling*" before accepting work. A
+ * credential that resolves nowhere is precisely a failure of provable access,
+ * and discovering it forty minutes into a build — after a ticket is claimed and
+ * a branch is cut — converts a clean refusal into abandoned half-work.
+ *
+ * **Three verdicts, and the third is the point.** `ok` and `missing` are
+ * obvious. `unreachable` is what happens when the provider itself cannot be
+ * asked: no CLI installed, no bootstrap token, an API that errored. That state
+ * must never collapse into either neighbour. Folded into `ok` it is a vacuous
+ * green — the check reports clean precisely when it learned nothing, which is
+ * the failure mode that lets a suppressed error read as a measured zero. Folded
+ * into `missing` it blames the vault for a fault in the caller's access, and
+ * sends whoever reads it to grant a credential that was never absent.
+ *
+ * Both non-ok verdicts fail. They are distinguished in the *message*, not the
+ * exit code, because the remediation differs completely: `missing` means extend
+ * the grant in the vault, `unreachable` means fix this machine's access to it.
+ * @module preflight-secrets
+ */
+
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { fetchAll } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+import { readMaterialized } from "./resolve-secret.mjs";
+import {
+  routingFloorReasons,
+  SUBSTITUTE_SUBSTRATES,
+} from "./routing-floor.mjs";
+
+/** Verdicts this check can reach, worst last. */
+export const VERDICTS = ["ok", "missing", "unreachable"];
+
+/**
+ * The names that must resolve on this surface, and why each is required.
+ *
+ * The floor is *unioned* with `require` rather than checked against it. A
+ * project should not have to restate `GH_TOKEN` to be protected by a rule its
+ * own `tracker: "github"` already implies, and a required set that depends on
+ * someone having typed it is exactly the hand-maintained list this replaces.
+ *
+ * `require` keeps its second job untouched. It still narrows resolution — a
+ * name outside it cannot be fetched — and the floor deliberately does not feed
+ * that. Unioning the floor into `cfg.require` would switch narrowing *on* for
+ * every project that never opted into it, and every credential they resolve
+ * today that is not in the floor would start throwing.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Array<{name: string, reasons: string[]}>} Required names, sorted.
+ */
+export function requiredNames(cfg) {
+  const reasons = routingFloorReasons(cfg.routing ?? {});
+  const declared = cfg.require ?? [];
+  const names = [...new Set([...(cfg.requiredFloor ?? []), ...declared])];
+  return names
+    .sort((left, right) => left.localeCompare(right))
+    .map(name => ({ name, reasons: whyRequired(name, reasons, declared) }));
+}
+
+/**
+ * Why one name is required, never empty.
+ *
+ * `report` renders this as "NAME — required because <reasons>", so an empty
+ * list prints a sentence that stops mid-clause and tells the operator nothing
+ * about which line of config to change. A name can reach the required set
+ * through the floor without a routing reason — anything that hands `preflight`
+ * a `requiredFloor` it did not derive from `routing` does exactly that — so the
+ * renderer needs a cause it can always print.
+ * @param {string} name The credential name.
+ * @param {Record<string, string[]>} reasons Routing-derived causes.
+ * @param {string[]} declared Names listed in `secrets.require`.
+ * @returns {string[]} At least one reason.
+ */
+function whyRequired(name, reasons, declared) {
+  const routingReasons = Object.hasOwn(reasons, name) ? reasons[name] : [];
+  const causes = [
+    ...(routingReasons ?? []),
+    ...(declared.includes(name) ? ["declared in secrets.require"] : []),
+  ];
+  return causes.length
+    ? causes
+    : ["it is in this project's resolved secrets floor"];
+}
+
+/**
+ * Check every required credential against the resolution ladder.
+ *
+ * Values are never returned, printed, or written anywhere by this function. It
+ * reports names and whether each resolved, which is all a readiness check needs
+ * and the only shape safe to surface into an agent's context.
+ * @param {object} [cfg] Resolved configuration.
+ * @param {Function} [fetch] Provider view factory, injected for tests.
+ * @param {Function} [materialized] Materialized view factory, for tests.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @param {Function} [probe] Substrate probe runner, injected for tests.
+ * @returns {{verdict: string, required: Array<{name: string, reasons: string[]}>, missing: Array<{name: string, reasons: string[]}>, reason: string|null}}
+ */
+export function preflight(
+  cfg = readConfig(),
+  fetch = fetchAll,
+  materialized = readMaterialized,
+  env = process.env,
+  probe = runProbe
+) {
+  const required = requiredNames(cfg);
+  if (!required.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  const file = safely(() => materialized(cfg)) ?? new Map();
+
+  // Env and the materialized file are consulted before the provider, and a
+  // required name satisfied by either needs no provider call at all. A session
+  // whose credentials are already exported is the common case on CI, and paying
+  // a network round-trip to confirm what is already in the environment would
+  // make the cheapest surface the slowest.
+  const unresolvedLocally = required.filter(
+    ({ name }) =>
+      !present(env[name]) && !file.get(name) && !substrateSatisfies(name, probe)
+  );
+  if (!unresolvedLocally.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  let provider;
+  try {
+    provider = fetch(cfg);
+  } catch (err) {
+    return {
+      verdict: "unreachable",
+      required,
+      missing: unresolvedLocally,
+      reason: err.message,
+    };
+  }
+
+  const missing = unresolvedLocally.filter(
+    ({ name }) => !present(provider.get(name)?.value)
+  );
+  return {
+    verdict: missing.length ? "missing" : "ok",
+    required,
+    missing,
+    reason: null,
+  };
+}
+
+/**
+ * Render a verdict for whoever has to act on it.
+ *
+ * Written for a non-technical operator standing at the gate, per `AGENTS.md`:
+ * everything crossing a gate outward must be readable by the person being asked
+ * to decide. So each line names the credential, why it is required, and which
+ * of the two remedies applies.
+ * @param {object} result A {@link preflight} result.
+ * @param {object} cfg Resolved configuration.
+ * @returns {string} Operator-readable report, empty when nothing needs saying.
+ */
+export function report(result, cfg) {
+  if (result.verdict === "ok") return "";
+
+  const lines = [];
+  if (result.verdict === "unreachable") {
+    lines.push(
+      `Secrets preflight could NOT be completed on surface "${cfg.surface}".`,
+      `The "${cfg.provider}" provider could not be reached, so nothing is`,
+      `known about any credential — this is not a report that they are fine.`,
+      ``,
+      `  reason: ${result.reason}`,
+      ``,
+      `Fix this machine's access to the provider (bootstrap token, CLI`,
+      `install, network), then start a new session. Do not treat the`,
+      `credentials below as verified:`
+    );
+  } else {
+    lines.push(
+      `Secrets preflight FAILED on surface "${cfg.surface}".`,
+      `These credentials are required and resolve nowhere — not in the`,
+      `environment, not materialized, not in the "${cfg.provider}" grant.`,
+      `Extend the grant in the vault (or correct the routing that requires`,
+      `them), then start a new session:`
+    );
+  }
+  lines.push(``);
+  for (const { name, reasons } of result.missing) {
+    lines.push(`  ${name} — required because ${reasons.join("; ")}`);
+  }
+  lines.push(
+    ``,
+    `Work needing one of these cannot be completed. Route the item to`,
+    `blocked with this reason rather than claiming it and stopping partway.`
+  );
+  return lines.join("\n");
+}
+
+/**
+ * Whether an alternative substrate already provides this capability.
+ * @param {string} name Required credential name.
+ * @param {Function} probe Probe runner, injected for tests.
+ * @returns {boolean} True when the substrate answered successfully.
+ */
+function substrateSatisfies(name, probe) {
+  const substrate = SUBSTITUTE_SUBSTRATES[name];
+  return substrate ? probe(substrate) : false;
+}
+
+/**
+ * How long a substrate probe may take before it counts as no answer.
+ *
+ * `gh auth status` contacts GitHub, and this runs on the session-start path.
+ * Unbounded, a hung connection holds the session open for as long as the child
+ * lives — the `catch` cannot help, because it is only reached once the call
+ * returns. Five seconds is far beyond a healthy round trip and far below the
+ * point where a person concludes the agent is broken.
+ */
+const PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * Run a substrate probe, treating any failure as "did not satisfy".
+ *
+ * Output is discarded rather than captured. The probe's job is to answer a
+ * yes/no question with its exit status, and a command that can print a
+ * credential is one whose stdout should never enter this process.
+ *
+ * A timeout throws, which the catch maps to false — the fail-closed answer. The
+ * credential is then checked against the environment, the materialized file and
+ * the provider as if no substrate existed, so a slow network costs a stricter
+ * check rather than a wrong verdict.
+ *
+ * Exported so the bound itself can be proved against a real slow command. A
+ * timeout that only exists as an option object is a claim; one that has been
+ * watched cut a hanging child off is a control.
+ * @param {{command: string, args: string[]}} substrate Probe definition.
+ * @returns {boolean} True when the command exited zero.
+ */
+export function runProbe(substrate) {
+  try {
+    execFileSync(substrate.command, substrate.args, {
+      stdio: "ignore",
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a resolved value counts as present.
+ * @param {unknown} value Candidate value.
+ * @returns {boolean} True when it is a non-blank string.
+ */
+function present(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Run a thunk, treating any throw as "no view available".
+ *
+ * The materialized file is optional on every surface and absent on most, so a
+ * failure to read it is not a preflight failure — the provider is still
+ * authoritative. Only the provider's own unavailability is a verdict.
+ * @param {Function} thunk Work to attempt.
+ * @returns {*} The result, or undefined when it threw.
+ */
+function safely(thunk) {
+  try {
+    return thunk();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * CLI entry point. Prints the report and exits non-zero on any failure.
+ */
+function main() {
+  const cfg = readConfig();
+  const result = preflight(cfg);
+  const text = report(result, cfg);
+  if (text) console.error(text);
+  if (result.verdict !== "ok") process.exit(1);
+}
+
+/**
+ * Whether this module is the entry point node was asked to run.
+ *
+ * Both sides are realpath'd rather than compared as text: `import.meta.url` is
+ * the resolved path while `process.argv[1]` is whatever the caller typed, so a
+ * symlinked path — every git worktree, and every `/tmp` path on macOS — makes a
+ * raw comparison false. The module then loads, runs nothing, and exits 0, which
+ * is a readiness check reporting clean because it never ran. Same rule and same
+ * reasoning as `scripts/lib/invoked-as-script.mjs`, written out here because a
+ * plugin payload has no `./lib/` to import from.
+ * @param {string} moduleUrl This module's own `import.meta.url`.
+ * @param {string} [argv1] Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the CLI body should run.
+ */
+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();
+}