@praneeth_54/agentdoctor 2.1.0 → 3.0.1

package/dist/product/health/code-health.d.ts

@@ -0,0 +1,20 @@
+import type { GitIntelligenceReport } from "../../intelligence/git/analyze.js";
+import type { ArchitectureCheckResult } from "../../architecture/contract.js";
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface CodeHealthIndicator {
+    id: string;
+    label: string;
+    value: number | string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface CodeHealthReport {
+    root: string;
+    indicators: CodeHealthIndicator[];
+    limitations: string[];
+}
+export declare function analyzeCodeHealth(rootInput: string, options?: {
+    gitReport?: GitIntelligenceReport;
+    architectureCheck?: ArchitectureCheckResult;
+    maxFileSizeBytes?: number;
+}): Promise<CodeHealthReport>;

package/dist/product/health/code-health.js

@@ -0,0 +1,149 @@
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { readTextFile } from "../../utils/fs.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function isTestPath(relativePath) {
+    const p = relativePath.toLowerCase();
+    return (p.includes(".test.") ||
+        p.includes(".spec.") ||
+        p.startsWith("tests/") ||
+        p.startsWith("test/") ||
+        p.includes("__tests__/"));
+}
+function isSourcePath(relativePath) {
+    const p = relativePath.toLowerCase();
+    if (isTestPath(p))
+        return false;
+    return (p.endsWith(".ts") ||
+        p.endsWith(".tsx") ||
+        p.endsWith(".js") ||
+        p.endsWith(".jsx") ||
+        p.endsWith(".py") ||
+        p.endsWith(".php") ||
+        p.endsWith(".go") ||
+        p.endsWith(".rs"));
+}
+async function countTodoFixme(root, files, maxBytes) {
+    let todo = 0;
+    let fixme = 0;
+    const evidence = [];
+    const re = /\b(TODO|FIXME)\b/g;
+    for (const f of files) {
+        const text = await readTextFile(path.join(root, f.relativePath), maxBytes);
+        if (!text)
+            continue;
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            if (m[1] === "TODO")
+                todo++;
+            else
+                fixme++;
+            if (evidence.length < 8) {
+                const line = text.slice(0, m.index).split("\n").length;
+                const excerpt = text.split(/\r?\n/)[line - 1]?.trim().slice(0, 100);
+                evidence.push({
+                    path: f.relativePath.replace(/\\/g, "/"),
+                    line,
+                    ...(excerpt !== undefined ? { excerpt } : {}),
+                });
+            }
+        }
+    }
+    return { todo, fixme, evidence };
+}
+export async function analyzeCodeHealth(rootInput, options) {
+    const maxFileSizeBytes = options?.maxFileSizeBytes ?? DEFAULT_MAX_FILE_SIZE_BYTES;
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const paths = detection.discovery.files.map((f) => f.relativePath.replace(/\\/g, "/"));
+    const limitations = [
+        "Scores are descriptive indicators with evidence; not a single authoritative debt score.",
+        "Hotspot overlap requires git intelligence input.",
+    ];
+    const sourceFiles = paths.filter(isSourcePath);
+    const testFiles = paths.filter(isTestPath);
+    const { todo, fixme, evidence: todoEvidence, } = await countTodoFixme(root, detection.discovery.files, maxFileSizeBytes);
+    const indicators = [
+        {
+            id: "file-count",
+            label: "Discovered files",
+            value: paths.length,
+            truth: "VERIFIED",
+            evidence: [{ path: ".", excerpt: `discovery.files.length=${paths.length}` }],
+        },
+        {
+            id: "source-file-count",
+            label: "Source-like files",
+            value: sourceFiles.length,
+            truth: "INFERRED",
+            evidence: [{ path: ".", excerpt: `extension/heuristic count=${sourceFiles.length}` }],
+        },
+        {
+            id: "test-file-count",
+            label: "Test-like files",
+            value: testFiles.length,
+            truth: "INFERRED",
+            evidence: [{ path: ".", excerpt: `test path heuristic count=${testFiles.length}` }],
+        },
+        {
+            id: "test-ratio",
+            label: "Test file ratio (test / (test+source))",
+            value: sourceFiles.length + testFiles.length === 0
+                ? "n/a"
+                : (testFiles.length / (sourceFiles.length + testFiles.length)).toFixed(3),
+            truth: "INFERRED",
+            evidence: [
+                {
+                    path: ".",
+                    excerpt: `tests=${testFiles.length}, sources=${sourceFiles.length}`,
+                },
+            ],
+        },
+        {
+            id: "todo-count",
+            label: "TODO markers",
+            value: todo,
+            truth: "VERIFIED",
+            evidence: todoEvidence.filter((e) => e.excerpt?.includes("TODO")),
+        },
+        {
+            id: "fixme-count",
+            label: "FIXME markers",
+            value: fixme,
+            truth: "VERIFIED",
+            evidence: todoEvidence.filter((e) => e.excerpt?.includes("FIXME")),
+        },
+    ];
+    if (options?.architectureCheck) {
+        indicators.push({
+            id: "architecture-violations",
+            label: "Architecture contract violations",
+            value: options.architectureCheck.violations.length,
+            truth: "VERIFIED",
+            evidence: options.architectureCheck.violations.slice(0, 5).map((v) => ({
+                path: v.fromPath || v.toPath || ".",
+                excerpt: `${v.ruleId}: ${v.description}`.slice(0, 120),
+            })),
+        });
+    }
+    if (options?.gitReport?.gitAvailable) {
+        const hotspotPaths = new Set(options.gitReport.hotspots.map((h) => h.path.replace(/\\/g, "/")));
+        const overlap = sourceFiles.filter((p) => hotspotPaths.has(p)).length;
+        indicators.push({
+            id: "hotspot-source-overlap",
+            label: "Source files overlapping git hotspots",
+            value: overlap,
+            truth: "INFERRED",
+            evidence: options.gitReport.hotspots.slice(0, 5).map((h) => ({
+                path: h.path,
+                excerpt: `commits=${h.commits}`,
+            })),
+        });
+    }
+    else {
+        limitations.push("Git hotspot overlap skipped (git unavailable or not provided).");
+    }
+    return { root, indicators, limitations };
+}

