Lisa Doctor

Doctor: $ARGUMENTS

Run a read-only Lisa readiness audit for the current repository.

Purpose

/lisa:doctor is the deterministic answer to "is this repo actually ready to use Lisa?" It audits the repository in grouped sections, reports each check as PASS, WARN, FAIL, or SKIP, and emits one overall verdict: READY, READY_WITH_WARNINGS, or NOT_READY.

The command is repository-scoped. It validates only what can be observed from the current repo, current machine, and current runtime. It does not create automations, labels, tracker items, or other external state as part of the default audit path.

Inputs

• Optional flags in $ARGUMENTS that narrow or tune read-only validation.
• The current repository root and its Lisa config files (.lisa.config.json, .lisa.config.local.json) when present.

Confirmation policy

Do not ask whether to proceed. Once invoked, run the read-only audit, print the grouped results, emit the overall verdict, and stop.

Specifically forbidden:

• Previewing the number of checks and asking whether to continue.
• Offering "run a few checks first" or "dry-run vs real run" choices. This skill is already the read-only path.
• Performing setup mutations just because a failing check discovered something missing.

The only legitimate reasons to stop early are:

• The current working directory cannot be resolved to a repository/root the audit can inspect.
• The runtime blocks all required local reads needed to even classify the repo.

Audit contract

Doctor reports grouped checks in a stable, human-readable structure. The grouped sections include, as applicable to the current repo:

