@praneeth_54/agentdoctor 2.0.1 → 3.0.0

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,87 @@
+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)) {
+            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>;

package/dist/product/ops/incident.js

@@ -0,0 +1,61 @@
+import { analyzeGitIntelligence } from "../../intelligence/git/analyze.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+function normalizePaths(paths) {
+    return [...new Set(paths.map((p) => p.replace(/\\/g, "/")))].sort();
+}
+export async function buildIncidentHypotheses(rootInput, options) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Timeline items are hypotheses for investigation, not verified incident root cause.",
+        "VERIFIED items require explicit changedFiles input or git hotspot file paths.",
+    ];
+    const changed = normalizePaths(options?.changedFiles ?? []);
+    const timeline = [];
+    if (changed.length) {
+        timeline.push({
+            id: "changed-files",
+            hypothesis: "Recent changes concentrated in supplied changedFiles list",
+            truth: "VERIFIED",
+            relatedPaths: changed,
+            method: "caller-supplied changedFiles",
+        });
+    }
+    let hotspots = options?.gitHotspots;
+    if (!hotspots) {
+        const git = await analyzeGitIntelligence(root);
+        if (git.gitAvailable) {
+            hotspots = git.hotspots.map((h) => ({ path: h.path, commits: h.commits }));
+        }
+        else {
+            limitations.push("Git unavailable; hotspot hypotheses skipped.");
+        }
+    }
+    if (hotspots?.length) {
+        const top = [...hotspots].sort((a, b) => b.commits - a.commits).slice(0, 5);
+        for (const h of top) {
+            const overlapsChange = changed.some((c) => c === h.path || h.path.endsWith(c) || c.endsWith(h.path));
+            timeline.push({
+                id: `hotspot-${h.path.replace(/[^\w]/g, "_")}`,
+                hypothesis: "Frequent historical churn (git hotspot) may relate to instability",
+                truth: overlapsChange ? "VERIFIED" : "INFERRED",
+                relatedPaths: [h.path.replace(/\\/g, "/")],
+                method: `git log file appearances (commits=${h.commits})`,
+            });
+        }
+    }
+    if (changed.length && hotspots?.length) {
+        const hotSet = new Set(hotspots.map((h) => h.path.replace(/\\/g, "/")));
+        const overlap = changed.filter((c) => hotSet.has(c));
+        if (overlap.length) {
+            timeline.push({
+                id: "change-hotspot-overlap",
+                hypothesis: "Changed files overlap historical hotspots",
+                truth: "VERIFIED",
+                relatedPaths: overlap,
+                method: "intersection(changedFiles, gitHotspots)",
+            });
+        }
+    }
+    timeline.sort((a, b) => a.id.localeCompare(b.id));
+    return { root, timeline, limitations };
+}

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