package/dist/product/index.d.ts

@@ -0,0 +1,72 @@
+export type { TruthLabel, ProductEvidence } from "./truth.js";
+export { minProductTruth, truthLabelDescription } from "./truth.js";
+export { traceRequirements } from "./requirements/trace.js";
+export type { RequirementTrace, RequirementsTraceReport } from "./requirements/trace.js";
+export { analyzeApiSurface } from "./api/doctor.js";
+export type { ApiDoctorReport, ApiEndpointFinding } from "./api/doctor.js";
+export { analyzeDatabaseSchema } from "./database/doctor.js";
+export type { DatabaseDoctorReport, SchemaObjectFinding, SchemaDriftFinding, SchemaRelationFinding, } from "./database/doctor.js";
+export { analyzeEvents } from "./events/doctor.js";
+export type { EventsDoctorReport, EventFlowNode, EventFlowEdge } from "./events/doctor.js";
+export { analyzeDependencies } from "./deps/analyze.js";
+export type { DependencyAnalysisReport, DirectDependency, DuplicatePackageName, UpgradeImpactHint, } from "./deps/analyze.js";
+export { analyzeCodeHealth } from "./health/code-health.js";
+export type { CodeHealthReport, CodeHealthIndicator } from "./health/code-health.js";
+export { buildSoftwareMap } from "./map/software-map.js";
+export type { SoftwareMap, SoftwareMapNode, SoftwareMapNodeKind } from "./map/software-map.js";
+export { appendChangeLedgerEntry, readChangeLedger, listChangeLedgerEntries, } from "./ledger/change-ledger.js";
+export type { ChangeLedgerEntry, ChangeLedgerListResult } from "./ledger/change-ledger.js";
+export { analyzeWhatIf } from "./whatif/engine.js";
+export type { WhatIfReport, WhatIfAffectedItem } from "./whatif/engine.js";
+export { loadDecisionLedger, appendDecisionLedgerEntry, parseAdrDecisions, resolveDecisionPath, } from "./decisions/ledger.js";
+export type { DecisionRecord, DecisionLedgerResult } from "./decisions/ledger.js";
+export { runForensicAnalysis, assertForensicReadOnly, ForensicWriteRefusedError, } from "./forensic/mode.js";
+export type { ForensicAnalysisReport } from "./forensic/mode.js";
+export { buildSoftwareDigitalTwinSnapshot } from "./twin/digital-twin.js";
+export type { SoftwareDigitalTwin } from "./twin/digital-twin.js";
+export { buildSoftwareDigitalTwin, updateTwin, loadTwinSnapshot, saveTwinSnapshot, invalidateTwinSnapshot, } from "./twin/store.js";
+export type { StoredTwinSnapshot, TwinSnapshotMeta } from "./twin/store.js";
+export { parsePackageLockJson, parseYarnLock, parsePnpmLockYaml, parseAllLockfiles, } from "./deps/lockfiles.js";
+export type { LockfilePackageVersion, ParsedLockfile } from "./deps/lockfiles.js";
+export { discoverOpenApiEndpoints } from "./api/openapi.js";
+export { buildIndex, searchIndex, searchHybrid, documentId } from "./search/index.js";
+export type { TfidfIndex, IndexDocument } from "./search/index.js";
+export { runEvalLab } from "./eval/lab.js";
+export type { EvalLabReport, EvalCheckResult } from "./eval/lab.js";
+export { diagnoseAgentDoctorSelf } from "./self/diagnose.js";
+export type { SelfDiagnoseReport, SelfDiagnoseFinding } from "./self/diagnose.js";
+export { analyzeInfra } from "./ops/infra.js";
+export type { InfraReport, InfraArtifact } from "./ops/infra.js";
+export { buildIncidentHypotheses } from "./ops/incident.js";
+export type { IncidentReport, IncidentTimelineItem } from "./ops/incident.js";
+export { discoverProjectRoots, resolveStartedProjectRoot, classifyBroadUserScanRoot, } from "./discovery/roots.js";
+export type { ProjectDiscoveryReport, ProjectCandidate, DiscoverProjectOptions, } from "./discovery/roots.js";
+export { buildProjectDna, persistProjectDna } from "./dna/build.js";
+export type { ProjectDna } from "./dna/build.js";
+export { enrichGraphWithLanguageAdapters } from "./graph/enrich-languages.js";
+export type { LanguageGraphEnrichmentStats } from "./graph/enrich-languages.js";
+export { analyzeSecuritySurface } from "./security/doctor.js";
+export type { SecurityDoctorReport, SecurityPatternFinding } from "./security/doctor.js";
+export { analyzeTestBrain, persistTestBrainReport, mapTestsFromGraph, } from "./testbrain/analyze.js";
+export type { TestBrainReport, FileTestMapping, TestBrainGraphStats, FileTestMappingEvidence, } from "./testbrain/analyze.js";
+export { analyzePrivacySurface } from "./privacy/doctor.js";
+export type { PrivacyDoctorReport, PrivacyFinding } from "./privacy/doctor.js";
+export { searchSymbolsAndConcepts } from "./search/software-search.js";
+export type { SoftwareSearchReport, SoftwareSearchHit } from "./search/software-search.js";
+export { buildTechnicalDebtRoadmap } from "./techdebt/roadmap.js";
+export type { TechnicalDebtRoadmap, TechnicalDebtItem } from "./techdebt/roadmap.js";
+export { loadOrganizationModel, saveOrganizationModel, linkProjectToOrgModel, resolveLinkedProjectRoot, } from "./org/model.js";
+export type { OrganizationModel, OrgEntityRef, OrgProjectLink } from "./org/model.js";
+export { analyzeFeatureIntelligence } from "./features/intelligence.js";
+export type { FeatureIntelligenceReport, FeatureFlow, FeatureFlowLink, } from "./features/intelligence.js";
+export { buildSoftwareEvolutionTimeline } from "./evolution/timeline.js";
+export type { SoftwareEvolutionReport, EvolutionTimelineEvent, EvolutionTrend, } from "./evolution/timeline.js";
+export { queryMemory } from "./memory/institutional.js";
+export type { InstitutionalMemoryQueryResult, MemoryHit } from "./memory/institutional.js";
+export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/model.js";
+export type { ApprovalRecord, ApprovalState, ApprovalRisk, ApprovalEvaluationInput, ApprovalEvaluationResult, } from "./approval/model.js";
+export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";
+export type { ApprovalGrant, ConsumeApprovalResult } from "./approval/session.js";
+export { classifyRelativePathOwnership, decideDirectoryTraversal, isNestedRepositoryRoot, isProjectOwnedRelativePath, isUnderNestedRepository, assertProjectOwnedRepoPath, ProjectOwnershipError, OWNERSHIP_BOUNDARY_VERSION, verifiedDecisionTruthMeaning, } from "../project/ownership.js";
+export type { ProjectOwnershipClass, DirectoryTraversalDecision } from "../project/ownership.js";
+export type { DecisionSourceKind } from "./decisions/ledger.js";

