@toolbaux/guardian 0.1.0

package/dist/extract/pattern-registry.js

@@ -0,0 +1,141 @@
+/**
+ * Pattern Registry — deterministically extracts implementation patterns from an ArchitectureSnapshot.
+ *
+ * Analogous to the ref book entity tables (FM/AT/MM) — a catalog of established patterns
+ * in the codebase that LLMs and developers can reference when implementing features.
+ *
+ * Patterns detected:
+ *   P1  Service Delegation      — endpoint delegates to a named service method
+ *   P2  Auth-Gated Endpoint     — endpoint file contains auth/permission decorators
+ *   P3  LLM Operation           — endpoint calls an AI provider
+ *   P4  Background Task Dispatch— endpoint dispatches a celery/background task
+ *   P5  CRUD Endpoint           — endpoint is part of a standard CRUD set on a resource
+ *   P6  Multi-Model Write       — endpoint writes to 3+ models
+ *   P7  Cross-Stack Contract    — endpoint has a verified frontend caller
+ *   P8  Paginated List          — endpoint is a GET list with "page"/"limit" in path/query naming
+ */
+export function buildPatternRegistry(architecture) {
+    const endpoints = architecture.endpoints;
+    const endpointModelUsage = architecture.endpoint_model_usage;
+    const crossStack = architecture.cross_stack_contracts ?? [];
+    const modelWriteMap = new Map();
+    for (const usage of endpointModelUsage) {
+        const writes = usage.models.filter((m) => m.access === "write" || m.access === "read_write").length;
+        modelWriteMap.set(usage.endpoint_id, writes);
+    }
+    const crossStackVerified = new Set(crossStack.filter((c) => c.status === "ok").map((c) => c.endpoint_id));
+    // P1 — Service Delegation
+    const p1 = endpoints.filter((ep) => ep.service_calls.length > 0);
+    // P2 — Auth-Gated (heuristic: file path contains "auth", "permission", "security", or handler mentions it)
+    const p2 = endpoints.filter((ep) => {
+        const lower = (ep.file + ep.handler).toLowerCase();
+        return (lower.includes("auth") ||
+            lower.includes("permission") ||
+            lower.includes("require_") ||
+            lower.includes("depends(get_current"));
+    });
+    // P3 — LLM Operation
+    const p3 = endpoints.filter((ep) => ep.ai_operations && ep.ai_operations.length > 0);
+    // P4 — Background Task Dispatch (service_calls referencing task patterns)
+    const p4 = endpoints.filter((ep) => ep.service_calls.some((s) => {
+        const lower = s.toLowerCase();
+        return (lower.includes("task") ||
+            lower.includes(".delay(") ||
+            lower.includes(".apply_async") ||
+            lower.includes("background"));
+    }));
+    // P5 — CRUD set: resource has GET list + GET detail + POST + PATCH/PUT + DELETE
+    const resourceMethods = new Map();
+    for (const ep of endpoints) {
+        // Normalise path to resource key: strip trailing /{id} variant
+        const resource = ep.path.replace(/\/\{[^}]+\}$/, "").replace(/\/:[^/]+$/, "");
+        const entry = resourceMethods.get(resource) ?? new Set();
+        entry.add(ep.method.toUpperCase());
+        resourceMethods.set(resource, entry);
+    }
+    const crudResources = new Set();
+    for (const [resource, methods] of resourceMethods) {
+        if (methods.has("GET") && methods.has("POST") && (methods.has("PATCH") || methods.has("PUT"))) {
+            crudResources.add(resource);
+        }
+    }
+    const p5 = endpoints.filter((ep) => {
+        const resource = ep.path.replace(/\/\{[^}]+\}$/, "").replace(/\/:[^/]+$/, "");
+        return crudResources.has(resource);
+    });
+    // P6 — Multi-Model Write (3+ model writes)
+    const p6 = endpoints.filter((ep) => (modelWriteMap.get(ep.id) ?? 0) >= 3);
+    // P7 — Cross-Stack Contract (verified frontend caller)
+    const p7 = endpoints.filter((ep) => crossStackVerified.has(ep.id));
+    // P8 — Paginated List (GET endpoints with "list" or "page" in name/path)
+    const p8 = endpoints.filter((ep) => {
+        if (ep.method.toUpperCase() !== "GET")
+            return false;
+        const lower = (ep.path + ep.handler).toLowerCase();
+        return lower.includes("list") || lower.includes("page") || lower.includes("paginate");
+    });
+    const definitions = [
+        {
+            id: "P1",
+            name: "Service Delegation",
+            description: "Endpoint delegates business logic to a named service method. Route handler is thin; all logic lives in service layer.",
+            matches: p1,
+        },
+        {
+            id: "P2",
+            name: "Auth-Gated Endpoint",
+            description: "Endpoint requires authentication or permission check before executing. Uses auth dependency injection or decorator.",
+            matches: p2,
+        },
+        {
+            id: "P3",
+            name: "LLM Operation",
+            description: "Endpoint calls an AI provider (OpenAI, Anthropic, etc.). May involve prompt construction, model selection, and token budgeting.",
+            matches: p3,
+        },
+        {
+            id: "P4",
+            name: "Background Task Dispatch",
+            description: "Endpoint dispatches work to a background task queue (Celery, FastAPI BackgroundTasks) and returns immediately.",
+            matches: p4,
+        },
+        {
+            id: "P5",
+            name: "CRUD Resource",
+            description: "Endpoint is part of a full CRUD set (GET list + GET detail + POST + PATCH/PUT + DELETE) on a single resource.",
+            matches: p5,
+        },
+        {
+            id: "P6",
+            name: "Multi-Model Write",
+            description: "Endpoint writes to 3 or more ORM models in a single request. Likely requires a transaction.",
+            matches: p6,
+        },
+        {
+            id: "P7",
+            name: "Cross-Stack Contract",
+            description: "Endpoint has a verified frontend caller with matching request/response fields. Schema contract is enforced.",
+            matches: p7,
+        },
+        {
+            id: "P8",
+            name: "Paginated List",
+            description: "GET endpoint returns a paginated collection. Supports page/limit/cursor parameters.",
+            matches: p8,
+        },
+    ];
+    const patterns = definitions.map(({ id, name, description, matches }) => ({
+        id,
+        name,
+        description,
+        occurrences: matches.length,
+        example_endpoints: matches
+            .slice(0, 3)
+            .map((ep) => `${ep.method} ${ep.path}`),
+        example_files: Array.from(new Set(matches.slice(0, 3).map((ep) => ep.file))),
+    }));
+    return {
+        generated_at: new Date().toISOString(),
+        patterns,
+    };
+}

