@codyswann/lisa 2.75.1 → 2.77.0

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.75.1",
+  "version": "2.77.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": "2.75.1",
+  "version": "2.77.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa/commands/doctor.md

@@ -0,0 +1,6 @@
+---
+description: "Audit whether the current repository is ready to use Lisa. Runs grouped read-only readiness checks for config, runtime surfaces, tracker/source access, automation prerequisites, and optional project/wiki coordination, then reports PASS/WARN/FAIL/SKIP results plus an overall verdict."
+argument-hint: "[--fix=false]"
+---
+
+Use the /lisa:doctor skill to audit whether the current repository is ready to use Lisa, report grouped PASS/WARN/FAIL/SKIP checks, and emit an overall readiness verdict. $ARGUMENTS

package/plugins/lisa/scripts/doctor-report.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Shared doctor report helpers for the base Lisa doctor surface.
+ *
+ * The first doctor milestone needs a stable grouped output contract before the
+ * repo adds real readiness probes. Keep this file dependency-free so future
+ * doctor scripts can reuse it from plugin distributions and downstream repos.
+ */
+
+export const DOCTOR_STATUSES = ["PASS", "WARN", "FAIL", "SKIP"];
+export const DOCTOR_VERDICTS = ["READY", "READY_WITH_WARNINGS", "NOT_READY"];
+
+/**
+ * @typedef {"PASS" | "WARN" | "FAIL" | "SKIP"} DoctorStatus
+ * @typedef {"READY" | "READY_WITH_WARNINGS" | "NOT_READY"} DoctorVerdict
+ *
+ * @typedef {{
+ *   readonly id: string
+ *   readonly status: DoctorStatus
+ *   readonly summary: string
+ *   readonly observed?: string
+ *   readonly remediation?: string
+ * }} DoctorCheck
+ *
+ * @typedef {{
+ *   readonly id: string
+ *   readonly title: string
+ *   readonly checks: readonly DoctorCheck[]
+ * }} DoctorGroup
+ *
+ * @typedef {{
+ *   readonly generatedAt?: string
+ *   readonly groups: readonly DoctorGroup[]
+ * }} DoctorReportInput
+ */
+
+/**
+ * @param {readonly DoctorGroup[]} groups
+ * @returns {DoctorVerdict}
+ */
+export function computeDoctorVerdict(groups) {
+  const checks = groups.flatMap(group => group.checks);
+  if (checks.some(check => check.status === "FAIL")) {
+    return "NOT_READY";
+  }
+  if (checks.some(check => check.status === "WARN")) {
+    return "READY_WITH_WARNINGS";
+  }
+  return "READY";
+}
+
+/**
+ * @param {readonly DoctorGroup[]} groups
+ * @returns {Record<DoctorStatus, number>}
+ */
+export function countDoctorStatuses(groups) {
+  return groups
+    .flatMap(group => group.checks)
+    .reduce(
+      (counts, check) => ({
+        ...counts,
+        [check.status]: counts[check.status] + 1,
+      }),
+      { PASS: 0, WARN: 0, FAIL: 0, SKIP: 0 }
+    );
+}
+
+/**
+ * @param {DoctorReportInput} input
+ * @returns {{ readonly verdict: DoctorVerdict, readonly counts: Record<DoctorStatus, number>, readonly text: string }}
+ */
+export function renderDoctorReport(input) {
+  const groups = input.groups.map(normalizeGroup);
+  const verdict = computeDoctorVerdict(groups);
+  const counts = countDoctorStatuses(groups);
+  const lines = [
+    `Overall verdict: ${verdict}`,
+    `Counts: ${DOCTOR_STATUSES.map(status => `${counts[status]} ${status}`).join(", ")}`,
+  ];
+
+  if (input.generatedAt) {
+    lines.push(`Generated at: ${input.generatedAt}`);
+  }
+
+  for (const group of groups) {
+    lines.push("", `${group.id}. ${group.title}`);
+    if (group.checks.length === 0) {
+      lines.push("- SKIP empty-group: no checks registered yet");
+      continue;
+    }
+    for (const check of group.checks) {
+      lines.push(`- ${check.status} ${check.id}: ${check.summary}`);
+      if (check.observed) {
+        lines.push(`  Observed: ${check.observed}`);
+      }
+      if (check.remediation) {
+        lines.push(`  Remediation: ${check.remediation}`);
+      }
+    }
+  }
+
+  return {
+    verdict,
+    counts,
+    text: `${lines.join("\n")}\n`,
+  };
+}
+
+/**
+ * @param {DoctorGroup} group
+ * @returns {DoctorGroup}
+ */
+function normalizeGroup(group) {
+  return {
+    ...group,
+    checks: group.checks.map(normalizeCheck),
+  };
+}
+
+/**
+ * @param {DoctorCheck} check
+ * @returns {DoctorCheck}
+ */
+function normalizeCheck(check) {
+  const normalizedStatus = DOCTOR_STATUSES.includes(check.status)
+    ? check.status
+    : "FAIL";
+  return {
+    ...check,
+    status: normalizedStatus,
+  };
+}