1. Project detection and runtime basics — detect the project root, package/runtime surface, and whether Lisa is installed where the repo expects it.
2. Lisa config readiness — read .lisa.config.json and .lisa.config.local.json using the same local-overrides-global semantics defined by config-resolution; report missing required keys, incompatible combinations, and committed-vs-local locality problems as findings rather than mutating config.
3. Tracker/source preflight — perform read-only readiness checks for the configured tracker and source only. If a required CLI, MCP surface, or auth context is unavailable in the current runtime, report that explicitly instead of pretending the repo is ready.
4. Runtime distribution surfaces — confirm the command, skill, hook, and related distribution surfaces relevant to this repo are present where Lisa expects them on the active runtime, and that the Lisa-owned enforcement artifacts (scripts/lisa-hooks/*, scripts/lisa-enforcement-fallback.sh) match the installed Lisa version rather than an older copy. Present-but-stale is a finding: a guard whose fix never landed enforces the old behavior.
5. Automation readiness — inspect whether the configured queue source/tracker and scheduling prerequisites are observable, but do not create, edit, or delete automations during doctor.
6. Optional GitHub Project coordination — when github.projects.v2 is configured, delegate the shared validation read to github-project-v2 instead of reimplementing ad-hoc GraphQL checks. Honor the required=false vs required=true semantics documented by config-resolution: best-effort failures are WARN, required-mode failures are FAIL.
7. Optional wiki delegation — when a repo-local wiki/ exists, either summarize the specialized lisa-wiki-doctor verdict or explicitly report that deeper wiki checks are available there. The base doctor stays narrower than full wiki migration enforcement.
8. Optional Kane browser provider — when verification.browser.kane.enabled is true, run the Lisa-owned readiness probe. Require explicit cloud-upload approval, the contract-tested exact version, a non-production environment allow-list, local Chrome/Chromium, Test Manager project/folder targeting, whoami authentication, and nonzero/observable credit readiness. Report missing executable/browser, auth failure, wrong target, zero credits, and control-plane failure separately. If Kane is not enabled, report an informational OK/not enabled rather than probing or installing it.

If a check family is not applicable to the current repo, report SKIP with the reason.

Minimum config-readiness checks

The Lisa config group is not just "does a file exist?" Doctor must audit the config contract in this order:

1. Presence + parseability

   • FAIL when .lisa.config.json is missing, empty, or invalid JSON.
   • Read .lisa.config.local.json only when present; if present but invalid JSON, FAIL.

2. Merged effective config

   • Resolve every key with the same per-key local-overrides-global semantics documented by config-resolution. Doctor must describe findings against the effective merged value, not by pretending one file fully replaces the other.

3. Required top-level dispatch keys

   • FAIL when merged tracker is missing or is not one of jira, github, or linear.
   • FAIL when merged source is present but is not one of notion, confluence, linear, github, or jira.

4. Vendor required-key audit

   • FAIL when the configured tracker/source points at a vendor whose required keys are absent after merge. Examples: tracker=github requires github.org + github.repo; tracker=jira requires atlassian.cloudId + jira.project; source=notion requires notion.workspaceId + notion.prdDatabaseId.
   • Reuse the config-resolution vendor tables rather than inventing a second required-key list.

5. Local-vs-committed locality audit

   • WARN when developer-specific fields appear in committed config. At minimum enforce the documented local-only examples: atlassian.email, intake.assignee, and jira.verified_workflow_hash.
   • WARN when project-wide shared fields exist only in .lisa.config.local.json and are absent from .lisa.config.json, because the current machine may work while the repository remains under-configured for teammates and automations. Examples include tracker, source, github.org, github.repo, atlassian.cloudId, atlassian.site, jira.project, linear.workspace, linear.teamKey, and deploy.branches.

6. Deploy env-order audit (only when deploy.branches is present)

   • PASS (or skip) when deploy.branches defines a single environment — deploy.order is optional and the back-sync chain is empty.
   • PASS (or skip) when deploy.branches defines multiple environments that all map to the same branch (e.g. dev/staging/production all → main). The branches resolve to a single distinct branch, so there is nothing to back-sync, the chain is the empty no-op, and deploy.order is not required. Do not WARN.
   • WARN when deploy.branches resolves to more than one distinct branch but deploy.order is absent. Config-driven back-sync cannot derive a source→target chain without the env ranking; the repo must add deploy.order (low→high, e.g. ["dev","staging","production"]).
   • FAIL when deploy.order is present but its env-name set does not exactly match the keys of deploy.branches (every env in one must appear in the other). A mismatch silently breaks the derived chain.
   • Reuse the deploy.order / deploy.branches contract from config-resolution ("Env order (sync-down chain)") rather than re-deriving the rules here.

Locality findings are advisory unless the merged config is unusable. Missing shared keys after the merge are FAIL; shared keys that exist only locally are WARN.

Minimum tracker/source preflight checks

After config readiness passes far enough to resolve the merged tracker and optional source, doctor must perform read-only preflight checks for the configured vendors only. It does not probe every vendor Lisa supports.

1. Scope the audit to configured vendors
   • Audit the merged tracker.
   • Audit the merged source only when present and distinct from the tracker.
   • Report every non-configured vendor as SKIP rather than pretending it was checked.
2. Prove a readable substrate exists
   • tracker=github or source=github: require gh CLI availability, a passing gh auth status, and a read probe against the configured repo such as gh repo view <org>/<repo>.
   • tracker=jira, source=jira, or source=confluence: follow the atlassian-access substrate ladder and prove at least one read-capable path can see the configured atlassian.cloudId and vendor scope. Acceptable substrates are acli, Atlassian MCP, or the validated API-token/curl path documented by config-resolution.
   • tracker=linear or source=linear: require either readable Linear MCP access or a valid personal API-key probe against the configured workspace. When Linear is the tracker, doctor must also prove the configured linear.teamKey is visible.
   • source=notion: require either a Notion MCP identity match for notion.workspaceId or a valid internal-integration token probe, plus read visibility to notion.prdDatabaseId.
3. Separate missing tooling from missing auth or scope
   • Missing executable / MCP substrate availability is a distinct observed fact, not the same as "auth failed."
   • When a probe runs and fails, preserve the exact read-only failure text or HTTP/GraphQL status in the observed output so the operator can distinguish wrong workspace/site/repo from missing credentials.
4. Severity ladder
   • PASS when at least one supported read-only substrate proves the configured vendor is reachable with the required scope.
   • WARN when the configured vendor is reachable, but an additional optional substrate is unavailable and later Lisa flows would need to fall back.
   • FAIL when no supported substrate can prove read access for the configured tracker/source, or when the configured vendor target is unreadable from the current runtime.

Minimum GitHub Project coordination checks

When github.projects.v2 is configured, doctor must run one additional read-only coordination check instead of treating the config block as implicitly ready.

1. Delegate through the shared chokepoint

   • Call lisa-github-project-v2 in read-only resolution mode:

     operation: resolve-project
     

   • Do not inline ad-hoc Project GraphQL in doctor. Setup, doctor, writers, and linked-PR flows must all read the same owner/access contract from the shared utility.

2. Preserve exact namespace + access failures

   • Enforce the v1 namespace rule exactly as documented by the shared utility. If github.projects.v2.owner.slug does not match github.org, report:

     code: project_namespace_mismatch
     message: "github.projects.v2.owner.slug must match github.org in v1"
     remediation: "Use a Project owned by <github.org> or remove github.projects.v2."
     

   • For owner-access or GraphQL failures, preserve the exact GitHub / GraphQL failure text in the observed output. Examples include missing Project, Resource not accessible by integration, unsupported owner kind, or a wrong owner/number pair.

3. Report exact remediation paths
   • Doctor must make the next operator action explicit. At minimum, say whether they need to:
     1. choose a Project owned by the tracked repo namespace,
     2. grant the token Project read/write access,
     3. correct the configured Project number/owner, or
     4. remove github.projects.v2 when coordination is not required.
4. Map shared utility outcomes into doctor severity
   • required: false => doctor WARN. Repository-local GitHub issue/PR flows remain usable while Project coordination is degraded.
   • required: true => doctor FAIL. The same Project validation failure blocks Lisa readiness because coordination was configured as required.

Good output examples:

WARN github.projects.v2: Resource not accessible by integration
Observed: exact GitHub / GraphQL failure text preserved from resolve-project.
Remediation: grant the token Project read/write access or remove github.projects.v2.required.
Repository-local GitHub issue/PR flows remain usable; Project coordination is disabled.

FAIL github.projects.v2: github.projects.v2.owner.slug must match github.org in v1
Remediation: use a Project owned by CodySwannGT or remove github.projects.v2.

Minimum automation-readiness checks

Doctor's automation-readiness group stays read-only: it audits whether this repo and runtime could support /lisa:setup-automations and the resulting recurring jobs, but it does not create, edit, delete, or reconcile automations on the default doctor path.

1. Resolve the queue inputs exactly as setup-automations would
   • Resolve the PRD queue from merged source.
   • Resolve the build queue from merged tracker.
   • Resolve the repair queue from the same queue-detection rules as lisa-repair-intake (identical source-dispatch contract to lisa-intake).
   • If any automation would require guessing because source, tracker, or their vendor keys are still unresolved after the config-readiness audit, report that automation as FAIL rather than pretending scheduling can proceed safely.
2. Audit the current runtime's native scheduler surface without mutating it
   • Codex: doctor should report whether the runtime exposes the native automations surface (automation_update) needed by /lisa:setup-automations.
   • Claude: doctor should report whether the runtime exposes /schedule.
   • Other runtimes: doctor should explicitly say that no native Lisa scheduler is known for the current runtime.
   • This is observability only. Never create a placeholder automation just to prove the scheduler works.
3. Check exploratory-automation support by shipped stack surface
   • exploratory-bugs is supported only when the project ships an exploratory-qa command surface (the expo, rails, or harper-fabric stacks today). Reuse the same stack/support rule documented by setup-automations; do not invent exploratory jobs for stacks that do not ship that command.
   • When the repo does not ship exploratory-qa, report exploratory-bugs as SKIP with the reason.
   • exploratory-prds remains applicable when the repo can run /lisa:project-ideation; if its queue/config prerequisites are unresolved, report the exact blocking config fact.
4. Severity ladder
   • PASS when an automation's queue inputs are resolvable and the runtime exposes the required native scheduler surface for that automation.
   • WARN when Lisa remains usable manually, but the current runtime has no native scheduler surface for unattended runs, so automation setup would be unavailable from here.
   • SKIP when an optional automation is intentionally unsupported for this repo surface (for example, exploratory-bugs on a stack with no exploratory-qa command).
   • FAIL when the repo's config cannot resolve the queue that an automation needs, because that would make unattended runs ambiguous or broken before scheduling even starts.

Minimum wiki-delegation checks

When a repo-local wiki/ directory exists, doctor must surface the specialized wiki-readiness path without turning the base doctor into a second lisa-wiki-doctor.

1. Detect whether wiki delegation applies
   • If no repo-local wiki/ directory exists, report the entire wiki group as SKIP with the reason that no wiki surface is present in this repository.
   • If wiki/ exists, keep the group present in the final report; do not silently omit it.
2. Prefer summary of an existing specialized verdict
   • If the repo already has a readable wiki/state/migration/doctor-report.json, doctor may summarize the specialized verdict (READY, READY_WITH_WARNINGS, or NOT_READY) plus the most relevant blocking/warning facts, clearly attributing them to lisa-wiki-doctor.
   • Preserve the base doctor's narrower scope: summarize or quote the specialized verdict, but do not inline the full migration/readiness checklist into the base doctor output.
3. Otherwise advertise the deeper follow-up explicitly

   • If wiki/ exists but no specialized report is available yet, doctor must still tell the operator that deeper wiki checks live behind lisa-wiki-doctor.

   • The report should make the next action explicit, for example:

     WARN wiki-follow-up: wiki/ detected; deeper wiki migration checks not yet summarized
     Observed: wiki/ exists, but no wiki/state/migration/doctor-report.json was found.
     Remediation: run lisa-wiki-doctor to produce the wiki-specific readiness verdict.
     

4. Severity ladder
   • SKIP when wiki/ is absent.
   • PASS when wiki/ exists and doctor successfully summarizes an existing lisa-wiki-doctor verdict.
   • WARN when wiki/ exists and doctor can only advertise the specialized follow-up because no persisted wiki verdict is available yet.
   • FAIL only when wiki/ exists but the repo cannot surface the specialized follow-up at all (for example, the required lisa-wiki-doctor distribution surface is missing or the existing report is unreadable/malformed enough that doctor cannot safely summarize it).
5. Keep wiki readiness optional for non-wiki repos
   • Never require a wiki plugin surface when wiki/ is absent.
   • Never let wiki-specific checks downgrade unrelated non-wiki repositories.

Minimum repository-readiness checks

The eight groups above answer one question: is Lisa installed correctly here? There is a second, orthogonal question — may an agent fleet operate here unattended? — and conflating them is how a brownfield onboarding ends in "we built a wiki, looks good" instead of a verdict someone can act on. Repository readiness is that second question, and it is opt-in behind the --readiness flag; the default doctor path never renders it and stays byte-identical.

1. Render one separately-titled group. When readiness mode is requested, append a single Repository readiness group (id repository-readiness) in a fixed position after the eight installation groups, using the shared createRepositoryReadinessDoctorGroup helper from scripts/doctor-report.mjs. It is distinct from the installation groups so a reader is never left guessing which question a verdict answered.

2. Score exactly the eight ownership dimensions from readiness-rubric. Report eight checks, in fixed order, never fewer and never silently omit one: context-routing, capabilities-tools, domain-ownership, execution-proof, feedback-guardrails, dependencies-supply-chain, delivery-authority, proportionality. Cite the readiness-rubric slug for the dimension definitions, the seven ship blockers, and the consequence-ordering contract; do not restate or fork that vocabulary here.

3. SKIP carries a reason and is never blank. A dimension with no applicable evidence renders SKIP with a stated reason ("no deployment target configured, so delivery/authority was not assessed"). An unassessed dimension is a known unknown, and the report says so.

   This surface reflects the CLI; it does not re-score. The evidence producers and the blocker engine live in the Lisa CLI, which is the single source of truth. When .lisa/readiness.json is present and readable (parses, matching schema_version, carries a dimensions array), this group projects each recorded dimension's status and its operator-facing evidence/reason text, so an operator running /lisa:doctor through any coding agent sees the same readiness answer the CLI gives. When the report is absent, unparseable, or stamped with an unknown schema_version — or records nothing for a given dimension — that dimension falls back to SKIP with the reason it was not assessed. Absence means the readiness pass has not run, never that the repository is clean: a pass or a fail is never manufactured from a missing report. Run lisa doctor --offline --readiness to produce the report first.

   A standing blocker outranks the recorded status. Some CLI producers record WARN while standing a ship blocker — the blocker engine never reads the per-dimension status, so the finding flips the repository to NOT_READY exactly as a FAIL would. A dimension that owns an entry in the report's blockers[] therefore projects as FAIL regardless of its recorded label, and its remediation names the blocker ids and repeats the report's narrowed_claim (the "IS ready for supervised, single-ticket agent work" fallback readiness-rubric requires whenever a blocker stands). Projected checks also carry the report's generated_at/lisa_version so a stale report cannot read as current truth, and unassessed dimensions carry the CLI's not-established caveat.

4. Reuse the shipped verdict ladder and consequence ordering. No new verdict value and no new severity: reuse READY / READY_WITH_WARNINGS / NOT_READY. READY requires positive evidence — every readiness dimension assessed and clean, with no blocker standing. An unassessed (SKIP) dimension is silence, not health, so any readiness report carrying one tops out at READY_WITH_WARNINGS; only a standing ship blocker yields NOT_READY. Section order stays stable; the findings within each dimension check order highest-consequence-first.

5. Persist to a versioned, relocatable artifact. Writing the report to .lisa/readiness.json (schema_version: 1, with verdict, blocker_count, and per-dimension findings) is resolved through a single resolver so the location is one line to change. The write is atomic and must never fail the run: a write error degrades to a WARN check rather than throwing.

6. Warn-only, always. This gates a claim, not a process: readiness never hard-blocks and never changes doctor's exit-code semantics (exit 1 iff some check is FAIL). Where a surface named here is not installed, degrade — state what was assessed, state what was not, and continue.

Upstream Lisa change-history diagnosis

A failing or warning check has two possible causes: the project drifted, or Lisa itself changed upstream since this project last updated. Doctor must distinguish them instead of blaming the project by default. Whenever findings need explanation — and always before proposing repairs — attribute the finding with real evidence.

The attribution procedure itself is shared: it lives in the lisa-attribute-failure skill (extracted from this section so any failure event can be attributed, not only doctor findings). Doctor invokes it per finding:

1. Resolve the version window. Determine the project's installed Lisa version (the @codyswann/lisa entry in package.json/lockfile, or the plugin version stamp on the active runtime) and the latest published version (npm view @codyswann/lisa version, or the update check's cached result).
2. Invoke lisa-attribute-failure with the finding as the failure event: the defect description, the implicated template/config paths, the rule/skill/hook in play, and the resolved version window. The skill evaluates its three ordered signals — Lisa-managed surface ownership, shipped rule/skill/hook behavior, and the upstream change-history window (the version-window compare procedure formerly documented inline here, preserved verbatim in that skill: pagination/--slurp handling, targeted per-SHA diff context, truncation caveats, and the bounded explicit-tag fetch fallback) — and returns lisa | project | ambiguous plus the cited evidence.
3. Map the verdict into the finding.
   • lisa — Lisa changed the contract (a tightened lint rule, a renamed check context, a new required config key) or shipped the defective surface. Say so in Observed: with the cited evidence (commit subject/version or managed-surface proof), and let Remediation: point at the sanctioned adoption path (e.g. lisa update + re-apply, a documented config opt-out) rather than hand-editing managed files.
   • project — history shows no relevant upstream change and the surface is project-owned: the project drifted, so remediate on the project side.
   • ambiguous — history was unavailable, truncated, or otherwise inconclusive: report the gap as a WARN-level observability note with the evidence gap named — never fail the audit because history was unavailable or incomplete, and never attribute drift with unverified confidence.

This diagnosis remains part of doctor's read-only contract: the attribution skill reads Lisa's repository, never writes to it, and repair suggestions stay suggestions.

Output contract

The final report must:

• Separate observed facts from remediation advice.
• Print every check with one of PASS, WARN, FAIL, or SKIP.
• Emit exactly one overall verdict: READY, READY_WITH_WARNINGS, or NOT_READY.
• Stay read-only by default.

Render the report in grouped sections using the shared scripts/doctor-report.mjs contract:

• Start with Overall verdict: <VERDICT> and one Counts: line covering PASS, WARN, FAIL, and SKIP.
• Then print each group as <group-id>. <group-title>.
• Under each group, print one line per check as - <STATUS> <check-id>: <summary>.
• When available, print Observed: and Remediation: lines beneath the check so the report keeps facts separate from advice.
• If a group has no applicable checks yet, render it as a grouped SKIP with the reason instead of silently omitting the section.

The verdict ladder is:

• READY — no FAIL and no WARN.
• READY_WITH_WARNINGS — no FAIL, but one or more WARN.
• NOT_READY — one or more FAIL.

Gate configuration

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
node scripts/lisa-gates.mjs skip-jobs                   # what replaces each skip_jobs token

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.

skip-jobs answers the migration off the skip_jobs workflow input. Eleven of the token → gate pairs cannot be recovered by transforming the name — lint is code-style, sg_scan is structural-rules, work_item_traceability is traceability — and being wrong does not break a build: it declares the WRONG gate off, so a check silently stops running while the configuration reads deliberate. Pass --moment= to match the moment the caller passes to quality.yml, because a gate's legal moments are a closed set and a declaration outside it is refused by validate — after the token has already been deleted.

Four of its six answers are refusals, and they are the point. unmappable means the job was never converted to a gate façade, so keep the token. partial means one job behind the token has a gate and the others do not, so the declaration alone would leave work running. inert means no job honours that token at all. unknown means nothing matches it — usually a space after a comma, which GitHub matches against nothing, so that job has been RUNNING all along. None of them produce a gate id, because a confident wrong answer here is worse than no answer.

lisa doctor reports the same thing per caller workflow and does NOT edit the workflow. lisa apply runs on postinstall, and an automated rewrite of a caller that gets it wrong is silent; an agent performing the edit can read the surrounding code and confirm afterwards that the same checks ran.

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.

The comparison also runs without anyone typing it. A control reachable only by a human reading a code block is indistinguishable from one that was never written, so the declaration is held against both enforcing surfaces on paths a machine already takes:

Both report one verdict per required context, and the vocabulary is seven values rather than matched/unmatched, because the mismatches and an unreadable surface need different actions:

• matched — declared required, and the surface requires it.
• declared-not-enforced — the settings file says it must pass and nothing requires it. The declaration blocks nothing.
• enforced-declared-off — the settings file says the property is deliberately not proved here, and protection requires it anyway. A contradiction, not a gap.
• enforced-undeclared — protection requires it, a registry gate produces it, and no declaration governs it. Silence is not permission to stop requiring it; the remedy is to declare the gate.
• enforced-declared-optional — protection requires it while the declaration says optional. Name which surface wins.
• enforced-not-lisa-owned — protection requires it and no registry gate produces it. Third-party checks are required by construction and declared by nobody; this bucket exists so they can be told apart from a Lisa gate that fell out of the settings file, never so they can be removed.
• unproven — the surface could not be read, so no enforcement comparison was made. It is never a match and never drift; the operator fixes access/availability and reruns the observation.

enforced-declared-off and declared-not-enforced fail the health check; the two gaps warn. No remedy in that vocabulary removes a required context — the type has no such member, so the 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.

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:

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. 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:

"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.

2b. A gate proved OUTSIDE the quality facade names its own check-run chain. A run-mode gate's required context is derived by prefixing the gate's label with the chain of jobs that reach the facade. When a project proves one property from a workflow of its own instead, that chain describes a route that never reaches the prover, and the derived name is one nothing posts — which does not turn a pull request red, it holds it at "Expected — Waiting for status to be reported" for ever. Declare the real chain on that moment:

"gates": {
  "e2e-browser": {
    "run": "test:e2e:pr",
    "pull-request": {
      "level": "required",
      "caller_chain": ["🎭 PR Browser Coverage"]
    }
  }
}

Read the chain off a completed run, never off the YAML: a check run's reported name is the /-joined chain of the JOB names that reach it, outermost first, and the top workflow's own name: never appears in it. Take it from gh api repos/OWNER/NAME/commits/SHA/check-runs --paginate --slurp, or let lisa-gates.mjs verify-contexts --posted=<file> compare a derivation against what actually posted. Either spelling works — ["A", "B"] or "A / B" — and the override replaces the caller's chain for that gate only; every other gate keeps deriving exactly what it derived before. It is declared per MOMENT, because the same job posts a one-level name on the pull-request path and a two-level one on the release path. Declaring it on the whole gate, on an awaiting moment, at a moment that posts no status, or with a blank level is refused by lisa-gates.mjs validate — at declaration time, which is the last point at which any of those can still fail loudly.

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.

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.

policy.review.require_extra_approval_for_unattributed_changes is declarable for a reason worth stating, because its default is not "leave it alone". Measured against the live rulesets API on 2026-08-25: a pull_request rule sent WITHOUT the parameter came back with it true; set explicitly to false it came back false; sent again without it, it came back true. GitHub re-applies its own default on every write that omits the field. So an operator who wants it OFF cannot hold it off unless the payload names it, and an operator who wants it ON is recording no choice at all — the value is whatever GitHub's default happens to be. Declaring it pins the choice and makes it visible to the reconciler; declaring nothing keeps the payload byte-for-byte what it was, parameter absent.

A ruleset that governs no branch

Reconciliation asks whether the required LIST matches. It never asks whether the ruleset carrying that list matches any ref the repository actually has, and GitHub does not ask either: a conditions.ref_name.include entry is a pattern, no

…(truncated)