@esneiderbravo/speclaw 0.3.5 → 0.3.8

package/dist/modules/foundation/doctor.js

@@ -1,218 +1,674 @@
 import fs from "node:fs";
 import path from "node:path";
 import { AGENTS, agentById, detectConfiguredAgents } from "../../shared/agents.js";
-import { isMinimalMode } from "../../shared/exposure.js";
+import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
+import { isGitRepo } from "../../shared/git.js";
+import { readManifest } from "../../shared/manifest.js";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+import { indexExists, openDb } from "../compass/db.js";
+import { specList } from "../lawbook/engine.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
-/**
- * Run the speclaw installation health checks against a project: ai-specs and
- * LAWS.md presence, agent contracts, the docs/standards set, per-agent IDE
- * symlink health, the lawbook/ workflow, the Compass index, and .mcp.json wiring.
- *
- * @param projectPath - Absolute path to the project root.
- * @returns One {@link Check} per verified item, each carrying a remediation hint.
- */
-export function doctor(projectPath) {
+import { redactValue } from "../../shared/redact.js";
+const STATUS_RANK = {
+    skip: 0,
+    ok: 1,
+    warn: 2,
+    error: 3,
+};
+/** Worst status among a list (`error` > `warn` > `ok` > `skip`). */
+export function worstStatus(statuses) {
+    let worst = "skip";
+    for (const s of statuses) {
+        if (STATUS_RANK[s] > STATUS_RANK[worst])
+            worst = s;
+    }
+    return worst;
+}
+function sectionOf(id, checks) {
+    return { id, status: worstStatus(checks.map((c) => c.status)), checks };
+}
+function detectInstallKind() {
+    const argv1 = process.argv[1] ?? "";
+    if (argv1.includes("_npx") ||
+        argv1.includes(`${path.sep}npx${path.sep}`) ||
+        process.env.npm_command === "exec") {
+        return "npx";
+    }
+    if (argv1.includes(`${path.sep}node_modules${path.sep}`))
+        return "local";
+    if (argv1.includes(`${path.sep}bin${path.sep}`) || argv1.includes(`${path.sep}.npm-global`)) {
+        return "global";
+    }
+    return "unknown";
+}
+function enginesRequirement() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
+        return pkg.engines?.node ?? ">=22";
+    }
+    catch {
+        return ">=22";
+    }
+}
+function nodeSatisfies(required, version) {
+    const m = /^>=\s*(\d+)/.exec(required.trim());
+    if (!m)
+        return true;
+    const major = parseInt(version.replace(/^v/, "").split(".")[0], 10);
+    return major >= parseInt(m[1], 10);
+}
+function libcLabel() {
+    if (process.platform !== "linux")
+        return "";
+    try {
+        const report = process.report;
+        const r = report?.getReport?.();
+        if (r?.header?.glibcVersionRuntime)
+            return `glibc ${r.header.glibcVersionRuntime}`;
+    }
+    catch {
+        /* ignore */
+    }
+    return "libc unknown";
+}
+function addCheck(checks, partial) {
+    if ((partial.status === "warn" || partial.status === "error") && !partial.remedy) {
+        // Spec: no remedy → demote to notes-style ok detail rather than a false warn.
+        checks.push({ ...partial, status: "ok", remedy: undefined });
+        return;
+    }
+    checks.push(partial);
+}
+/** The law ids recorded as loaded into agent context, from the append-only log. */
+function loadedLawIds(projectPath) {
+    const loaded = new Set();
+    try {
+        const log = fs.readFileSync(path.join(projectPath, ".speclaw", "context-log.jsonl"), "utf8");
+        for (const line of log.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            const ids = JSON.parse(line).lawIds ?? [];
+            for (const id of ids)
+                loaded.add(id);
+        }
+    }
+    catch {
+        /* no log yet */
+    }
+    return loaded;
+}
+function readIndexedAt(projectPath) {
+    if (!indexExists(projectPath))
+        return null;
+    try {
+        const db = openDb(projectPath);
+        try {
+            const row = db.prepare("SELECT value FROM meta WHERE key = 'indexed_at'").get();
+            return row?.value ?? null;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+function countFilesNewerThan(projectPath, sinceMs) {
+    if (!indexExists(projectPath))
+        return 0;
+    try {
+        const db = openDb(projectPath);
+        try {
+            const rows = db.prepare("SELECT path FROM files").all();
+            let n = 0;
+            for (const r of rows) {
+                try {
+                    if (fs.statSync(path.join(projectPath, r.path)).mtimeMs > sinceMs)
+                        n++;
+                }
+                catch {
+                    /* deleted */
+                }
+            }
+            return n;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return 0;
+    }
+}
+function environmentChecks() {
     const checks = [];
-    const has = (rel) => fs.existsSync(path.join(projectPath, rel));
-    checks.push({
-        name: "ai-specs directory",
-        ok: has("ai-specs"),
-        detail: has("ai-specs") ? "present" : "missing — run the scaffold tool first",
+    const required = enginesRequirement();
+    const okNode = nodeSatisfies(required, process.version);
+    addCheck(checks, {
+        id: "env.node",
+        title: "node",
+        status: okNode ? "ok" : "error",
+        value: process.version,
+        detail: `${process.version} (requires ${required})`,
+        remedy: okNode ? undefined : `Install Node.js ${required} (https://nodejs.org)`,
     });
-    checks.push({
-        name: "LAWS.md constitution",
-        ok: has("LAWS.md"),
-        detail: has("LAWS.md") ? "present" : "missing — the project has no law",
+    const libc = libcLabel();
+    addCheck(checks, {
+        id: "env.platform",
+        title: "platform",
+        status: "ok",
+        value: `${process.platform} ${process.arch}`,
+        detail: [process.platform, process.arch, libc].filter(Boolean).join(" "),
     });
-    for (const entry of ["CLAUDE.md", "AGENTS.md", "docs/compass.md"]) {
-        checks.push({
-            name: `${entry} agent contract`,
-            ok: has(entry),
-            detail: has(entry) ? "present" : "missing — scaffold writes it",
-        });
-    }
-    const standards = [
-        "base-standards",
-        "architecture",
-        "backend-standards",
-        "frontend-standards",
-        "testing-standards",
-        "documentation",
-        "conventions",
-        "lawbook",
-    ];
-    const missingStandards = standards.filter((s) => !has(path.join("docs/standards", `${s}.md`)));
-    checks.push({
-        name: "docs/standards/*",
-        ok: missingStandards.length === 0,
-        detail: missingStandards.length === 0
-            ? `all ${standards.length} standards present`
-            : `missing: ${missingStandards.join(", ")}`,
+    // Filled by caller with projectPath — placeholder; see buildEnvironment.
+    return checks;
+}
+function buildEnvironment(projectPath) {
+    const checks = environmentChecks();
+    const git = isGitRepo(projectPath);
+    addCheck(checks, {
+        id: "env.git",
+        title: "git",
+        status: git ? "ok" : "warn",
+        value: git,
+        detail: git ? "repository" : "not a git repository",
+        remedy: git ? undefined : "git init",
     });
-    // Only check the agents the user actually configured — selection is opt-in.
+    addCheck(checks, {
+        id: "env.ast-engine",
+        title: "ast engine",
+        status: "skip",
+        detail: "@ast-grep/napi not shipped yet — skip until executable-laws wires it",
+        remedy: "speclaw update",
+    });
+    return checks;
+}
+function symlinkChecks(projectPath) {
+    const has = (rel) => fs.existsSync(path.join(projectPath, rel));
     const configured = AGENTS.filter((a) => detectConfiguredAgents(projectPath).includes(a.id));
     if (configured.length === 0) {
-        checks.push({
-            name: "agents",
-            ok: false,
-            detail: "none configured — run `speclaw init` or `speclaw agent add <id>`",
-        });
+        return {
+            id: "cfg.symlinks",
+            title: "agent surfaces",
+            status: "warn",
+            detail: "none configured",
+            remedy: "speclaw init",
+        };
     }
+    const broken = [];
+    let linkCount = 0;
     for (const agent of configured) {
         for (const target of agent.linkTargets) {
-            // only demand links for content that actually exists in ai-specs/
             if (!has(path.join("ai-specs", target)))
                 continue;
-            const ideDir = agent.ideDir;
-            const linkPath = path.join(projectPath, ideDir, target);
-            let ok = false;
-            let detail = "missing";
+            const linkPath = path.join(projectPath, agent.ideDir, target);
+            linkCount++;
             try {
                 const stat = fs.lstatSync(linkPath);
                 if (stat.isSymbolicLink()) {
-                    ok = fs.existsSync(linkPath); // broken symlink -> false
-                    detail = ok ? `-> ${fs.readlinkSync(linkPath)}` : "broken symlink";
-                }
-                else {
-                    ok = true;
-                    detail = "real directory (not a symlink — consider migrating to ai-specs)";
+                    if (!fs.existsSync(linkPath))
+                        broken.push(`${agent.ideDir}/${target}`);
                 }
             }
             catch {
-                // stays missing
+                broken.push(`${agent.ideDir}/${target}`);
             }
-            checks.push({ name: `${ideDir}/${target}`, ok, detail });
         }
     }
-    checks.push({
-        name: "lawbook workflow",
-        ok: has("lawbook"),
-        detail: has("lawbook") ? "lawbook/ present" : "missing — run the `lawbook_init` tool",
-    });
-    checks.push({
-        name: "Compass index",
-        ok: has(".speclaw/index.db"),
-        detail: has(".speclaw/index.db")
-            ? ".speclaw/index.db present"
-            : "missing — run the `compass_index` tool",
-    });
-    checks.push({
-        name: ".mcp.json wiring",
-        ok: has(".mcp.json"),
-        detail: has(".mcp.json") ? "present" : "missing — scaffold writes it",
-    });
-    lawEnforcementChecks(projectPath, checks);
-    const minimal = isMinimalMode(projectPath);
-    checks.push({
-        name: "exposure profile",
-        ok: true,
-        detail: minimal
-            ? "minimal — setup/lifecycle MCP tools are omitted from registration"
-            : "full — all MCP tools registered (no server-side defer_loading)",
-    });
-    return checks;
+    if (broken.length) {
+        return {
+            id: "cfg.symlinks",
+            title: "agent surfaces",
+            status: "error",
+            value: broken.join(", "),
+            detail: `${configured.length} configured · broken: ${broken.join(", ")}`,
+            remedy: "speclaw update",
+        };
+    }
+    return {
+        id: "cfg.symlinks",
+        title: "agent surfaces",
+        status: "ok",
+        detail: `${configured.length} configured, ${linkCount} link(s) intact`,
+    };
 }
-/** The law ids recorded as loaded into agent context, from the append-only log. */
-function loadedLawIds(projectPath) {
-    const loaded = new Set();
+async function mcpCheckAsync(projectPath, agentId) {
+    const agent = agentById(agentId);
+    const id = `cfg.mcp.${agentId}`;
+    const title = `mcp · ${agentId}`;
+    if (!agent.mcpFile) {
+        return {
+            id,
+            title,
+            status: "skip",
+            detail: `${agent.label} has no MCP config surface`,
+        };
+    }
+    const mcpPath = path.join(projectPath, agent.mcpFile);
+    if (!fs.existsSync(mcpPath)) {
+        return {
+            id,
+            title,
+            status: "warn",
+            detail: "not configured",
+            remedy: `speclaw agent add ${agentId}`,
+        };
+    }
+    let entry;
     try {
-        const log = fs.readFileSync(path.join(projectPath, ".speclaw", "context-log.jsonl"), "utf8");
-        for (const line of log.split(/\r?\n/)) {
-            if (!line.trim())
-                continue;
-            const ids = JSON.parse(line).lawIds ?? [];
-            for (const id of ids)
-                loaded.add(id);
-        }
+        const cfg = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+        entry = cfg.mcpServers?.speclaw;
     }
     catch {
-        // No log yet — hooks have not recorded any context loads.
+        return {
+            id,
+            title,
+            status: "warn",
+            detail: "MCP config unreadable",
+            remedy: `speclaw agent add ${agentId}`,
+        };
+    }
+    if (!entry) {
+        return {
+            id,
+            title,
+            status: "warn",
+            detail: "not configured (no speclaw server entry)",
+            remedy: `speclaw agent add ${agentId}`,
+        };
+    }
+    try {
+        const { collectRegisteredTools } = await import("./context-budget.js");
+        const tools = collectRegisteredTools(isMinimalMode(projectPath));
+        return {
+            id,
+            title,
+            status: "ok",
+            value: tools.length,
+            detail: `reachable (self-probe), ${tools.length} tools`,
+        };
+    }
+    catch (err) {
+        return {
+            id,
+            title,
+            status: "warn",
+            detail: `configured but probe failed: ${err.message}`,
+            remedy: `speclaw agent add ${agentId}`,
+        };
     }
-    return loaded;
 }
-/**
- * Append the law-enforcement health checks: manifest presence and backend
- * coverage, glob validity (caught here rather than at runtime), context-coverage
- * with the post-compact caveat, and the agents where blocking laws don't apply.
- */
-function lawEnforcementChecks(projectPath, checks) {
+/** Semver compare — true when `latest` is strictly newer than `current`. */
+function isNewerVersion(latest, current) {
+    const parse = (v) => v
+        .split("-")[0]
+        .split(".")
+        .map((n) => parseInt(n, 10) || 0);
+    const a = parse(latest);
+    const b = parse(current);
+    for (let i = 0; i < 3; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return false;
+}
+async function fetchLatestVersion(name) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const url = `https://registry.npmjs.org/${name.replace("/", "%2F")}/latest`;
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function lawsCheck(projectPath) {
     const manifest = readLawManifest(projectPath);
     if (!manifest) {
-        checks.push({
-            name: "law manifest",
-            ok: false,
-            detail: "missing — run `speclaw init`/`update` to seed .speclaw/laws-manifest.json",
-        });
-        return;
+        return {
+            id: "cfg.laws",
+            title: "laws",
+            status: "warn",
+            detail: "manifest missing",
+            remedy: "speclaw update",
+        };
     }
-    const withPath = manifest.laws.filter(hasBackend);
-    const withBatch = manifest.laws.filter(hasBatchBackend);
-    const noBackend = manifest.laws.filter((l) => !hasBackend(l) && !hasBatchBackend(l));
-    checks.push({
-        name: "law manifest",
-        ok: true,
-        detail: `${manifest.laws.length} law(s): ${withPath.length} enforced (path), ` +
-            `${withBatch.length} verified (deps/graph)` +
-            (noBackend.length
-                ? `, ${noBackend.length} declared without a backend yet (${noBackend
-                    .map((l) => l.id)
-                    .join(", ")})`
-                : ""),
-    });
-    // Graph-engine availability — the deps/graph backends need the Compass index.
-    if (withBatch.length > 0) {
-        const indexed = fs.existsSync(path.join(projectPath, ".speclaw", "index.db"));
-        checks.push({
-            name: "graph law engines",
-            ok: indexed,
-            detail: indexed
-                ? `index present — ${withBatch.length} deps/graph law(s) evaluable via \`speclaw laws verify\``
-                : `${withBatch.length} deps/graph law(s) will be skipped (no-index) — run the \`compass_index\` tool`,
-        });
-    }
-    // Glob validation — a malformed scope glob must fail loudly here, never
-    // silently match zero files at runtime. (A malformed deps/graph regex is
-    // rejected earlier, when the manifest is validated, so a manifest that reaches
-    // here has none.)
     const badGlobs = [];
     for (const law of manifest.laws) {
         for (const pattern of law.scope) {
             const err = globError(pattern);
             if (err)
-                badGlobs.push(`${law.id}: ${pattern} (${err})`);
+                badGlobs.push(`${law.id}: ${pattern}`);
         }
     }
-    checks.push({
-        name: "law scope globs",
-        ok: badGlobs.length === 0,
-        detail: badGlobs.length === 0 ? "all valid" : `malformed: ${badGlobs.join("; ")}`,
+    if (badGlobs.length) {
+        return {
+            id: "cfg.laws",
+            title: "laws",
+            status: "error",
+            detail: `invalid globs: ${badGlobs.join("; ")}`,
+            remedy: "Fix scope globs in .speclaw/laws-manifest.json",
+        };
+    }
+    const withPath = manifest.laws.filter(hasBackend).length;
+    const withBatch = manifest.laws.filter(hasBatchBackend).length;
+    return {
+        id: "cfg.laws",
+        title: "laws",
+        status: "ok",
+        value: manifest.laws.length,
+        detail: `${manifest.laws.length} declared · ${withPath} path · ${withBatch} deps/graph · 0 invalid`,
+    };
+}
+async function budgetCheck(projectPath) {
+    try {
+        const { measureInstallBudget } = await import("./context-budget.js");
+        const m = measureInstallBudget(projectPath);
+        return {
+            id: "cfg.budget",
+            title: "context cost",
+            status: "ok",
+            value: m.total,
+            detail: `~${m.total} always-on tokens (${m.profile}, ${m.toolCount} tools)`,
+        };
+    }
+    catch (err) {
+        return {
+            id: "cfg.budget",
+            title: "context cost",
+            status: "skip",
+            detail: `could not measure: ${err.message}`,
+            remedy: "speclaw budget",
+        };
+    }
+}
+function freshnessCheck(projectPath) {
+    if (!indexExists(projectPath)) {
+        return {
+            id: "cfg.index.freshness",
+            title: "index freshness",
+            status: "warn",
+            detail: "no index",
+            remedy: "speclaw index",
+        };
+    }
+    const indexedAt = readIndexedAt(projectPath);
+    if (!indexedAt) {
+        return {
+            id: "cfg.index.freshness",
+            title: "index freshness",
+            status: "skip",
+            detail: "meta.indexed_at absent (index from an older speclaw)",
+            remedy: "speclaw index",
+        };
+    }
+    const sinceMs = Date.parse(indexedAt);
+    if (Number.isNaN(sinceMs)) {
+        return {
+            id: "cfg.index.freshness",
+            title: "index freshness",
+            status: "skip",
+            detail: "meta.indexed_at unparseable",
+            remedy: "speclaw index",
+        };
+    }
+    const ageDays = (Date.now() - sinceMs) / (24 * 60 * 60 * 1000);
+    const changed = countFilesNewerThan(projectPath, sinceMs);
+    const stale = ageDays > 7 && changed > 0;
+    return {
+        id: "cfg.index.freshness",
+        title: "index freshness",
+        status: stale ? "warn" : "ok",
+        value: Math.floor(ageDays),
+        detail: `${Math.floor(ageDays)} day(s) old · ${changed} file(s) newer than index`,
+        remedy: stale ? "speclaw index" : undefined,
+    };
+}
+function specsOrphansCheck(projectPath) {
+    const list = specList(projectPath);
+    if (!list.initialized) {
+        return {
+            id: "cfg.specs.orphans",
+            title: "specs",
+            status: "skip",
+            detail: "lawbook not initialised",
+            remedy: "speclaw lawbook init",
+        };
+    }
+    const active = list.activeChanges;
+    if (active.length === 0) {
+        return {
+            id: "cfg.specs.orphans",
+            title: "specs",
+            status: "ok",
+            detail: "no active changes",
+        };
+    }
+    return {
+        id: "cfg.specs.orphans",
+        title: "specs",
+        status: "warn",
+        value: active.join(", "),
+        detail: `${active.length} change(s) not archived: ${active.join(", ")}`,
+        remedy: `speclaw lawbook archive ${active[0]}`,
+    };
+}
+function configurationChecks(projectPath, initialised) {
+    if (!initialised) {
+        const ids = [
+            "cfg.manifest",
+            "cfg.ownership",
+            "cfg.symlinks",
+            "cfg.hooks",
+            "cfg.laws",
+            "cfg.budget",
+            "cfg.index.freshness",
+            "cfg.specs.orphans",
+        ];
+        return ids.map((id) => ({
+            id,
+            title: id.replace(/^cfg\./, ""),
+            status: "skip",
+            detail: "project not initialised",
+            remedy: "speclaw init",
+        }));
+    }
+    const checks = [];
+    const manifest = readManifest(projectPath);
+    addCheck(checks, {
+        id: "cfg.manifest",
+        title: "manifest",
+        status: manifest ? "ok" : "warn",
+        detail: manifest ? `.speclaw.json (written by ${manifest.version})` : "missing .speclaw.json",
+        remedy: manifest ? undefined : "speclaw init",
+    });
+    addCheck(checks, {
+        id: "cfg.ownership",
+        title: "managed files",
+        status: "skip",
+        detail: "content-hash inventory not available yet — skip",
+        remedy: "speclaw update",
     });
-    // Context coverage — which laws actually entered the agent's context.
+    checks.push(symlinkChecks(projectPath));
+    addCheck(checks, {
+        id: "cfg.hooks",
+        title: "hooks",
+        status: "skip",
+        detail: "see notes.compact / law context coverage — no dedicated hooks probe yet",
+        remedy: "speclaw update",
+    });
+    checks.push(lawsCheck(projectPath));
+    // budget + mcp + freshness + specs filled async by caller
+    return checks;
+}
+function notesSection(projectPath) {
+    const checks = [];
     const loaded = loadedLawIds(projectPath);
-    const declared = manifest.laws.map((l) => l.id);
+    const manifest = readLawManifest(projectPath);
+    const declared = manifest?.laws.map((l) => l.id) ?? [];
     const missing = declared.filter((id) => !loaded.has(id));
-    checks.push({
-        name: "law context coverage",
-        ok: true,
-        detail: `${declared.length - missing.length} of ${declared.length} laws loaded into context` +
-            (missing.length ? ` — not yet loaded: ${missing.join(", ")}` : "") +
-            ". Note: after a compact, root CLAUDE.md is re-injected but `paths:`-scoped rules are not," +
-            " until a matching file is next touched — so a path-scoped law can be out of context" +
-            " exactly when it matters, which is why it is also a hook.",
+    addCheck(checks, {
+        id: "notes.compact",
+        title: "post-compact rules",
+        status: "ok",
+        detail: "Rules with `paths:` are NOT re-injected after a context compact. " +
+            (manifest
+                ? `${declared.length - missing.length}/${declared.length} laws seen in context-log.`
+                : "No law manifest."),
     });
-    // Agent asymmetry — where blocking laws cannot be enforced at the keystroke.
     const configured = detectConfiguredAgents(projectPath);
-    const unhooked = configured
-        .map((id) => agentById(id))
-        .filter((a) => a && !a.hooks)
-        .map((a) => a.label);
-    if (unhooked.length) {
-        const blocking = manifest.laws.filter((l) => l.enforcement === "bloqueo").length;
-        checks.push({
-            name: "hook coverage across agents",
-            ok: true,
-            detail: `no hook support for ${unhooked.join(", ")} — your ${blocking} blocking law(s) apply ` +
-                "there only via `speclaw verify`.",
+    const caps = AGENTS.map((a) => {
+        const on = configured.includes(a.id);
+        return `${a.id}: hooks=${a.hooks ? "yes" : "no"} mcp=${a.mcpFile ? "yes" : "no"}${on ? " (configured)" : ""}`;
+    });
+    addCheck(checks, {
+        id: "notes.capabilities",
+        title: "agent capabilities",
+        status: "ok",
+        detail: caps.join("; "),
+    });
+    return checks;
+}
+/**
+ * Build the versioned diagnostic report for a project.
+ *
+ * @param projectPath - Absolute project root.
+ * @param opts - Offline / redaction options.
+ */
+export async function doctor(projectPath, opts = {}) {
+    const redact = opts.redact !== false;
+    const offline = Boolean(opts.offline);
+    const initialised = Boolean(readManifest(projectPath)) || fs.existsSync(path.join(projectPath, "LAWS.md"));
+    const environment = buildEnvironment(projectPath);
+    const configuration = configurationChecks(projectPath, initialised);
+    if (initialised) {
+        configuration.push(await budgetCheck(projectPath));
+        configuration.push(freshnessCheck(projectPath));
+        configuration.push(specsOrphansCheck(projectPath));
+        const configured = detectConfiguredAgents(projectPath);
+        const mcpAgents = AGENTS.filter((a) => a.mcpFile && configured.includes(a.id));
+        if (mcpAgents.length === 0) {
+            // Still report one representative unconfigured surface when agents exist without mcp.
+            const withMcp = AGENTS.filter((a) => a.mcpFile);
+            for (const a of withMcp.slice(0, 1)) {
+                configuration.push(await mcpCheckAsync(projectPath, a.id));
+            }
+        }
+        else {
+            for (const a of mcpAgents) {
+                configuration.push(await mcpCheckAsync(projectPath, a.id));
+            }
+        }
+    }
+    const authentication = [
+        {
+            id: "auth.none",
+            title: "credentials",
+            status: "ok",
+            detail: "none — speclaw stores no credentials and runs fully local",
+        },
+    ];
+    const connectivity = [];
+    if (offline) {
+        connectivity.push({
+            id: "conn.registry",
+            title: "npm registry",
+            status: "skip",
+            detail: "skipped (--offline)",
+            remedy: "speclaw doctor",
         });
     }
+    else {
+        const current = pkgVersion();
+        const latest = await fetchLatestVersion(pkgName());
+        if (!latest) {
+            connectivity.push({
+                id: "conn.registry",
+                title: "npm registry",
+                status: "skip",
+                detail: "registry unreachable",
+                remedy: "speclaw doctor --offline",
+            });
+        }
+        else if (isNewerVersion(latest, current)) {
+            connectivity.push({
+                id: "conn.registry",
+                title: "npm registry",
+                status: "warn",
+                value: latest,
+                detail: `${current} installed, ${latest} available`,
+                remedy: "npx @esneiderbravo/speclaw@latest update",
+            });
+        }
+        else {
+            connectivity.push({
+                id: "conn.registry",
+                title: "npm registry",
+                status: "ok",
+                detail: `${current} installed (latest)`,
+            });
+        }
+    }
+    connectivity.push({
+        id: "conn.egress",
+        title: "outbound requests",
+        status: "ok",
+        value: 1,
+        detail: "1 possible: npm version check (disable with --offline). No analytics, no authenticated calls.",
+    });
+    const notes = notesSection(projectPath);
+    const sections = [
+        sectionOf("environment", environment),
+        sectionOf("configuration", configuration),
+        sectionOf("authentication", authentication),
+        sectionOf("connectivity", connectivity),
+        sectionOf("notes", notes),
+    ];
+    let report = {
+        schemaVersion: 1,
+        generatedAt: new Date().toISOString(),
+        speclaw: {
+            version: pkgVersion(),
+            mode: isMinimalMode(projectPath) ? "minimal" : "full",
+            installKind: detectInstallKind(),
+        },
+        status: worstStatus(sections.map((s) => s.status)),
+        redacted: redact,
+        sections,
+    };
+    if (redact) {
+        report = redactValue(report, projectPath);
+        report.redacted = true;
+    }
+    return report;
+}
+/**
+ * Flatten checks for legacy callers that still expect a name/ok/detail list.
+ * Prefer {@link doctor} + {@link DoctorReport}.
+ */
+export function flattenChecks(report) {
+    const out = [];
+    for (const section of report.sections) {
+        for (const c of section.checks) {
+            out.push({
+                name: c.id,
+                ok: c.status === "ok" || c.status === "skip",
+                detail: c.detail ?? c.status,
+            });
+        }
+    }
+    return out;
 }