package/plugins/lisa/skills/doctor/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: doctor
+description: "Audit whether the current repository is ready to use Lisa. Runs grouped read-only checks across project detection, Lisa config, runtime distribution surfaces, tracker/source preflight access, automation prerequisites, optional GitHub Project coordination, and optional wiki delegation, then reports PASS/WARN/FAIL/SKIP results plus an overall readiness verdict (`READY`, `READY_WITH_WARNINGS`, or `NOT_READY`)."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# 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.
+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.
+
+If a check family is not applicable to the current repo, report `SKIP` with the reason.
+
+## 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`.
+
+## Delegation and reuse
+
+- Reuse `config-resolution` for config and lifecycle role defaults instead of inventing a second
+  schema.
+- Reuse the existing `github-project-v2` chokepoint for GitHub Project coordination checks instead
+  of inlining bespoke access logic.
+- Reuse ideas from `lisa-wiki-doctor` for grouped verdict rendering where they fit, while keeping
+  the Lisa-wide doctor narrower than the wiki-specific migration/readiness workflow.
+
+## Rules
+
+- Never mutate repository, tracker, or automation state on the default doctor path.
+- Never hardcode tracker/source label names outside the documented defaults plus configured
+  overrides from `config-resolution`.
+- Never silently treat an unavailable check surface as success; report `WARN`, `FAIL`, or `SKIP`
+  with the explicit missing dependency.
+- Never turn wiki-specific checks into a requirement for non-wiki repos.

package/plugins/lisa/skills/doctor/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Doctor"
+short_description: "Audit whether the current repository is ready to use Lisa"
+default_prompt:
+  - "Use $doctor: Audit whether the current repository is ready to use Lisa."

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.75.1",
+  "version": "2.77.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": "2.75.1",
+  "version": "2.77.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.75.1",
+  "version": "2.77.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.75.1",
+  "version": "2.77.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/src/base/commands/doctor.md

@@ -0,0 +1,6 @@
+---
+description: "Audit whether the current repository is ready to use Lisa. Runs grouped read-only readiness checks for config, runtime surfaces, tracker/source access, automation prerequisites, and optional project/wiki coordination, then reports PASS/WARN/FAIL/SKIP results plus an overall verdict."
+argument-hint: "[--fix=false]"
+---
+
+Use the /lisa:doctor skill to audit whether the current repository is ready to use Lisa, report grouped PASS/WARN/FAIL/SKIP checks, and emit an overall readiness verdict. $ARGUMENTS