package/dist/product/index.js

@@ -0,0 +1,36 @@
+export { minProductTruth, truthLabelDescription } from "./truth.js";
+export { traceRequirements } from "./requirements/trace.js";
+export { analyzeApiSurface } from "./api/doctor.js";
+export { analyzeDatabaseSchema } from "./database/doctor.js";
+export { analyzeEvents } from "./events/doctor.js";
+export { analyzeDependencies } from "./deps/analyze.js";
+export { analyzeCodeHealth } from "./health/code-health.js";
+export { buildSoftwareMap } from "./map/software-map.js";
+export { appendChangeLedgerEntry, readChangeLedger, listChangeLedgerEntries, } from "./ledger/change-ledger.js";
+export { analyzeWhatIf } from "./whatif/engine.js";
+export { loadDecisionLedger, appendDecisionLedgerEntry, parseAdrDecisions, resolveDecisionPath, } from "./decisions/ledger.js";
+export { runForensicAnalysis, assertForensicReadOnly, ForensicWriteRefusedError, } from "./forensic/mode.js";
+export { buildSoftwareDigitalTwinSnapshot } from "./twin/digital-twin.js";
+export { buildSoftwareDigitalTwin, updateTwin, loadTwinSnapshot, saveTwinSnapshot, invalidateTwinSnapshot, } from "./twin/store.js";
+export { parsePackageLockJson, parseYarnLock, parsePnpmLockYaml, parseAllLockfiles, } from "./deps/lockfiles.js";
+export { discoverOpenApiEndpoints } from "./api/openapi.js";
+export { buildIndex, searchIndex, searchHybrid, documentId } from "./search/index.js";
+export { runEvalLab } from "./eval/lab.js";
+export { diagnoseAgentDoctorSelf } from "./self/diagnose.js";
+export { analyzeInfra } from "./ops/infra.js";
+export { buildIncidentHypotheses } from "./ops/incident.js";
+export { discoverProjectRoots, resolveStartedProjectRoot, classifyBroadUserScanRoot, } from "./discovery/roots.js";
+export { buildProjectDna, persistProjectDna } from "./dna/build.js";
+export { enrichGraphWithLanguageAdapters } from "./graph/enrich-languages.js";
+export { analyzeSecuritySurface } from "./security/doctor.js";
+export { analyzeTestBrain, persistTestBrainReport, mapTestsFromGraph, } from "./testbrain/analyze.js";
+export { analyzePrivacySurface } from "./privacy/doctor.js";
+export { searchSymbolsAndConcepts } from "./search/software-search.js";
+export { buildTechnicalDebtRoadmap } from "./techdebt/roadmap.js";
+export { loadOrganizationModel, saveOrganizationModel, linkProjectToOrgModel, resolveLinkedProjectRoot, } from "./org/model.js";
+export { analyzeFeatureIntelligence } from "./features/intelligence.js";
+export { buildSoftwareEvolutionTimeline } from "./evolution/timeline.js";
+export { queryMemory } from "./memory/institutional.js";
+export { evaluateApprovalRecord, formatApprovalRecordSummary } from "./approval/model.js";
+export { issueApprovalGrant, consumeApprovalGrant, hashPlanPayload, hashFileWritePlan, } from "./approval/session.js";
+export { classifyRelativePathOwnership, decideDirectoryTraversal, isNestedRepositoryRoot, isProjectOwnedRelativePath, isUnderNestedRepository, assertProjectOwnedRepoPath, ProjectOwnershipError, OWNERSHIP_BOUNDARY_VERSION, verifiedDecisionTruthMeaning, } from "../project/ownership.js";

