@codyswann/lisa 3.15.1 → 3.17.0

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/tool-floor.mjs

@@ -0,0 +1,94 @@
+/**
+ * Derive the CLIs a project's own configuration already implies.
+ *
+ * The symmetric half of `routing-floor.mjs`. A credential and the binary that
+ * consumes it are the same question asked twice — can this agent do the work —
+ * and both were answered only by a hand-maintained list.
+ *
+ * `detect-tooling` already knows most of these pairings and states them well:
+ * "the work-item guardrails shell out to `gh` for every tracker read". But it
+ * knows them at *proposal* time, as suggestions a human runs a skill to see and
+ * then copies into config. Nothing derives them at runtime, so a project that
+ * never ran the skill — or ran it before it adopted Maestro — has a manifest
+ * that silently understates what its agents need.
+ *
+ * This promotes those pairings to a derivation. The floor is unioned into the
+ * required set, never written into config, so it cannot drift from the routing
+ * that produces it.
+ *
+ * Deliberately narrow. An entry belongs here only when the configuration that
+ * implies it makes the tool unavoidable — not merely likely. A project can have
+ * `quality.testCoverage` thresholds and run them through any runner, so no CLI
+ * is derived from that; `secrets.provider: "bitwarden"` on the other hand
+ * cannot resolve one credential without `bws`.
+ * @module tool-floor
+ */
+
+/**
+ * Config predicates that make a CLI unavoidable, with the reason to report.
+ *
+ * The reason is not decoration. A missing tool has two valid remedies — install
+ * it, or change the configuration that demands it — and an operator cannot pick
+ * between them without knowing which line of config is responsible.
+ */
+const DERIVATIONS = [
+  {
+    tool: "gh",
+    applies: cfg => cfg.tracker === "github" || cfg.source === "github",
+    reason: cfg =>
+      `${cfg.tracker === "github" ? "tracker" : "source"} is "github", and ` +
+      `the work-item guardrails shell out to gh for every tracker read`,
+  },
+  {
+    tool: "bws",
+    applies: cfg => cfg.secrets?.provider === "bitwarden",
+    reason: () =>
+      `secrets.provider is "bitwarden", and the CLI is how every secret is ` +
+      `resolved`,
+  },
+  {
+    tool: "doppler",
+    applies: cfg => cfg.secrets?.provider === "doppler",
+    reason: () => `secrets.provider is "doppler"`,
+  },
+  {
+    tool: "maestro",
+    // Keyed on the coverage block rather than a `.maestro` directory: config is
+    // the declaration that this project gates on Maestro, where a stray
+    // directory could be a leftover. `detect-tooling` uses the directory
+    // because it is guessing; here the project has already said so.
+    applies: cfg => cfg.quality?.e2eCoverage?.maestro !== undefined,
+    reason: () =>
+      `quality.e2eCoverage.maestro is configured, and nothing installs the ` +
+      `maestro binary`,
+  },
+];
+
+/**
+ * The CLIs a project's configuration makes mandatory.
+ * @param {object} [config] Parsed `.lisa.config.json` root.
+ * @returns {Array<{name: string, reason: string}>} Sorted derived tools.
+ */
+export function toolFloor(config = {}) {
+  return DERIVATIONS.filter(entry => safely(() => entry.applies(config)))
+    .map(entry => ({ name: entry.tool, reason: entry.reason(config) }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/**
+ * Evaluate a predicate, treating a malformed config as "does not apply".
+ *
+ * A config shaped unexpectedly is a problem for the schema validator to report
+ * in its own vocabulary. Throwing here would make a readiness check the place a
+ * structural defect first surfaces, with a message about tools that names
+ * nothing an operator can act on.
+ * @param {Function} predicate Test to run.
+ * @returns {boolean} The result, or false when it threw.
+ */
+function safely(predicate) {
+  try {
+    return Boolean(predicate());
+  } catch {
+    return false;
+  }
+}

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs

@@ -25,8 +25,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 
-import { readRemoteEnvConfig } from "./setup-remote-env.mjs";
-import { extractVersion } from "./toolchain.mjs";
+import { probe, readRemoteEnvConfig } from "./setup-remote-env.mjs";
+import { planToolchain } from "./toolchain.mjs";
 
 /** Collected results, so every check runs before anything reports failure. */
 const results = [];
@@ -84,39 +84,21 @@ function node(args) {
 
 /**
  * Assert each declared tool is present at its pinned or minimum version.
+ *
+ * Delegates every decision to `planToolchain` rather than probing here. This
+ * function used to run its own loop, and the copy silently forgot `minVersion`:
+ * a `require` entry passed as long as the binary answered `--version` at all,
+ * so a container verified clean against a node older than the manifest
+ * demanded. The plan-side check rejected exactly what this one accepted.
+ *
+ * That is the same failure the note validators had before one shared module
+ * replaced them, and it recurs for the same reason — two implementations of one
+ * question cannot be kept in step by intention. There is now one.
  * @param {object} tools Toolchain manifest.
  */
 function verifyToolchain(tools) {
-  for (const tool of tools.require ?? []) {
-    try {
-      const out = execFileSync(tool.name, ["--version"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      check(true, `tool ${tool.name}`, extractVersion(out) ?? "present");
-    } catch {
-      check(false, `tool ${tool.name}`, "required but not present");
-    }
-  }
-  for (const tool of tools.install ?? []) {
-    try {
-      const out = execFileSync(tool.name, ["--version"], {
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      });
-      const found = extractVersion(out);
-      check(
-        found === tool.version,
-        `tool ${tool.name}`,
-        `${found} (pin ${tool.version})`
-      );
-    } catch {
-      check(
-        false,
-        `tool ${tool.name}`,
-        `pinned ${tool.version} but not installed`
-      );
-    }
+  for (const step of planToolchain(tools, probe, "remote")) {
+    check(step.action === "present", `tool ${step.name}`, step.reason);
   }
 }
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "3.15.1",
+  "version": "3.17.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa-copilot/hooks/secrets-preflight.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Prove at session start that this agent can actually do the work: that the
+# credentials the project needs resolve, and that the CLIs it needs are on PATH.
+#
+# One hook for both because it is one question — can this agent do the work —
+# and an operator reading two separate reports has to assemble the answer
+# themselves. Both halves also share the same failure mode if split: two hooks
+# means two subprocess spawns on every session start, for a check that is silent
+# almost every time.
+#
+# Injects rather than blocks, and that is deliberate. The right response to a
+# missing credential or tool is for the agent to know before it claims work and
+# to route the item to blocked with a reason a human can act on — not for the
+# session to die. A session that cannot reach the vault can still write code,
+# review a PR, or answer a question; killing it would tax every session for a
+# minority need, and a control people route around enforces nothing.
+#
+# The hard gates live where they can afford to be hard: `lisa doctor` and CI
+# run the same two scripts and exit non-zero on them.
+#
+# Silent on success on purpose. A control that announces itself when everything
+# is fine trains its readers to skim past it, and then it is decoration.
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+if [ -n "$INPUT" ]; then
+  HOOK_EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "SessionStart"' 2>/dev/null || echo "SessionStart")
+else
+  HOOK_EVENT="SessionStart"
+fi
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+SECRETS="$ROOT/skills/lisa-secrets-access/scripts/preflight-secrets.mjs"
+TOOLS="$ROOT/skills/lisa-setup-remote-env/scripts/preflight-tools.mjs"
+
+command -v node >/dev/null 2>&1 || exit 0
+# The hook's whole output is one `jq -n` document. Without jq there is nothing
+# to write, so exiting is the only honest outcome — the alternative is a hook
+# that prints `jq: command not found` and exits 127, which reports a failure
+# from a check designed never to block. The doctor and CI gates run the same
+# two scripts without jq involved.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# stderr carries each report; stdout is reserved for the hook's JSON. A script
+# that is absent (partial or older install) or fails to run at all contributes
+# nothing, because a broken hook must not manufacture a finding.
+REPORT=""
+for script in "$SECRETS" "$TOOLS"; do
+  [ -f "$script" ] || continue
+  # An escape hatch that is honest about what it costs, and scoped to what it
+  # names. Set when a surface has no secrets provider by design and the noise is
+  # not worth it; the doctor and CI gates are unaffected, so opting out here
+  # does not opt out of the check entirely. It must not also silence the
+  # TOOLING half — a variable about secrets that hides a missing `gh` or
+  # `maestro` is an opt-out from a check nobody opted out of.
+  if [ "$script" = "$SECRETS" ] && [ "${LISA_SKIP_SECRETS_PREFLIGHT:-}" = "1" ]; then
+    continue
+  fi
+  OUT=$(node "$script" 2>&1 >/dev/null) || true
+  [ -n "$OUT" ] || continue
+  [ -n "$REPORT" ] && REPORT+=$'\n\n'
+  REPORT+="$OUT"
+done
+
+[ -n "$REPORT" ] || exit 0
+
+CONTEXT="## Readiness preflight
+
+$REPORT"
+
+jq -n --arg event "$HOOK_EVENT" --arg ctx "$CONTEXT" \
+  '{"hookSpecificOutput": {"hookEventName": $event, "additionalContext": $ctx}}'

package/plugins/lisa-copilot/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`.