package/plugins/src/base/scripts/doctor-report.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Shared doctor report helpers for the base Lisa doctor surface.
+ *
+ * The first doctor milestone needs a stable grouped output contract before the
+ * repo adds real readiness probes. Keep this file dependency-free so future
+ * doctor scripts can reuse it from plugin distributions and downstream repos.
+ */
+
+export const DOCTOR_STATUSES = ["PASS", "WARN", "FAIL", "SKIP"];
+export const DOCTOR_VERDICTS = ["READY", "READY_WITH_WARNINGS", "NOT_READY"];
+
+/**
+ * @typedef {"PASS" | "WARN" | "FAIL" | "SKIP"} DoctorStatus
+ * @typedef {"READY" | "READY_WITH_WARNINGS" | "NOT_READY"} DoctorVerdict
+ *
+ * @typedef {{
+ *   readonly id: string
+ *   readonly status: DoctorStatus
+ *   readonly summary: string
+ *   readonly observed?: string
+ *   readonly remediation?: string
+ * }} DoctorCheck
+ *
+ * @typedef {{
+ *   readonly id: string
+ *   readonly title: string
+ *   readonly checks: readonly DoctorCheck[]
+ * }} DoctorGroup
+ *
+ * @typedef {{
+ *   readonly generatedAt?: string
+ *   readonly groups: readonly DoctorGroup[]
+ * }} DoctorReportInput
+ */
+
+/**
+ * @param {readonly DoctorGroup[]} groups
+ * @returns {DoctorVerdict}
+ */
+export function computeDoctorVerdict(groups) {
+  const checks = groups.flatMap(group => group.checks);
+  if (checks.some(check => check.status === "FAIL")) {
+    return "NOT_READY";
+  }
+  if (checks.some(check => check.status === "WARN")) {
+    return "READY_WITH_WARNINGS";
+  }
+  return "READY";
+}
+
+/**
+ * @param {readonly DoctorGroup[]} groups
+ * @returns {Record<DoctorStatus, number>}
+ */
+export function countDoctorStatuses(groups) {
+  return groups
+    .flatMap(group => group.checks)
+    .reduce(
+      (counts, check) => ({
+        ...counts,
+        [check.status]: counts[check.status] + 1,
+      }),
+      { PASS: 0, WARN: 0, FAIL: 0, SKIP: 0 }
+    );
+}
+
+/**
+ * @param {DoctorReportInput} input
+ * @returns {{ readonly verdict: DoctorVerdict, readonly counts: Record<DoctorStatus, number>, readonly text: string }}
+ */
+export function renderDoctorReport(input) {
+  const groups = input.groups.map(normalizeGroup);
+  const verdict = computeDoctorVerdict(groups);
+  const counts = countDoctorStatuses(groups);
+  const lines = [
+    `Overall verdict: ${verdict}`,
+    `Counts: ${DOCTOR_STATUSES.map(status => `${counts[status]} ${status}`).join(", ")}`,
+  ];
+
+  if (input.generatedAt) {
+    lines.push(`Generated at: ${input.generatedAt}`);
+  }
+
+  for (const group of groups) {
+    lines.push("", `${group.id}. ${group.title}`);
+    if (group.checks.length === 0) {
+      lines.push("- SKIP empty-group: no checks registered yet");
+      continue;
+    }
+    for (const check of group.checks) {
+      lines.push(`- ${check.status} ${check.id}: ${check.summary}`);
+      if (check.observed) {
+        lines.push(`  Observed: ${check.observed}`);
+      }
+      if (check.remediation) {
+        lines.push(`  Remediation: ${check.remediation}`);
+      }
+    }
+  }
+
+  return {
+    verdict,
+    counts,
+    text: `${lines.join("\n")}\n`,
+  };
+}
+
+/**
+ * @param {DoctorGroup} group
+ * @returns {DoctorGroup}
+ */
+function normalizeGroup(group) {
+  return {
+    ...group,
+    checks: group.checks.map(normalizeCheck),
+  };
+}
+
+/**
+ * @param {DoctorCheck} check
+ * @returns {DoctorCheck}
+ */
+function normalizeCheck(check) {
+  const normalizedStatus = DOCTOR_STATUSES.includes(check.status)
+    ? check.status
+    : "FAIL";
+  return {
+    ...check,
+    status: normalizedStatus,
+  };
+}

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

@@ -0,0 +1,114 @@
+---
+name: doctor
+description: "Audit whether the current repository is ready to use Lisa. Runs grouped read-only checks across project detection, Lisa config, runtime distribution surfaces, tracker/source preflight access, automation prerequisites, optional GitHub Project coordination, and optional wiki delegation, then reports PASS/WARN/FAIL/SKIP results plus an overall readiness verdict (`READY`, `READY_WITH_WARNINGS`, or `NOT_READY`)."
+allowed-tools: ["Skill", "Bash", "Read", "Glob", "Grep"]
+---
+
+# 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.
+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.
+
+If a check family is not applicable to the current repo, report `SKIP` with the reason.
+
+## 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`.
+
+## Delegation and reuse
+
+- Reuse `config-resolution` for config and lifecycle role defaults instead of inventing a second
+  schema.
+- Reuse the existing `github-project-v2` chokepoint for GitHub Project coordination checks instead
+  of inlining bespoke access logic.
+- Reuse ideas from `lisa-wiki-doctor` for grouped verdict rendering where they fit, while keeping
+  the Lisa-wide doctor narrower than the wiki-specific migration/readiness workflow.
+
+## Rules
+
+- Never mutate repository, tracker, or automation state on the default doctor path.
+- Never hardcode tracker/source label names outside the documented defaults plus configured
+  overrides from `config-resolution`.
+- Never silently treat an unavailable check surface as success; report `WARN`, `FAIL`, or `SKIP`
+  with the explicit missing dependency.
+- Never turn wiki-specific checks into a requirement for non-wiki repos.