package/dist/extract/product-doc.js

@@ -0,0 +1,497 @@
+/**
+ * Product Document Renderer
+ *
+ * Generates a human-readable, navigable product document from codebase intelligence
+ * and existing guardian doc files (hld.md, integration.md, summary.md).
+ *
+ * Navigation features:
+ *   - Auto-generated TOC with anchor links + domain/model sub-links
+ *   - Collapsible <details> blocks for large tables (>15 rows)
+ *   - Domain quick-index at top of API Surface
+ *   - Back-to-top links at end of each major section
+ *   - Section stats in headings (count, warnings)
+ *
+ * Sections:
+ *   Overview               ← LLM or fallback
+ *   System Architecture    ← Mermaid diagram + coupling heatmap from hld.md
+ *   API Surface            ← integration.md content (has schemas + model usage)
+ *   Data Models            ← grouped by module, collapsible per group
+ *   Quality Signals        ← orphans, duplicates, drift hotspots from summary.md
+ *   Pattern Registry       ← detected patterns
+ *   Background Tasks       ← task list
+ *   Feature Timeline       ← from feature arcs (if present)
+ *   Frontend Pages         ← from UX snapshot
+ *   Discrepancies          ← code vs spec diff
+ */
+import { parseIntegrationDomains } from "./docs-loader.js";
+import { llmComplete } from "./llm-client.js";
+const SYSTEM_PROMPT = `You are a technical writer generating a product document section for a software engineering team.
+Write concisely and precisely. No marketing language. No filler. Use plain English.
+Respond with only the content for the section — no headers, no preamble.`;
+const COLLAPSE_THRESHOLD = 15; // rows before wrapping in <details>
+const TOP_LINK = `\n[↑ Top](#table-of-contents)\n`;
+function logSection(name) {
+    process.stdout.write(`  ${name}... `);
+    return (note) => console.log(note ?? "done");
+}
+// ── Anchor helpers ────────────────────────────────────────────────────────
+function anchor(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+function link(label, id) {
+    return `[${label}](#${anchor(id)})`;
+}
+// ── Collapsible block ─────────────────────────────────────────────────────
+function collapsible(summary, content, open = false) {
+    const openAttr = open ? " open" : "";
+    return `<details${openAttr}>\n<summary><strong>${summary}</strong></summary>\n\n${content}\n\n</details>`;
+}
+// ── Main renderer ─────────────────────────────────────────────────────────
+export async function renderProductDocument(options) {
+    const { intel, featureArcs, discrepancies, llmConfig, existingDocs } = options;
+    const useLlm = !!llmConfig;
+    const ts = new Date().toISOString().slice(0, 19).replace("T", " ");
+    const sections = [];
+    const parts = [];
+    // ── Header ────────────────────────────────────────────────────────────────
+    parts.push(`# Product Document — ${intel.meta.project}`);
+    parts.push(`_Auto-generated by \`guardian doc-generate\`. Do not edit manually._`);
+    parts.push(`_Updated: ${ts} UTC · ` +
+        `${intel.meta.counts.endpoints} endpoints · ` +
+        `${intel.meta.counts.models} models · ` +
+        `${intel.meta.counts.tasks} tasks · ` +
+        `${intel.meta.counts.pages} pages_`);
+    // Stakeholder metrics table if available
+    if (existingDocs?.stakeholderMetrics) {
+        parts.push("");
+        parts.push(existingDocs.stakeholderMetrics);
+    }
+    parts.push("");
+    // ── Collect section metadata for TOC ─────────────────────────────────────
+    const integrationDomains = existingDocs?.integrationByDomain
+        ? parseIntegrationDomains(existingDocs.integrationByDomain)
+        : null;
+    const domainNames = integrationDomains
+        ? Array.from(integrationDomains.keys()).sort()
+        : Object.keys(groupEndpointsByDomain(intel)).sort();
+    const modelGroups = groupModelsByModule(intel);
+    const groupNames = Array.from(modelGroups.keys()).sort();
+    const hasArcs = !!(featureArcs && Object.keys(featureArcs.arcs).length > 0);
+    const hasPages = intel.frontend_pages.length > 0;
+    const hasTasks = intel.background_tasks.length > 0;
+    const hasDiscrepancies = !!discrepancies;
+    sections.push({ id: "overview", label: "Overview" });
+    sections.push({ id: "system-architecture", label: "System Architecture" });
+    sections.push({
+        id: "api-surface",
+        label: `API Surface — ${domainNames.length} domains · ${intel.meta.counts.endpoints} endpoints`,
+        subLinks: domainNames.slice(0, 20).map((d) => link(d, d)),
+    });
+    sections.push({
+        id: "data-models",
+        label: `Data Models — ${intel.meta.counts.models} models`,
+        subLinks: groupNames.map((g) => link(g, `${g} group`)),
+    });
+    sections.push({ id: "quality-signals", label: "Quality Signals" });
+    sections.push({ id: "pattern-registry", label: "Pattern Registry" });
+    if (hasTasks)
+        sections.push({ id: "background-tasks", label: `Background Tasks — ${intel.meta.counts.tasks}` });
+    if (hasArcs)
+        sections.push({ id: "feature-timeline", label: "Feature Timeline" });
+    if (hasPages)
+        sections.push({ id: "frontend-pages", label: "Frontend Pages" });
+    if (hasDiscrepancies)
+        sections.push({ id: "discrepancies", label: "Discrepancies" });
+    // ── Table of Contents ─────────────────────────────────────────────────────
+    const tocLines = ["## Table of Contents", ""];
+    for (const sec of sections) {
+        tocLines.push(`- ${link(sec.label, sec.id)}`);
+        if (sec.subLinks && sec.subLinks.length > 0) {
+            const line = `  ${sec.subLinks.join(" · ")}`;
+            const suffix = domainNames.length > 20 && sec.id === "api-surface"
+                ? ` · _+${domainNames.length - 20} more_`
+                : "";
+            tocLines.push(line + suffix);
+        }
+    }
+    parts.push(tocLines.join("\n"));
+    parts.push("");
+    // ── Overview ──────────────────────────────────────────────────────────────
+    {
+        const done = logSection(`Overview${useLlm ? " [LLM]" : ""}`);
+        parts.push(`## Overview`);
+        parts.push("");
+        // Inject product context from config or README if available
+        if (options.productContext) {
+            parts.push(options.productContext);
+            parts.push("");
+        }
+        if (llmConfig) {
+            const contextHint = options.productContext
+                ? `\nProduct context:\n${options.productContext.slice(0, 800)}`
+                : "";
+            const text = await generateOverview(llmConfig, intel, contextHint);
+            parts.push(text);
+            done();
+        }
+        else {
+            parts.push(`**${intel.meta.project}** — ${intel.meta.counts.endpoints} endpoints across ${intel.meta.counts.modules} modules, ` +
+                `${intel.meta.counts.models} data models, ${intel.meta.counts.tasks} background tasks, ${intel.meta.counts.pages} frontend pages.`);
+            parts.push("");
+            parts.push(`_Set \`SPECGUARD_LLM_ENDPOINT\` + \`SPECGUARD_LLM_API_KEY\`, or run Ollama locally, for a narrative summary._`);
+            done("skipped (no LLM)");
+        }
+        parts.push(TOP_LINK);
+    }
+    // ── System Architecture ───────────────────────────────────────────────────
+    {
+        const done = logSection("System Architecture");
+        parts.push(`## System Architecture`);
+        parts.push("");
+        if (existingDocs?.systemDiagram) {
+            parts.push("### System Block Diagram");
+            parts.push("");
+            parts.push(existingDocs.systemDiagram);
+            parts.push("");
+        }
+        if (existingDocs?.driftSummary) {
+            parts.push(collapsible("Drift Summary", existingDocs.driftSummary));
+            parts.push("");
+        }
+        if (existingDocs?.couplingHeatmap) {
+            parts.push(collapsible("Structural Coupling Heatmap", existingDocs.couplingHeatmap));
+            parts.push("");
+        }
+        if (existingDocs?.backendSubsystems) {
+            parts.push(collapsible("Backend Subsystems", existingDocs.backendSubsystems));
+            parts.push("");
+        }
+        if (!existingDocs?.systemDiagram && !existingDocs?.couplingHeatmap) {
+            // Fallback: simple module table
+            parts.push("| Module | Layer | Files | Endpoints |");
+            parts.push("|---|---|---|---|");
+            for (const m of intel.service_map.filter((m) => m.type === "backend")
+                .sort((a, b) => b.endpoint_count - a.endpoint_count)) {
+                parts.push(`| \`${m.id}\` | ${m.layer} | ${m.file_count} | ${m.endpoint_count} |`);
+            }
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── API Surface ───────────────────────────────────────────────────────────
+    {
+        const done = logSection(`API Surface (${domainNames.length} domains${useLlm ? " + LLM descriptions" : ""})`);
+        parts.push(`## API Surface`);
+        parts.push(`_${domainNames.length} domains · ${intel.meta.counts.endpoints} endpoints_`);
+        parts.push("");
+        // Quick-index
+        parts.push("**Jump to:** " +
+            domainNames.map((d) => `[${d}](#${anchor(d)})`).join(" · "));
+        parts.push("");
+        if (integrationDomains && integrationDomains.size > 0) {
+            // Use integration.md content — richer (has schemas + model usage)
+            for (const [domain, { content }] of Array.from(integrationDomains.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+                const rowCount = (content.match(/^\|/gm) ?? []).length;
+                const endpointCount = Math.max(0, rowCount - 2); // subtract header + separator rows
+                let sectionContent = `<a id="${anchor(domain)}"></a>\n\n`;
+                if (llmConfig && endpointCount > 0) {
+                    const desc = await generateDomainDescriptionFromText(llmConfig, domain, content);
+                    if (desc)
+                        sectionContent += `${desc}\n\n`;
+                }
+                sectionContent += content;
+                const isOpen = endpointCount <= COLLAPSE_THRESHOLD;
+                parts.push(collapsible(`${domain} — ${endpointCount} endpoint(s)`, sectionContent, isOpen));
+                parts.push("");
+            }
+        }
+        else {
+            // Fallback: build from intel
+            const domains = groupEndpointsByDomain(intel);
+            for (const [domain, endpoints] of Array.from(domains.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+                let sectionContent = `<a id="${anchor(domain)}"></a>\n\n`;
+                if (llmConfig) {
+                    const desc = await generateDomainDescription(llmConfig, domain, endpoints);
+                    if (desc)
+                        sectionContent += `${desc}\n\n`;
+                }
+                sectionContent += "| Method | Path | Handler | Patterns |\n|---|---|---|---|\n";
+                for (const [, ep] of endpoints) {
+                    const patterns = ep.patterns.length > 0 ? ep.patterns.join(", ") : "—";
+                    sectionContent += `| \`${ep.method}\` | \`${ep.path}\` | \`${ep.handler}\` | ${patterns} |\n`;
+                }
+                const isOpen = endpoints.length <= COLLAPSE_THRESHOLD;
+                parts.push(collapsible(`${domain} — ${endpoints.length} endpoint(s)`, sectionContent, isOpen));
+                parts.push("");
+            }
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Data Models ───────────────────────────────────────────────────────────
+    {
+        const done = logSection(`Data Models (${intel.meta.counts.models}${useLlm ? " + LLM descriptions" : ""})`);
+        parts.push(`## Data Models`);
+        parts.push(`_${intel.meta.counts.models} models in ${modelGroups.size} group(s)_`);
+        parts.push("");
+        // Group quick-index
+        parts.push("**Jump to:** " +
+            groupNames.map((g) => `[${g}](#${anchor(`${g} group`)})`).join(" · "));
+        parts.push("");
+        for (const [group, models] of Array.from(modelGroups.entries()).sort((a, b) => a[0].localeCompare(b[0]))) {
+            let groupContent = `<a id="${anchor(`${group} group`)}"></a>\n\n`;
+            groupContent += "| Model | Framework | Fields | Relationships |\n|---|---|---|---|\n";
+            for (const [name, model] of models) {
+                const fields = model.fields.length > 6
+                    ? `${model.fields.slice(0, 6).join(", ")} +${model.fields.length - 6} more`
+                    : model.fields.join(", ") || "—";
+                const rels = model.relationships.slice(0, 3).join(", ") || "—";
+                groupContent += `| **${name}** | ${model.framework} | ${fields} | ${rels} |\n`;
+            }
+            if (llmConfig && models.length > 0) {
+                const topModels = models.slice(0, 4).map(([name, m]) => `${name}: ${m.fields.slice(0, 8).join(", ")}`).join("\n");
+                const desc = await generateGroupDescription(llmConfig, group, topModels);
+                if (desc)
+                    groupContent = `<a id="${anchor(`${group} group`)}"></a>\n\n${desc}\n\n` + groupContent.replace(`<a id="${anchor(`${group} group`)}"></a>\n\n`, "");
+            }
+            const isOpen = models.length <= COLLAPSE_THRESHOLD;
+            parts.push(collapsible(`${group} — ${models.length} model(s)`, groupContent, isOpen));
+            parts.push("");
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Quality Signals ───────────────────────────────────────────────────────
+    {
+        const done = logSection("Quality Signals");
+        parts.push(`## Quality Signals`);
+        parts.push("");
+        if (existingDocs?.qualitySignals) {
+            parts.push(existingDocs.qualitySignals);
+        }
+        else {
+            // Fallback from intel analysis
+            parts.push("_Run `guardian extract` to populate quality signals._");
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Pattern Registry ──────────────────────────────────────────────────────
+    {
+        const activePatterns = intel.pattern_registry.patterns.filter((p) => p.occurrences > 0);
+        const done = logSection(`Pattern Registry (${activePatterns.length} active)`);
+        parts.push(`## Pattern Registry`);
+        parts.push(`_${activePatterns.length} implementation patterns detected in the codebase._`);
+        parts.push("");
+        parts.push("| ID | Pattern | Occurrences | Description | Example |");
+        parts.push("|---|---|---|---|---|");
+        for (const p of activePatterns) {
+            const example = p.example_endpoints[0] ? `\`${p.example_endpoints[0]}\`` : "—";
+            parts.push(`| ${p.id} | **${p.name}** | ${p.occurrences} | ${p.description} | ${example} |`);
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Background Tasks ──────────────────────────────────────────────────────
+    if (hasTasks) {
+        const done = logSection(`Background Tasks (${intel.background_tasks.length})`);
+        parts.push(`## Background Tasks`);
+        parts.push("");
+        parts.push("| Task | Kind | File | Queue |");
+        parts.push("|---|---|---|---|");
+        for (const t of intel.background_tasks) {
+            parts.push(`| \`${t.name}\` | ${t.kind} | \`${t.file}\` | ${t.queue ?? "—"} |`);
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Feature Timeline ──────────────────────────────────────────────────────
+    if (hasArcs && featureArcs) {
+        const arcCount = Object.keys(featureArcs.arcs).length;
+        const done = logSection(`Feature Timeline (${arcCount} arc(s))`);
+        parts.push(`## Feature Timeline`);
+        parts.push(`_${arcCount} feature area(s) tracked across sprints._`);
+        parts.push("");
+        for (const [tag, arc] of Object.entries(featureArcs.arcs)) {
+            const sprintCount = Object.keys(arc.sprints).length;
+            const sprintLines = [];
+            for (const [sprint, snap] of Object.entries(arc.sprints)) {
+                sprintLines.push(`**${sprint}** — ${snap.features.join(", ")}`);
+                if (snap.endpoints.length > 0)
+                    sprintLines.push(`  Endpoints: ${snap.endpoints.map((e) => `\`${e}\``).join(", ")}`);
+                if (snap.models.length > 0)
+                    sprintLines.push(`  Models: ${snap.models.map((m) => `\`${m}\``).join(", ")}`);
+            }
+            const summary = `${arc.total_endpoints} endpoints · ${arc.total_models} models · ${sprintCount} sprint(s)`;
+            parts.push(collapsible(`${tag} — ${summary}`, sprintLines.join("\n"), true));
+            parts.push("");
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Frontend Pages ────────────────────────────────────────────────────────
+    if (hasPages) {
+        const done = logSection(`Frontend Pages (${intel.frontend_pages.length})`);
+        parts.push(`## Frontend Pages`);
+        parts.push("");
+        parts.push("| Page | Component | API Calls | Direct Components |");
+        parts.push("|---|---|---|---|");
+        for (const page of intel.frontend_pages) {
+            const calls = page.api_calls.length > 0
+                ? page.api_calls.slice(0, 3).join(", ") + (page.api_calls.length > 3 ? ` +${page.api_calls.length - 3}` : "")
+                : "—";
+            const comps = page.direct_components.length > 0
+                ? page.direct_components.slice(0, 3).join(", ") + (page.direct_components.length > 3 ? ` +${page.direct_components.length - 3}` : "")
+                : "—";
+            parts.push(`| \`${page.path}\` | ${page.component} | ${calls} | ${comps} |`);
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    // ── Discrepancies ─────────────────────────────────────────────────────────
+    if (hasDiscrepancies && discrepancies) {
+        const issueLabel = discrepancies.summary.total_issues === 0
+            ? "none"
+            : `${discrepancies.summary.total_issues} issue(s)${discrepancies.summary.has_critical ? " ⚠" : ""}`;
+        const done = logSection(`Discrepancies (${issueLabel})`);
+        parts.push(`## Discrepancies`);
+        parts.push("");
+        if (discrepancies.summary.total_issues === 0) {
+            parts.push("✓ No discrepancies found. Code and specs are in sync.");
+        }
+        else {
+            parts.push(`${discrepancies.summary.has_critical ? "⚠ " : ""}**${discrepancies.summary.total_issues} issue(s)** detected.`);
+            parts.push("");
+            const bullets = [];
+            if (discrepancies.new_endpoints.length > 0)
+                bullets.push(`**${discrepancies.new_endpoints.length} new endpoint(s)** since baseline`);
+            if (discrepancies.removed_endpoints.length > 0)
+                bullets.push(`**⚠ ${discrepancies.removed_endpoints.length} removed endpoint(s)** since baseline`);
+            if (discrepancies.untracked_endpoints.length > 0)
+                bullets.push(`**${discrepancies.untracked_endpoints.length} endpoint(s)** not in any feature spec`);
+            if (discrepancies.drifted_models.length > 0)
+                bullets.push(`**${discrepancies.drifted_models.length} model(s)** with field changes`);
+            if (discrepancies.orphan_specs.length > 0)
+                bullets.push(`**⚠ ${discrepancies.orphan_specs.length} spec(s)** reference missing endpoints`);
+            for (const b of bullets)
+                parts.push(`- ${b}`);
+            parts.push("");
+            parts.push(`_Run \`guardian discrepancy\` for the full report._`);
+        }
+        parts.push(TOP_LINK);
+        done();
+    }
+    return parts.join("\n");
+}
+// ── LLM generators ────────────────────────────────────────────────────────
+async function generateOverview(config, intel, contextHint = "") {
+    const summary = [
+        `Project: ${intel.meta.project}`,
+        `${intel.meta.counts.endpoints} endpoints, ${intel.meta.counts.models} models, ${intel.meta.counts.tasks} tasks`,
+        `Modules: ${intel.service_map.filter((m) => m.type === "backend").sort((a, b) => b.endpoint_count - a.endpoint_count).slice(0, 4).map((m) => `${m.id}(${m.endpoint_count})`).join(", ")}`,
+        `Patterns: ${intel.pattern_registry.patterns.filter((p) => p.occurrences > 0).map((p) => `${p.name}(${p.occurrences}x)`).slice(0, 4).join(", ")}`,
+        contextHint,
+    ].join("\n");
+    try {
+        return await llmComplete(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: `Write a 2-3 sentence product overview. Be specific about what this product does, who it's for, and its key architectural decisions:\n\n${summary}` },
+        ], 512);
+    }
+    catch (err) {
+        return `_LLM summary unavailable: ${err.message}_`;
+    }
+}
+async function generateDomainDescriptionFromText(config, domain, integrationContent) {
+    const endpoints = integrationContent
+        .split("\n")
+        .filter((l) => l.startsWith("| ") && !l.startsWith("| Method") && !l.startsWith("| ---"))
+        .slice(0, 8)
+        .map((l) => { const cols = l.split("|").map((c) => c.trim()); return `${cols[1]} ${cols[2]}`; })
+        .join("\n");
+    try {
+        return await llmComplete(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: `One sentence: what does the "${domain}" API domain do?\n${endpoints}` },
+        ], 200);
+    }
+    catch {
+        return "";
+    }
+}
+async function generateDomainDescription(config, domain, endpoints) {
+    const list = endpoints.slice(0, 8).map(([, ep]) => `${ep.method} ${ep.path}`).join("\n");
+    try {
+        return await llmComplete(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: `One sentence: what does the "${domain}" API domain do?\n${list}` },
+        ], 200);
+    }
+    catch {
+        return "";
+    }
+}
+async function generateGroupDescription(config, group, modelSummary) {
+    try {
+        return await llmComplete(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: `One sentence: what does the "${group}" model group represent?\n${modelSummary}` },
+        ], 200);
+    }
+    catch {
+        return "";
+    }
+}
+// ── Grouping helpers ──────────────────────────────────────────────────────
+function groupModelsByModule(intel) {
+    const groups = new Map();
+    // Build file → module index from service_map
+    const fileToModule = new Map();
+    for (const m of intel.service_map) {
+        // service_map paths are directory paths; match model files by prefix
+        for (const [name, model] of Object.entries(intel.model_registry)) {
+            if (model.file.includes(m.path) || m.path.includes(model.file.split("/")[0] ?? "")) {
+                fileToModule.set(model.file, m.id);
+            }
+        }
+    }
+    for (const [name, model] of Object.entries(intel.model_registry)) {
+        const module = fileToModule.get(model.file) ?? deriveGroupFromFile(model.file);
+        const entry = groups.get(module) ?? [];
+        entry.push([name, model]);
+        groups.set(module, entry);
+    }
+    // Sort models within each group
+    for (const [key, models] of groups) {
+        groups.set(key, models.sort((a, b) => a[0].localeCompare(b[0])));
+    }
+    return groups;
+}
+function deriveGroupFromFile(file) {
+    // "backend/app/models.py" → "app"
+    // "backend/app/services/auth.py" → "app"
+    const parts = file.split("/").filter(Boolean);
+    const appIdx = parts.indexOf("app");
+    if (appIdx !== -1)
+        return parts[appIdx + 1] ?? parts[appIdx] ?? "other";
+    return parts[1] ?? parts[0] ?? "other";
+}
+function groupEndpointsByDomain(intel) {
+    const domains = new Map();
+    for (const [key, ep] of Object.entries(intel.api_registry)) {
+        const domain = extractDomain(ep.path);
+        const entry = domains.get(domain) ?? [];
+        entry.push([key, ep]);
+        domains.set(domain, entry);
+    }
+    return domains;
+}
+function extractDomain(epPath) {
+    const parts = epPath.replace(/^\//, "").split("/");
+    const start = parts[0] === "api" ? 1 : 0;
+    return parts[start] ?? "root";
+}