@codyswann/lisa 3.62.0 → 3.63.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/skills/lisa-doctor/SKILL.md

@@ -501,7 +501,11 @@ remedy in that vocabulary removes a required context — the type has no such me
 guarantee holds for every caller rather than for the careful ones. A surface this run could not
 read is reported as unproven and is never a match.
 
-The interactive reconciler remains the way to *write* the live ruleset:
+Reconciliation is **wired**, not something an agent has to remember to run: it is step 5 of
+`scripts/lisa-github-repo-setup.sh`, alongside the settings baseline and the rulesets themselves,
+and it is exposed as `npm run policy:reconcile`. Until #2917 its only callers were the code blocks
+below — prose in this very file — so the declared configuration converged when somebody happened to
+read a document. Run it by hand for the flags:
 
 ```sh
 node scripts/lisa-reconcile-policy.mjs --dry-run              # read-only: what would change
@@ -529,12 +533,41 @@ drift that was *measured*, and here nothing was. Map it to doctor's `WARN`/`FAIL
 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.
+Under `repair` the script 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 check that belongs in `.lisa.config.json` — decide which
+before pruning anything.
+
+A context posted by an external app no longer HAS to be EXTRA. `SonarCloud Code Analysis`,
+`GitGuardian Security Checks`, and `CodeRabbit` are declarable two ways, and either one makes the
+reconciler treat them as MATCHED rather than as a permanent false alarm:
+
+```json
+"gates": {
+  "credential-leakage": {
+    "pull-request": {
+      "level": "required",
+      "await": "GitGuardian Security Checks",
+      "posted_by": 46505
+    }
+  }
+},
+"github": {
+  "rulesets": {
+    "requiredChecks": {
+      "quality checks": [{ "context": "🧩 Plugin artifacts match source" }]
+    }
+  }
+}
+```
+
+An `await` names the gate the signal PROVES, so declaring nothing requires nothing — which is how a
+project that proves credential leakage with a different scanner says so. `posted_by` is the GitHub
+App id allowed to post that context; omit it and the context is required unpinned, GitHub's "any
+source". `requiredChecks` is for a repository-specific check that no gate models; it replaces the
+additive-only `addRequiredChecks`, which is still read but can never express "stop requiring this".
+Both surfaces name the ruleset a repair writes to, so `--ruleset` is needed only for a
+gate-DERIVED context on a repository whose rulesets are ambiguous.
 
 **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
@@ -549,6 +582,12 @@ names that script rather than reshaping rules it did not build. When more than o
 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.
 
+That rule construction is itself config-driven now. `all/github-rulesets/base.json` is deleted; the
+`base` ruleset is generated per project from `policy` — including `policy.ruleset.enforcement`, the
+`policy.ruleset.include_refs` / `exclude_refs` conditions, `policy.ruleset.bypass_actors`, and
+`policy.review.required_approving_review_count`, none of which config could express while the
+template owned them.
+
 ## Secrets configuration
 
 Run the secrets health checks through the skill that owns the contract, rather than reimplementing

package/plugins/src/base/skills/lisa-setup-github-repo/SKILL.md

@@ -23,12 +23,13 @@ Apply the fleet-standard GitHub repository configuration to this project's repo.
    - Default branch set to the lowest-tier environment branch that exists (dev → staging → main); override with `github.settings.default_branch`
    - GitHub wiki tab off (Lisa projects use in-repo `wiki/`)
    - Secret scanning + push protection enabled where the plan supports it
-2. **Rulesets** (`scripts/lisa-github-rulesets.sh`) from Lisa's `<type>/github-rulesets/` templates, matched by project type:
-   - `base` — deletion/force-push protection on `main`/`dev`/`staging` + default, PRs required (0 approvals, review-thread resolution required, merge method = merge only), required checks: CodeRabbit + GitGuardian
+2. **Rulesets** (`scripts/lisa-github-rulesets.sh`) — one generated from config, the rest from Lisa's `<type>/github-rulesets/` templates matched by project type:
+   - `base` — **generated from `.lisa.config.json`**, not shipped as a template. Deletion/force-push protection from `policy.protect`, the branch list from `policy.ruleset.include_refs`, bypass actors from `policy.ruleset.bypass_actors`, approvals from `policy.review`, merge methods from `policy.merge`, and required checks from whatever gates the project `await`s. A project that declares nothing gets exactly the ruleset the retired `all/github-rulesets/base.json` described, minus its two vendor checks — those are now `await` declarations a project can choose not to make
    - `quality checks` — the stack's CI checks (TypeScript emoji names or Rails names)
    - `prevent delete`, `protect tags` (`v*`), plus stack overlays (`cdk validation`, staging-only `playwright`)
    - Repos without `.github/workflows/` get only app-based required checks — an Actions check that can never report would block every PR forever