package/dist/product/ledger/change-ledger.d.ts

@@ -0,0 +1,23 @@
+export interface ChangeLedgerEntry {
+    id: string;
+    recordedAt: string;
+    task?: string;
+    plan?: string;
+    approval?: string;
+    files?: string[];
+    tests?: string[];
+    proofIds?: string[];
+    note?: string;
+}
+export interface ChangeLedgerListResult {
+    root: string;
+    ledgerDir: string;
+    entries: ChangeLedgerEntry[];
+    limitations: string[];
+}
+export declare function appendChangeLedgerEntry(rootInput: string, entry: Omit<ChangeLedgerEntry, "id" | "recordedAt"> & {
+    id?: string;
+    recordedAt?: string;
+}): Promise<ChangeLedgerEntry>;
+export declare function readChangeLedger(rootInput: string): Promise<ChangeLedgerListResult>;
+export declare function listChangeLedgerEntries(rootInput: string): Promise<ChangeLedgerEntry[]>;

package/dist/product/ledger/change-ledger.js

@@ -0,0 +1,64 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeRelPath } from "../../security/paths.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { pathExists } from "../../utils/fs.js";
+function ledgerDirFor(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "change-ledger");
+}
+function ledgerFileFor(root) {
+    return path.join(ledgerDirFor(root), "entries.jsonl");
+}
+async function ensureLedgerDir(root) {
+    const dir = ledgerDirFor(root);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+function newEntryId() {
+    return `cle_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function appendChangeLedgerEntry(rootInput, entry) {
+    const root = resolveRepoRoot(rootInput);
+    await ensureLedgerDir(root);
+    const record = {
+        id: entry.id ?? newEntryId(),
+        recordedAt: entry.recordedAt ?? new Date().toISOString(),
+        ...(entry.task !== undefined ? { task: entry.task } : {}),
+        ...(entry.plan !== undefined ? { plan: entry.plan } : {}),
+        ...(entry.approval !== undefined ? { approval: entry.approval } : {}),
+        ...(entry.files !== undefined ? { files: entry.files.map((f) => safeRelPath(root, f)) } : {}),
+        ...(entry.tests !== undefined ? { tests: entry.tests } : {}),
+        ...(entry.proofIds !== undefined ? { proofIds: entry.proofIds } : {}),
+        ...(entry.note !== undefined ? { note: entry.note } : {}),
+    };
+    const line = `${JSON.stringify(record)}\n`;
+    await fs.appendFile(ledgerFileFor(root), line, "utf8");
+    return record;
+}
+export async function readChangeLedger(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const ledgerDir = ledgerDirFor(root);
+    const limitations = ["Append-only JSONL; entries are not cryptographically signed."];
+    const file = ledgerFileFor(root);
+    if (!(await pathExists(file))) {
+        return { root, ledgerDir, entries: [], limitations };
+    }
+    const text = await fs.readFile(file, "utf8");
+    const entries = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            limitations.push("Skipped malformed JSONL line in change ledger.");
+        }
+    }
+    return { root, ledgerDir, entries, limitations };
+}
+export async function listChangeLedgerEntries(rootInput) {
+    const result = await readChangeLedger(rootInput);
+    return result.entries;
+}

package/dist/product/map/software-map.d.ts

@@ -0,0 +1,17 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export type SoftwareMapNodeKind = "root" | "package" | "directory" | "workspace" | "docs" | "tests" | "unknown";
+export interface SoftwareMapNode {
+    id: string;
+    kind: SoftwareMapNodeKind;
+    label: string;
+    path?: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+    children?: SoftwareMapNode[];
+}
+export interface SoftwareMap {
+    root: string;
+    tree: SoftwareMapNode;
+    limitations: string[];
+}
+export declare function buildSoftwareMap(rootInput: string, maxFileSizeBytes?: number): Promise<SoftwareMap>;

package/dist/product/map/software-map.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { detectProject } from "../../detectors/project.js";
+import { detectMonorepo } from "../../detectors/monorepo.js";
+import { isProjectOwnedRelativePath } from "../../project/ownership.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function nodeId(prefix, p) {
+    return `${prefix}:${p.replace(/[^\w./-]/g, "_")}`;
+}
+async function topLevelEntries(root) {
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && !e.name.startsWith(".") && isProjectOwnedRelativePath(e.name))
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function buildSoftwareMap(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const relativePaths = detection.discovery.files.map((f) => f.relativePath.replace(/\\/g, "/"));
+    let rootWorkspaces;
+    const rootPkgPath = path.join(root, "package.json");
+    try {
+        const raw = await fs.readFile(rootPkgPath, "utf8");
+        rootWorkspaces = JSON.parse(raw).workspaces;
+    }
+    catch {
+        rootWorkspaces = undefined;
+    }
+    const monorepo = detectMonorepo({
+        relativePaths,
+        packageJsonWorkspaces: rootWorkspaces,
+    }).monorepo;
+    const limitations = [
+        "Map is structural (directories/packages), not a full module dependency graph.",
+        `Monorepo signal: ${monorepo}`,
+    ];
+    const packageJsonPaths = relativePaths.filter((p) => p.endsWith("package.json"));
+    const packageNodes = packageJsonPaths.map((p) => ({
+        id: nodeId("pkg", p),
+        kind: p === "package.json" ? "root" : "package",
+        label: path.dirname(p) === "." ? "root package" : path.dirname(p),
+        path: p,
+        truth: "VERIFIED",
+        evidence: [{ path: p }],
+    }));
+    const dirs = await topLevelEntries(root);
+    const dirNodes = dirs.map((name) => {
+        let kind = "directory";
+        if (name === "docs")
+            kind = "docs";
+        if (name === "tests" || name === "test")
+            kind = "tests";
+        return {
+            id: nodeId("dir", name),
+            kind,
+            label: name,
+            path: name,
+            truth: "VERIFIED",
+            evidence: [{ path: name, excerpt: "top-level directory listing" }],
+        };
+    });
+    const tree = {
+        id: nodeId("root", root),
+        kind: "root",
+        label: path.basename(root) || root,
+        path: ".",
+        truth: "VERIFIED",
+        evidence: [{ path: ".", excerpt: "detectProject root" }],
+        children: [
+            {
+                id: "packages-section",
+                kind: "workspace",
+                label: "packages",
+                truth: packageNodes.length ? "VERIFIED" : "UNKNOWN",
+                evidence: packageNodes.slice(0, 3).map((n) => ({ path: n.path ?? "." })),
+                children: packageNodes,
+            },
+            {
+                id: "directories-section",
+                kind: "directory",
+                label: "top-level directories",
+                truth: dirNodes.length ? "VERIFIED" : "PARTIAL",
+                evidence: dirNodes.slice(0, 5).map((n) => ({ path: n.path ?? n.label })),
+                children: dirNodes,
+            },
+        ],
+    };
+    return { root, tree, limitations };
+}

package/dist/product/memory/institutional.d.ts

@@ -0,0 +1,16 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface MemoryHit {
+    source: "brain" | "decisions" | "change-ledger" | "dna";
+    id: string;
+    title: string;
+    excerpt: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface InstitutionalMemoryQueryResult {
+    root: string;
+    query: string;
+    hits: MemoryHit[];
+    limitations: string[];
+}
+export declare function queryMemory(rootInput: string, query: string): Promise<InstitutionalMemoryQueryResult>;

package/dist/product/memory/institutional.js

@@ -0,0 +1,92 @@
+import { loadLatestBrain, searchBrain } from "../../core/brain-cli/service.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { buildProjectDna } from "../dna/build.js";
+import { loadDecisionLedger } from "../decisions/ledger.js";
+import { readChangeLedger } from "../ledger/change-ledger.js";
+export async function queryMemory(rootInput, query) {
+    const root = resolveRepoRoot(rootInput);
+    const q = query.trim();
+    const limitations = [
+        "Institutional memory merges repo-local Brain, ADR/decision ledger, change ledger, and DNA — not a vector DB.",
+        "Ranking is substring match with simple scoring — not semantic search.",
+        "Cross-repo memory is not supported; query is scoped to the resolved catalog root.",
+    ];
+    if (!q) {
+        return { root, query: q, hits: [], limitations: [...limitations, "Empty query — no hits."] };
+    }
+    const hits = [];
+    const qLower = q.toLowerCase();
+    const brain = await loadLatestBrain(root);
+    if (brain) {
+        for (const bh of searchBrain(brain, q).slice(0, 15)) {
+            if (bh.text.includes(".private/") ||
+                bh.text.includes("AgentDoctorOS/") ||
+                bh.text.includes("oss-validation/")) {
+                continue;
+            }
+            hits.push({
+                source: "brain",
+                id: bh.id,
+                title: bh.kind,
+                excerpt: bh.text.slice(0, 280),
+                truth: "VERIFIED",
+                evidence: [{ path: ".agentdoctor/project-brain", excerpt: bh.text.slice(0, 120) }],
+            });
+        }
+    }
+    else {
+        limitations.push("No Project Brain snapshot — brain hits skipped.");
+    }
+    const decisions = await loadDecisionLedger(root);
+    for (const d of decisions.decisions) {
+        const hay = `${d.title} ${d.bodyExcerpt ?? ""}`.toLowerCase();
+        if (!hay.includes(qLower))
+            continue;
+        hits.push({
+            source: "decisions",
+            id: d.id,
+            title: d.title,
+            excerpt: (d.bodyExcerpt ?? d.title).slice(0, 280),
+            truth: d.truth,
+            evidence: d.evidence,
+        });
+    }
+    const changeLedger = await readChangeLedger(root);
+    for (const entry of changeLedger.entries) {
+        const hay = `${entry.task ?? ""} ${entry.plan ?? ""} ${entry.note ?? ""} ${(entry.files ?? []).join(" ")}`.toLowerCase();
+        if (!hay.includes(qLower))
+            continue;
+        hits.push({
+            source: "change-ledger",
+            id: entry.id,
+            title: entry.task ?? entry.id,
+            excerpt: (entry.note ?? entry.plan ?? entry.task ?? "").slice(0, 280),
+            truth: "VERIFIED",
+            evidence: [{ path: ".agentdoctor/change-ledger/entries.jsonl", excerpt: entry.id }],
+        });
+    }
+    const dna = await buildProjectDna(root);
+    const dnaHay = JSON.stringify({
+        name: dna.name,
+        frameworks: dna.frameworks,
+        languages: dna.languages,
+        services: dna.services,
+    }).toLowerCase();
+    if (dnaHay.includes(qLower)) {
+        hits.push({
+            source: "dna",
+            id: dna.fingerprint,
+            title: `Project DNA: ${dna.name}`,
+            excerpt: `Languages: ${dna.languages.join(", ")}; frameworks: ${dna.frameworks.join(", ")}`,
+            truth: dna.truth,
+            evidence: [{ path: ".agentdoctor/dna/project-dna.json", excerpt: dna.fingerprint }],
+        });
+    }
+    hits.sort((a, b) => b.excerpt.length - a.excerpt.length);
+    return {
+        root,
+        query: q,
+        hits: hits.slice(0, 40),
+        limitations,
+    };
+}

package/dist/product/ops/incident.d.ts

@@ -0,0 +1,20 @@
+import type { TruthLabel } from "../truth.js";
+export interface IncidentTimelineItem {
+    id: string;
+    hypothesis: string;
+    truth: TruthLabel;
+    relatedPaths: string[];
+    method: string;
+}
+export interface IncidentReport {
+    root: string;
+    timeline: IncidentTimelineItem[];
+    limitations: string[];
+}
+export declare function buildIncidentHypotheses(rootInput: string, options?: {
+    changedFiles?: string[];
+    gitHotspots?: Array<{
+        path: string;
+        commits: number;
+    }>;
+}): Promise<IncidentReport>;