@@ -0,0 +1,15 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface InfraArtifact {
+    kind: "docker" | "kubernetes" | "terraform" | "ci" | "compose-service" | "unknown";
+    path: string;
+    label: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface InfraReport {
+    root: string;
+    artifacts: InfraArtifact[];
+    services: string[];
+    limitations: string[];
+}
+export declare function analyzeInfra(rootInput: string, maxFileSizeBytes?: number): Promise<InfraReport>;

package/dist/product/ops/infra.js

@@ -0,0 +1,112 @@
+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 classifyPath(relativePath) {
+    const norm = relativePath.replace(/\\/g, "/");
+    const base = norm.split("/").pop()?.toLowerCase() ?? "";
+    if (base === "dockerfile" || base.startsWith("dockerfile.")) {
+        return {
+            kind: "docker",
+            path: norm,
+            label: "Dockerfile",
+            truth: "VERIFIED",
+            evidence: [{ path: norm }],
+        };
+    }
+    if (base === "docker-compose.yml" || base === "docker-compose.yaml" || base === "compose.yml") {
+        return {
+            kind: "docker",
+            path: norm,
+            label: "Docker Compose",
+            truth: "VERIFIED",
+            evidence: [{ path: norm }],
+        };
+    }
+    if (norm.includes(".github/workflows/") && (base.endsWith(".yml") || base.endsWith(".yaml"))) {
+        return {
+            kind: "ci",
+            path: norm,
+            label: "GitHub Actions workflow",
+            truth: "VERIFIED",
+            evidence: [{ path: norm }],
+        };
+    }
+    if (base.endsWith(".tf")) {
+        return {
+            kind: "terraform",
+            path: norm,
+            label: "Terraform",
+            truth: "VERIFIED",
+            evidence: [{ path: norm }],
+        };
+    }
+    if (norm.includes("kubernetes/") || base.includes("deployment") || base.includes("service")) {
+        if (base.endsWith(".yaml") || base.endsWith(".yml")) {
+            return {
+                kind: "kubernetes",
+                path: norm,
+                label: "Kubernetes manifest (heuristic)",
+                truth: "INFERRED",
+                evidence: [{ path: norm }],
+            };
+        }
+    }
+    return null;
+}
+function parseComposeServices(content, relativePath) {
+    const services = [];
+    let inServices = false;
+    for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (/^services:\s*$/i.test(trimmed)) {
+            inServices = true;
+            continue;
+        }
+        if (inServices) {
+            if (/^[a-zA-Z0-9_-]+:\s*$/.test(trimmed) && !trimmed.startsWith("version:")) {
+                const name = trimmed.replace(":", "");
+                if (name !== "services" && !name.includes(" "))
+                    services.push(name);
+            }
+            if (/^[a-zA-Z_]+:/.test(trimmed) &&
+                !line.startsWith(" ") &&
+                !line.startsWith("\t") &&
+                trimmed !== "services:") {
+                if (!trimmed.startsWith("services:"))
+                    inServices = false;
+            }
+        }
+    }
+    return services.map((s) => `${s}@${relativePath}`);
+}
+export async function analyzeInfra(rootInput, maxFileSizeBytes = DEFAULT_MAX_FILE_SIZE_BYTES) {
+    const root = resolveRepoRoot(rootInput);
+    const detection = await detectProject(root, maxFileSizeBytes);
+    const limitations = [
+        "Compose service names use simple line heuristics, not a full YAML parser.",
+        "Kubernetes detection is path/name heuristic.",
+    ];
+    const artifacts = [];
+    const services = [];
+    for (const entry of detection.discovery.files) {
+        const rel = entry.relativePath.replace(/\\/g, "/");
+        const artifact = classifyPath(rel);
+        if (artifact)
+            artifacts.push(artifact);
+        const base = rel.split("/").pop()?.toLowerCase() ?? "";
+        if (base === "docker-compose.yml" || base === "docker-compose.yaml" || base === "compose.yml") {
+            const text = await readTextFile(path.join(root, rel), maxFileSizeBytes);
+            if (text)
+                services.push(...parseComposeServices(text, rel));
+        }
+    }
+    artifacts.sort((a, b) => a.path.localeCompare(b.path));
+    return {
+        root,
+        artifacts,
+        services: [...new Set(services)].sort(),
+        limitations,
+    };
+}

package/dist/product/org/model.d.ts