-   - **A template change never reaches an already-configured repo on its own** — re-running this step is the migration. Reconciliation is additive (a live-only required context is preserved, never dropped) and legible: each context the run newly makes blocking is printed as `+ now required: <context>`, and a ruleset that already satisfies its template reports `nothing to do` and is not sent at all, so a second run is visibly a no-op
+   - **A template change never reaches an already-configured repo on its own** — re-running this step is the migration. Each context the run newly makes blocking is printed as `+ now required: <context>`, and a ruleset that already satisfies its template reports `nothing to do` and is not sent at all, so a second run is visibly a no-op
+   - **Declaring a ruleset's required list makes it declarative.** By default a live-only required context is preserved, never dropped — including on the generated `base`, which gets no exemption: removing a protection by default, on a script invoked with `--yes`, is not something an operator ever opted into. Name a ruleset in `github.rulesets.requiredChecks` and the live list stops being unioned in, so removing an entry actually stops requiring it — printed as `- no longer required: <context>`. Dropping an `await` without that opt-in leaves the live context in place; `lisa-reconcile-policy.mjs` then reports it as EXTRA, and `--prune` is where the removal is asked for. The retired `addRequiredChecks` is still read and could only ever add
 3. **Deploy key** (`scripts/setup-deploy-key.sh --yes`) — write-access deploy key + `DEPLOY_KEY` secret, skipped when already configured. The `base` ruleset's `DeployKey: always` bypass is what lets CI version-bump pushes through protected branches.
 4. **Deployment environments** (`scripts/lisa-github-environments.sh`) — entirely optional; only runs when `.lisa.config.json` declares environments:
    ```json
@@ -52,6 +53,9 @@ Apply the fleet-standard GitHub repository configuration to this project's repo.
    - Every declared environment also gets a **deployment branch policy** pinned to its branch, so only that branch can deploy to it.
    - Provisioning matters: GitHub silently auto-creates an environment **without** protection rules the first time a workflow references it, so an unprovisioned approval gate gates on nothing.
    - The stack `deploy.yml` templates read this same config at runtime and pass `require_approval`/`approval_environment` to `release.yml`, whose `release_approval` job is where the run pauses. Requires a public repo or a paid plan for private repos (the script skips gracefully otherwise).
+5. **Policy reconciliation** (`scripts/lisa-reconcile-policy.mjs`, also `npm run policy:reconcile`) — compares the DECLARED gates and `policy` block against what GitHub actually has, and converges it when `policy.on_drift` is `repair`. It runs here rather than only from a skill file, because a declaration nothing applies is not governance.
+   - The installed `scripts/lisa-reconcile-policy.mjs` is preferred; the shipped template is the fallback; finding neither is a hard failure, not a skip.
+   - Exit `2` is `UNPROVEN` — `gh` refused, is missing, or answered something unparseable. A private repository on a plan without rulesets answers `403`. Setup **warns and continues**: failing for a plan limitation punishes a repository that has done nothing wrong. The warning names the state, because a blind gate that says nothing is indistinguishable from a clean one.
 
 ## Workflow
 

package/scripts/check-required-check-promotions.mjs

@@ -139,7 +139,9 @@ import fs from "node:fs";
 import path from "node:path";
 import yaml from "js-yaml";
 
+import { readGates } from "../all/copy-overwrite/scripts/lisa-gates.mjs";
 import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+import { buildRulesetPayload } from "./lisa-ruleset-payload.mjs";
 
 // Literals named once — each was repeated enough times that a typo in one
 // copy would diverge silently.
@@ -226,13 +228,19 @@ function contextsFromTemplate(absolute, relative) {
 }
 
 /**
- * Read the per-repository `addRequiredChecks` opt-in.
+ * Read the per-repository required-check opt-in.
  *
  * This surface is NOT templated and exists precisely because a Lisa-only
  * context must never ship in a shared template — host projects would inherit a
  * context they never report (the #2476 defect). A guard blind to it would clear
  * every context added this way.
  *
+ * Both key spellings are read: `requiredChecks` is the declarative one that
+ * can also STOP requiring a context, and `addRequiredChecks` is the additive
+ * one it replaced. A guard that read only the new name would go blind to every
+ * repository that has not renamed the key yet — the very blindness described
+ * above, reintroduced by the rename that was supposed to improve things.
+ *
  * @param {string} root - absolute repository root.
  * @returns {{ context: string, integrationId: number, source: string }[]} declarations.
  */
@@ -245,9 +253,18 @@ function contextsFromConfig(root) {
   } catch {
     return [];
   }
-  const added = parsed?.github?.rulesets?.addRequiredChecks ?? {};
+  const rulesets = parsed?.github?.rulesets ?? {};
+  // Both maps are read INDEPENDENTLY, never merged by key. A spread would let
+  // `requiredChecks["quality checks"]` overwrite `addRequiredChecks["quality
+  // checks"]`, and a repository carrying both during a migration would lose the
+  // legacy contexts from promotion checking — a guard going quiet about exactly
+  // the checks a half-finished rename leaves behind.
+  const declared = [
+    ...Object.values(rulesets.addRequiredChecks ?? {}),
+    ...Object.values(rulesets.requiredChecks ?? {}),
+  ];
   const found = [];
-  for (const entries of Object.values(added)) {
+  for (const entries of declared) {
     for (const entry of Array.isArray(entries) ? entries : []) {
       if (typeof entry?.context !== "string") continue;
       found.push({
@@ -264,7 +281,54 @@ function contextsFromConfig(root) {
 }
 
 /**
- * Collect every required context this repository declares, from both surfaces.
+ * Read the required contexts the generated `base` ruleset will carry.
+ *
+ * `all/github-rulesets/base.json` used to be a template this function found by
+ * walking each project type's `github-rulesets` directory, and it named two
+ * vendor contexts. It is now
+ * generated from `.lisa.config.json`'s `await` gate declarations, so a guard
+ * that only walked directories would have gone blind to two contexts that are
+ * still required — and worse, gone blind SILENTLY, reporting a clean promotion
+ * ledger for a surface it had stopped reading.
+ *
+ * @param {string} root - absolute repository root.
+ * @returns {{ context: string, integrationId: number, source: string }[]} declarations.
+ */
+function contextsFromGeneratedBase(root) {
+  let payload;
+  try {
+    const { gates, policy } = readGates(root);
+    payload = buildRulesetPayload({ gates, policy });
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const rule of payload?.rules ?? []) {
+    if (rule?.type !== "required_status_checks") continue;
+    for (const check of rule?.parameters?.required_status_checks ?? []) {
+      if (typeof check?.context !== "string") continue;
+      found.push({
+        context: check.context,
+        // An absent id here means UNPINNED — GitHub's "any source" — not
+        // "GitHub Actions". The generated ruleset emits an awaited vendor check
+        // without an id on purpose, and defaulting it to Actions would send
+        // this guard looking for a workflow job named after the vendor,
+        // reporting a wiring violation against a context Actions never posts.
+        // A template check with no id genuinely IS an Actions check, which is
+        // why the template reader above still defaults; this one must not.
+        integrationId:
+          typeof check.integration_id === "number"
+            ? check.integration_id
+            : null,
+        source: ".lisa.config.json (generated base ruleset)",
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * Collect every required context this repository declares, from every surface.
  *
  * @param {string} root - absolute repository root.
  * @returns {{ context: string, integrationId: number, source: string }[]}
@@ -287,6 +351,7 @@ export function collectDeclaredContexts(root) {
     }
   }
   found.push(...contextsFromConfig(root));
+  found.push(...contextsFromGeneratedBase(root));
   return found.sort(
     (a, b) =>
       a.context.localeCompare(b.context) || a.source.localeCompare(b.source)

package/scripts/lisa-github-repo-setup.sh

@@ -11,6 +11,9 @@
 #   4. Deployment environments with required-reviewer approval gates
 #      (lisa-github-environments.sh), from the optional
 #      github.environments block in .lisa.config.json.
+#   5. Policy reconciliation (lisa-reconcile-policy.mjs): compares the DECLARED
+#      gate and policy configuration against what GitHub actually has, and
+#      converges it when policy.on_drift is `repair`.
 #
 # Usage:
 #   lisa-github-repo-setup.sh [options] [project-path]
@@ -38,7 +41,7 @@ while [[ $# -gt 0 ]]; do
   case $1 in
     -n|--dry-run) DRY_RUN=true; PASSTHROUGH+=("--dry-run"); shift ;;
     -v|--verbose) VERBOSE=true; PASSTHROUGH+=("--verbose"); shift ;;
-    -h|--help) sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     -*) echo "Unknown option: $1" >&2; exit 1 ;;
     *) PROJECT_PATH="$1"; shift ;;
   esac
@@ -47,15 +50,34 @@ done
 PROJECT_PATH="${PROJECT_PATH:-.}"
 PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
 
-echo "==> Step 1/4: repository settings"
+# The reconciler ships as a template AND is installed into host projects. The
+# installed copy is preferred so a project pinned to an older Lisa reconciles
+# with the script it actually has; the template is the fallback so a repository
+# that has not run `lisa apply` yet still gets reconciled. Failing closed when
+# NEITHER resolves is the point — a missing script that exits 0 is how a control
+# reports success while examining nothing.
+resolve_reconciler() {
+  local installed="$PROJECT_PATH/scripts/lisa-reconcile-policy.mjs"
+  local shipped="$SCRIPT_DIR/../all/copy-overwrite/scripts/lisa-reconcile-policy.mjs"
+
+  if [[ -f "$installed" ]]; then
+    echo "$installed"
+  elif [[ -f "$shipped" ]]; then
+    echo "$shipped"
+  else
+    return 1
+  fi
+}
+
+echo "==> Step 1/5: repository settings"
 bash "$SCRIPT_DIR/lisa-github-repo-settings.sh" "${PASSTHROUGH[@]}" "$PROJECT_PATH"
 
 echo ""
-echo "==> Step 2/4: rulesets"
+echo "==> Step 2/5: rulesets"
 bash "$SCRIPT_DIR/lisa-github-rulesets.sh" --yes "${PASSTHROUGH[@]}" "$PROJECT_PATH"
 
 echo ""
-echo "==> Step 3/4: deploy key"
+echo "==> Step 3/5: deploy key"
 if [[ "$DRY_RUN" == "true" ]]; then
   echo "[DRY RUN] Would ensure a write-access deploy key + DEPLOY_KEY secret exist"
 else
@@ -73,8 +95,45 @@ else
 fi
 
 echo ""
-echo "==> Step 4/4: deployment environments"
+echo "==> Step 4/5: deployment environments"
 bash "$SCRIPT_DIR/lisa-github-environments.sh" "${PASSTHROUGH[@]}" "$PROJECT_PATH"
 
+echo ""
+echo "==> Step 5/5: policy reconciliation"
+if ! RECONCILER="$(resolve_reconciler)"; then
+  echo "✗ Could not find lisa-reconcile-policy.mjs in $PROJECT_PATH/scripts/ or in this Lisa install" >&2
+  exit 1
+fi
+
+# Not `[[ ... ]] && cmd`: under `set -e` a false test at top level is a failing
+# command, so on a non-dry run the script would exit right here.
+RECONCILE_ARGS=()
+if [[ "$DRY_RUN" == "true" ]]; then
+  RECONCILE_ARGS+=("--dry-run")
+fi
+
+# Exit 2 is UNPROVEN: `gh` refused, is missing, or answered something
+# unparseable. A private repository on a plan without rulesets answers 403, and
+# 13 rulesets across the portfolio do exactly that — failing setup for a plan
+# limitation punishes a repository that has done nothing wrong. But a blind gate
+# has to SAY it is blind, which is why this is a named warning and not silence,
+# and why the reconciler keeps 2 as its own code rather than collapsing it into
+# either 0 or 1.
+set +e
+(cd "$PROJECT_PATH" && node "$RECONCILER" "${RECONCILE_ARGS[@]}")
+RECONCILE_STATUS=$?
+set -e
+
+case "$RECONCILE_STATUS" in
+  0) ;;
+  2)
+    echo "⚠ Policy was NOT checked (UNPROVEN) — see the reason above. Setup continues; nothing about the declared policy has been verified." >&2
+    ;;
+  *)
+    echo "✗ Policy reconciliation failed (exit $RECONCILE_STATUS)" >&2
+    exit "$RECONCILE_STATUS"
+    ;;
+esac
+
 echo ""
 echo "✓ GitHub repository governance setup complete"