@codyswann/lisa 2.76.0 → 2.77.1

package/package.json

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

package/plugins/lisa/rules/config-resolution.md

@@ -398,6 +398,37 @@ For batch skills that consume `source`:
 2. If `$ARGUMENTS` is the bare token `notion` / `confluence` / `linear` / `github` / `jira`, the source is that vendor; resolve location from the corresponding config section.
 3. If `$ARGUMENTS` is empty, fall back to `source` from config; if that's also empty, stop and report `"No source specified and no 'source' field in .lisa.config.json."`
 
+### Doctor config readiness
+
+`/lisa:doctor` reads the same config, but it audits readiness instead of dispatching a write.
+Doctor must validate config in three layers:
+
+1. **Parse and merge**
+   - Parse both config files as JSON. Missing or invalid `.lisa.config.json` is a blocking error.
+     `.lisa.config.local.json` is optional, but if present and invalid it is also a blocking error.
+   - Merge per key with the standard local-overrides-global rule. Doctor reports against the merged
+     effective config; it does not treat the local file as a full replacement for the committed
+     file.
+2. **Required-key correctness**
+   - Missing `tracker` after merge is a blocking error. Unknown merged `tracker` / `source` values
+     are also blocking errors.
+   - If the configured tracker/source vendor is missing its required keys after merge, doctor must
+     report a blocking readiness failure using the vendor tables above. Examples: `tracker=github`
+     requires `github.org` + `github.repo`; `tracker=jira` requires `atlassian.cloudId` +
+     `jira.project`; `source=notion` requires `notion.workspaceId` + `notion.prdDatabaseId`.
+3. **Field locality correctness**
+   - `atlassian.email`, `intake.assignee`, and `jira.verified_workflow_hash` are local-only. If
+     they appear in committed config, doctor warns that developer-specific state was checked into
+     the project file.
+   - Project-wide fields that exist only in `.lisa.config.local.json` should warn, not pass
+     silently. Current machine works, repository not durably configured for teammates and
+     automations. Common examples include `tracker`, `source`, `github.org`, `github.repo`,
+     `atlassian.cloudId`, `atlassian.site`, `jira.project`, `linear.workspace`, `linear.teamKey`,
+     and `deploy.branches`.
+
+Doctor's severity rule is simple: unusable merged config is `FAIL`; locality drift with a still
+usable merged config is `WARN`.
+
 ## Skill mapping
 
 The shim → vendor mapping is fixed:

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

@@ -69,6 +69,41 @@ as applicable to the current repo:
 
 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`.
+
+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`.
+
 ## Output contract
 
 The final report must:
@@ -78,6 +113,17 @@ The final report must:
 - 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`.

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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.76.0",
+  "version": "2.77.1",
   "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/rules/config-resolution.md

@@ -398,6 +398,37 @@ For batch skills that consume `source`:
 2. If `$ARGUMENTS` is the bare token `notion` / `confluence` / `linear` / `github` / `jira`, the source is that vendor; resolve location from the corresponding config section.
 3. If `$ARGUMENTS` is empty, fall back to `source` from config; if that's also empty, stop and report `"No source specified and no 'source' field in .lisa.config.json."`
 
+### Doctor config readiness
+
+`/lisa:doctor` reads the same config, but it audits readiness instead of dispatching a write.
+Doctor must validate config in three layers:
+
+1. **Parse and merge**
+   - Parse both config files as JSON. Missing or invalid `.lisa.config.json` is a blocking error.
+     `.lisa.config.local.json` is optional, but if present and invalid it is also a blocking error.
+   - Merge per key with the standard local-overrides-global rule. Doctor reports against the merged
+     effective config; it does not treat the local file as a full replacement for the committed
+     file.
+2. **Required-key correctness**
+   - Missing `tracker` after merge is a blocking error. Unknown merged `tracker` / `source` values
+     are also blocking errors.
+   - If the configured tracker/source vendor is missing its required keys after merge, doctor must
+     report a blocking readiness failure using the vendor tables above. Examples: `tracker=github`
+     requires `github.org` + `github.repo`; `tracker=jira` requires `atlassian.cloudId` +
+     `jira.project`; `source=notion` requires `notion.workspaceId` + `notion.prdDatabaseId`.
+3. **Field locality correctness**
+   - `atlassian.email`, `intake.assignee`, and `jira.verified_workflow_hash` are local-only. If
+     they appear in committed config, doctor warns that developer-specific state was checked into
+     the project file.
+   - Project-wide fields that exist only in `.lisa.config.local.json` should warn, not pass
+     silently. Current machine works, repository not durably configured for teammates and
+     automations. Common examples include `tracker`, `source`, `github.org`, `github.repo`,
+     `atlassian.cloudId`, `atlassian.site`, `jira.project`, `linear.workspace`, `linear.teamKey`,
+     and `deploy.branches`.
+
+Doctor's severity rule is simple: unusable merged config is `FAIL`; locality drift with a still
+usable merged config is `WARN`.
+
 ## Skill mapping
 
 The shim → vendor mapping is fixed:

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

@@ -69,6 +69,41 @@ as applicable to the current repo:
 
 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`.
+
+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`.
+
 ## Output contract
 
 The final report must:
@@ -78,6 +113,17 @@ The final report must:
 - 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`.