@@ -0,0 +1,34 @@
+import type { TruthLabel } from "../truth.js";
+export interface OrgEntityRef {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface OrgProjectLink {
+    id: string;
+    name: string;
+    /** Absolute or repo-relative root path for this project within the workspace catalog */
+    rootPath: string;
+    teamIds: string[];
+    serviceIds: string[];
+    ownerIds: string[];
+}
+export interface OrganizationModel {
+    schemaVersion: 1;
+    updatedAt: string;
+    /** Catalog root this model was loaded from (not shared across repos automatically) */
+    catalogRoot: string;
+    teams: OrgEntityRef[];
+    projects: OrgProjectLink[];
+    services: OrgEntityRef[];
+    owners: OrgEntityRef[];
+    truth: TruthLabel;
+    limitations: string[];
+}
+export declare function loadOrganizationModel(rootInput: string): Promise<OrganizationModel>;
+export declare function saveOrganizationModel(rootInput: string, model: Omit<OrganizationModel, "schemaVersion" | "updatedAt" | "catalogRoot" | "truth" | "limitations">): Promise<OrganizationModel>;
+/** Register or update a project link under the catalog root (path must stay within catalogRoot). */
+export declare function linkProjectToOrgModel(rootInput: string, link: Omit<OrgProjectLink, "rootPath"> & {
+    rootPath?: string;
+}): Promise<OrganizationModel>;
+export declare function resolveLinkedProjectRoot(model: OrganizationModel, projectId: string): string | null;

package/dist/product/org/model.js

@@ -0,0 +1,195 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { redactSecrets } from "../../platform/security/redact.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { DEFAULT_MAX_FILE_SIZE_BYTES } from "../../constants.js";
+import { pathExists, readJsonFile } from "../../utils/fs.js";
+const FORBIDDEN_KEY = /^(secret|token|password|api[_-]?key|credential|private[_-]?key)$/i;
+function modelPath(root) {
+    return path.join(resolveRepoRoot(root), ".agentdoctor", "org", "model.json");
+}
+function sanitizeString(value) {
+    return redactSecrets(value).text.slice(0, 2000);
+}
+function sanitizeEntityRef(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    for (const key of Object.keys(o)) {
+        if (FORBIDDEN_KEY.test(key))
+            return null;
+    }
+    const id = typeof o.id === "string" ? sanitizeString(o.id.trim()) : "";
+    const name = typeof o.name === "string" ? sanitizeString(o.name.trim()) : "";
+    if (!id || !name)
+        return null;
+    const description = typeof o.description === "string" ? sanitizeString(o.description.trim()) : undefined;
+    return {
+        id,
+        name,
+        ...(description !== undefined && description.length > 0 ? { description } : {}),
+    };
+}
+function sanitizeProject(raw, catalogRoot) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const o = raw;
+    for (const key of Object.keys(o)) {
+        if (FORBIDDEN_KEY.test(key))
+            return null;
+    }
+    const id = typeof o.id === "string" ? sanitizeString(o.id.trim()) : "";
+    const name = typeof o.name === "string" ? sanitizeString(o.name.trim()) : "";
+    const rootPathRaw = typeof o.rootPath === "string" ? o.rootPath.trim() : catalogRoot;
+    if (!id || !name)
+        return null;
+    const resolved = path.isAbsolute(rootPathRaw)
+        ? path.normalize(rootPathRaw)
+        : path.normalize(path.join(catalogRoot, rootPathRaw));
+    if (!resolved.startsWith(catalogRoot)) {
+        return null;
+    }
+    const teamIds = Array.isArray(o.teamIds)
+        ? o.teamIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    const serviceIds = Array.isArray(o.serviceIds)
+        ? o.serviceIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    const ownerIds = Array.isArray(o.ownerIds)
+        ? o.ownerIds.filter((x) => typeof x === "string").map((x) => sanitizeString(x))
+        : [];
+    return { id, name, rootPath: resolved, teamIds, serviceIds, ownerIds };
+}
+function emptyModel(catalogRoot) {
+    return {
+        schemaVersion: 1,
+        updatedAt: new Date().toISOString(),
+        catalogRoot,
+        teams: [],
+        projects: [],
+        services: [],
+        owners: [],
+        truth: "VERIFIED",
+        limitations: [
+            "Org model is repo-local metadata only — not synced across machines or tenants.",
+            "Secret-like fields are rejected on load/save; values are redacted when persisted.",
+            "Linking a project root does not grant cross-repo file access — workspace rules still apply.",
+        ],
+    };
+}
+export async function loadOrganizationModel(rootInput) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const file = modelPath(catalogRoot);
+    if (!(await pathExists(file))) {
+        return emptyModel(catalogRoot);
+    }
+    const parsed = await readJsonFile(file, DEFAULT_MAX_FILE_SIZE_BYTES);
+    if (!parsed.ok || typeof parsed.data !== "object" || parsed.data === null) {
+        return {
+            ...emptyModel(catalogRoot),
+            truth: "PARTIAL",
+            limitations: [
+                ...emptyModel(catalogRoot).limitations,
+                "Corrupt org model file — using empty model.",
+            ],
+        };
+    }
+    const o = parsed.data;
+    const teams = [];
+    const services = [];
+    const owners = [];
+    const projects = [];
+    if (Array.isArray(o.teams)) {
+        for (const item of o.teams) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                teams.push(ref);
+        }
+    }
+    if (Array.isArray(o.services)) {
+        for (const item of o.services) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                services.push(ref);
+        }
+    }
+    if (Array.isArray(o.owners)) {
+        for (const item of o.owners) {
+            const ref = sanitizeEntityRef(item);
+            if (ref)
+                owners.push(ref);
+        }
+    }
+    if (Array.isArray(o.projects)) {
+        for (const item of o.projects) {
+            const link = sanitizeProject(item, catalogRoot);
+            if (link)
+                projects.push(link);
+        }
+    }
+    return {
+        schemaVersion: 1,
+        updatedAt: typeof o.updatedAt === "string" && o.updatedAt.trim()
+            ? o.updatedAt.trim()
+            : new Date().toISOString(),
+        catalogRoot,
+        teams,
+        projects,
+        services,
+        owners,
+        truth: "VERIFIED",
+        limitations: emptyModel(catalogRoot).limitations,
+    };
+}
+export async function saveOrganizationModel(rootInput, model) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const teams = model.teams
+        .map((t) => sanitizeEntityRef(t))
+        .filter((t) => t !== null);
+    const services = model.services
+        .map((s) => sanitizeEntityRef(s))
+        .filter((s) => s !== null);
+    const owners = model.owners
+        .map((o) => sanitizeEntityRef(o))
+        .filter((o) => o !== null);
+    const projects = model.projects
+        .map((p) => sanitizeProject(p, catalogRoot))
+        .filter((p) => p !== null);
+    const record = {
+        ...emptyModel(catalogRoot),
+        teams,
+        services,
+        owners,
+        projects,
+        updatedAt: new Date().toISOString(),
+    };
+    const dir = path.dirname(modelPath(catalogRoot));
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(modelPath(catalogRoot), `${JSON.stringify(record, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return record;
+}
+/** Register or update a project link under the catalog root (path must stay within catalogRoot). */
+export async function linkProjectToOrgModel(rootInput, link) {
+    const catalogRoot = resolveRepoRoot(rootInput);
+    const current = await loadOrganizationModel(catalogRoot);
+    const rootPath = link.rootPath ?? catalogRoot;
+    const sanitized = sanitizeProject({ ...link, rootPath }, catalogRoot);
+    if (!sanitized) {
+        throw new Error("Invalid project link — path escape or forbidden fields");
+    }
+    const projects = current.projects.filter((p) => p.id !== sanitized.id);
+    projects.push(sanitized);
+    return saveOrganizationModel(catalogRoot, {
+        teams: current.teams,
+        services: current.services,
+        owners: current.owners,
+        projects,
+    });
+}
+export function resolveLinkedProjectRoot(model, projectId) {
+    const hit = model.projects.find((p) => p.id === projectId);
+    return hit?.rootPath ?? null;
+}

package/dist/product/privacy/doctor.d.ts

@@ -0,0 +1,13 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface PrivacyFinding {
+    id: string;
+    label: string;
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+}
+export interface PrivacyDoctorReport {
+    root: string;
+    findings: PrivacyFinding[];
+    limitations: string[];
+}
+export declare function analyzePrivacySurface(rootInput: string): Promise<PrivacyDoctorReport>;

package/dist/product/privacy/doctor.js

@@ -0,0 +1,90 @@
+import { loadLatestBrain, searchBrain } from "../../core/brain-cli/service.js";
+import { resolveRepoRoot } from "../../utils/path.js";
+import { lineNumberAt, loadProjectSourceFiles } from "../evidence-scan.js";
+const PII_PATTERNS = [
+    {
+        id: "email-like",
+        label: "Email-like string",
+        re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+    },
+    {
+        id: "ssn-like",
+        label: "SSN-like digit groups",
+        re: /\b\d{3}-\d{2}-\d{4}\b/g,
+    },
+    {
+        id: "credit-card-like",
+        label: "Credit-card-like digit groups",
+        re: /\b(?:\d[ -]*?){13,19}\b/g,
+    },
+];
+function redactPiiExcerpt(line, match) {
+    const idx = line.indexOf(match);
+    if (idx < 0)
+        return "[REDACTED]";
+    const before = line.slice(0, idx).slice(-24);
+    const after = line.slice(idx + match.length).slice(0, 12);
+    return `${before}[REDACTED]${after}`.trim().slice(0, 120);
+}
+export async function analyzePrivacySurface(rootInput) {
+    const root = resolveRepoRoot(rootInput);
+    const limitations = [
+        "Privacy doctor is a lightweight PII-ish heuristic scan — not legal/compliance advice (not GDPR/HIPAA/PCI attestation).",
+        "Matches are INFERRED; many are fixtures, tests, or placeholders.",
+        "Matched values are redacted in excerpts; never export raw PII from this report.",
+    ];
+    const findings = [];
+    const { files } = await loadProjectSourceFiles(root, () => true);
+    for (const file of files) {
+        for (const pattern of PII_PATTERNS) {
+            pattern.re.lastIndex = 0;
+            let match;
+            while ((match = pattern.re.exec(file.content)) !== null) {
+                const raw = match[0] ?? "";
+                if (pattern.id === "credit-card-like" && raw.replace(/\D/g, "").length < 13)
+                    continue;
+                const line = lineNumberAt(file.content, match.index);
+                const lineText = file.content.split(/\r?\n/)[line - 1] ?? "";
+                findings.push({
+                    id: pattern.id,
+                    label: pattern.label,
+                    truth: "INFERRED",
+                    evidence: [
+                        {
+                            path: file.relativePath,
+                            line,
+                            excerpt: redactPiiExcerpt(lineText, raw),
+                        },
+                    ],
+                });
+                if (findings.length >= 100)
+                    break;
+            }
+            if (findings.length >= 100)
+                break;
+        }
+        if (findings.length >= 100) {
+            limitations.push("PII finding cap reached (100)");
+            break;
+        }
+    }
+    const brain = await loadLatestBrain(root);
+    if (brain) {
+        const brainHits = searchBrain(brain, "email");
+        if (brainHits.length > 0) {
+            findings.push({
+                id: "brain-claim-hint",
+                label: "Project brain mentions email-related claims (review manually)",
+                truth: "INFERRED",
+                evidence: brainHits.slice(0, 3).map((h) => ({
+                    path: ".agentdoctor/project-brain",
+                    excerpt: h.text.slice(0, 100),
+                })),
+            });
+        }
+    }
+    else {
+        limitations.push("Project brain not available for supplemental search.");
+    }
+    return { root, findings, limitations };
+}

package/dist/product/requirements/trace.d.ts

@@ -0,0 +1,21 @@
+import type { ProductEvidence, TruthLabel } from "../truth.js";
+export interface RequirementTrace {
+    id: string;
+    title: string;
+    sourcePath: string;
+    sourceLine: number;
+    acceptanceCriteria: string[];
+    truth: TruthLabel;
+    evidence: ProductEvidence[];
+    missingTestHeuristic: boolean;
+    missingTestNote?: string;
+}
+export interface RequirementsTraceReport {
+    root: string;
+    requirements: RequirementTrace[];
+    limitations: string[];
+}
+/**
+ * Scan repository docs for requirements / user stories with file evidence only.
+ */
+export declare function traceRequirements(rootInput: string, maxFileSizeBytes?: number): Promise<RequirementsTraceReport>;