@praneeth_54/agentdoctor 3.0.2 → 3.0.3

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.3] — 2026-09-27
+
+Patch release on top of public **3.0.2**: Brain → Project Chat evidence bridge and
+real operation-based progress UX for `agentdoctor ask`.
+
+Public relationship:
+
+- **3.0.2** remains the immutable public discovery patch (`v3.0.2` → `8d41936`).
+- **3.0.3** packages the finalize work from `a586cdf` (Brain→Chat + ask progress).
+- Does **not** rewrite **3.0.0**, **3.0.1**, or **3.0.2** history.
+
+### Fixed
+
+- Deterministic `agentdoctor ask` / Project Chat now consumes searchable Project Brain claims/components as first-class **INFERRED** evidence (aligned with `brain search`).
+- Brain-derived source paths are ownership-gated before excerpts; Brain claims are never auto-upgraded to **VERIFIED**.
+- `.agentdoctor/**` control-plane paths cannot become **VERIFIED** application source evidence.
+- Architecture/module answers prioritize Brain + owned sources over generic minified graph noise.
+- Ownership, containment, HOME/broad-root, `.private`, nested-repo, symlink, and stale-brain protections remain enforced.
+
+### Added
+
+- `agentdoctor ask` progress UX driven by real pipeline stages (understand → search → retrieve → verify → prepare).
+- Progress writes to stderr (TTY spinner / non-TTY stable lines); answers and `--json` stay on stdout without contamination.
+- No artificial delays — spinner frames only animate while real work is in flight.
+
+### Tests
+
+- Added `tests/unit/agent/chat-brain-context.test.ts` for Brain → ask evidence, control-plane hostility, stale brain, and UNKNOWN.
+- Added `tests/unit/cli/ask-progress.test.ts` for TTY/non-TTY/JSON/error progress lifecycle.
+
 ## [3.0.2] — 2026-09-27
 
 Patch release: fix current-directory project discovery for `agentdoctor start`.
@@ -14,7 +44,7 @@ Patch release: fix current-directory project discovery for `agentdoctor start`.
 Public relationship:
 
 - **3.0.0** and **3.0.1** remain immutable public releases.
-- **3.0.2** does not rewrite prior npm/GitHub history.
+- **3.0.2** is the public discovery patch (`v3.0.2` → `8d41936`). Brain→Chat and ask progress ship in **3.0.3**.
 
 ### Fixed
 
@@ -622,7 +652,8 @@ First public beta.
 - Not a complete secret scanner
 - Git “tracked secret” detection deferred
 
-[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v3.0.2...HEAD
+[Unreleased]: https://github.com/pranee54/AgentDoctor/compare/v3.0.3...HEAD
+[3.0.3]: https://github.com/pranee54/AgentDoctor/compare/v3.0.2...v3.0.3
 [3.0.2]: https://github.com/pranee54/AgentDoctor/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/pranee54/AgentDoctor/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/pranee54/AgentDoctor/compare/v2.1.0...v3.0.0

package/README.md

@@ -281,15 +281,15 @@ Student path: `learn` → ask → viva → docs → Build With Me (with `--appro
 Requires **Node.js 20+**.
 
 ```bash
-npm install -g @praneeth_54/agentdoctor@3.0.2
-agentdoctor --version   # 3.0.2
+npm install -g @praneeth_54/agentdoctor@3.0.3
+agentdoctor --version   # 3.0.3
 agentdoctor --help
 ```
 
 Or without global install:
 
 ```bash
-npx @praneeth_54/agentdoctor@3.0.2 --help
+npx @praneeth_54/agentdoctor@3.0.3 --help
 ```
 
 ---
@@ -298,7 +298,7 @@ npx @praneeth_54/agentdoctor@3.0.2 --help
 
 ```bash
 # 1. Install
-npm install -g @praneeth_54/agentdoctor@3.0.2
+npm install -g @praneeth_54/agentdoctor@3.0.3
 
 # 2. Enter YOUR project (not your home folder)
 cd /path/to/my-project
@@ -586,6 +586,7 @@ Post-acceptance ideas for later releases: maintainers see [docs/internal/POST_3_
 | **3.0.0 (released)** | Original public release (`v3.0.0` → `c21faf1`)                           |
 | **3.0.1 (released)** | Freeze remediation / ownership & security hardening follow-up            |
 | **3.0.2 (released)** | `start` discovery aligned with deterministic `detectProject`             |
+| **3.0.3 (released)** | Brain → Project Chat evidence + `ask` progress UX                        |
 | **Coming soon**      | Maturity, language depth, runtime adapters, DX — not promised ship dates |
 
 ---

package/dist/agent/chat/deterministic.d.ts

@@ -1,6 +1,8 @@
 import type { ChatTurnResponse } from "./types.js";
+import { type AskProgressReporter } from "../progress.js";
 export declare function answerDeterministicProjectQuestion(options: {
     root: string;
     question: string;
     sessionId: string;
+    progress?: AskProgressReporter;
 }): Promise<ChatTurnResponse>;

package/dist/agent/chat/deterministic.js

@@ -4,11 +4,14 @@ import { analyzeDependencies } from "../../product/deps/analyze.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { resolveRepoRoot } from "../../utils/path.js";
 import { retrieveProjectContext } from "../context/retrieve.js";
+import { extractQueryTerms } from "../context/brain-evidence.js";
 import { buildChatTurnResponse } from "./response.js";
+import { noopAskProgress } from "../progress.js";
 const ARCH_RE = /architecture|structure|module|layout|what (is|does) (this|my) project|project overview|understand (my |this )?project/i;
 const AUTH_RE = /auth|login|password|session|jwt|oauth/i;
 const DEPS_RE = /depend|package|lockfile|npm|yarn|pnpm/i;
 const DB_RE = /database|db\.|sql|prisma|query\(/i;
+const MODULE_RE = /\bmodule\b|\bcomponent\b|\bprovides?\b|\bbelong/i;
 /** ReDoS-safe: avoid `where.*…` / `how.*…` backtracking on uncontrolled chat input. */
 function isStartQuestion(q) {
     if (/application start|entry\s*point/i.test(q))
@@ -28,14 +31,42 @@ function isArchitectureQuestion(q) {
         return true;
     return false;
 }
+function isModuleQuestion(q) {
+    return MODULE_RE.test(q) || extractQueryTerms(q).length > 0;
+}
 export async function answerDeterministicProjectQuestion(options) {
     const root = resolveRepoRoot(options.root);
     const q = options.question.trim();
+    const progress = options.progress ?? noopAskProgress;
+    progress.stage("understand", "start");
+    const terms = extractQueryTerms(q);
+    progress.stage("understand", "ok", terms.length ? `focus: ${terms.slice(0, 4).join(", ")}` : undefined);
     const context = await retrieveProjectContext({
         root,
         query: q,
         budgetTokens: 4_000,
+        maxSourceFiles: 8,
+        progress,
     });
+    progress.stage("prepare", "start");
+    try {
+        const response = await buildDeterministicAnswer({
+            root,
+            q,
+            terms,
+            context,
+            sessionId: options.sessionId,
+        });
+        progress.stage("prepare", "ok");
+        return response;
+    }
+    catch (error) {
+        progress.stage("prepare", "fail", error instanceof Error ? error.message : String(error));
+        throw error;
+    }
+}
+async function buildDeterministicAnswer(options) {
+    const { root, q, terms, context, sessionId } = options;
     const sections = [
         "Deterministic project answer (no LLM). Evidence from DNA, graph, brain, and dependency analyzers.",
         "",
@@ -46,6 +77,27 @@ export async function answerDeterministicProjectQuestion(options) {
     sections.push(`Frameworks: ${dna.frameworks.join(", ") || "UNKNOWN"}`);
     sections.push(`Monorepo: ${dna.monorepo.isMonorepo ? dna.monorepo.tool : "no"}`);
     sections.push("");
+    const brainCitations = context.citations.filter((c) => c.source === "brain" || c.evidenceType === "project-brain");
+    const sourceCitations = context.citations.filter((c) => c.confidence === "VERIFIED" && c.evidenceType === "source-code" && c.path);
+    if (brainCitations.length > 0 && (isModuleQuestion(q) || isArchitectureQuestion(q))) {
+        const focus = terms.length ? terms.join(", ") : "project";
+        sections.push(`[INFERRED] Project Brain evidence for: ${focus}`);
+        for (const c of brainCitations.slice(0, 14)) {
+            sections.push(`  - ${c.excerpt ?? c.note ?? "brain claim"}`);
+        }
+        sections.push("");
+        if (sourceCitations.length) {
+            sections.push("[VERIFIED] Owned source paths linked from Brain / retrieval:");
+            for (const c of sourceCitations.slice(0, 10)) {
+                sections.push(`  - ${c.path}`);
+            }
+            sections.push("");
+        }
+        else {
+            sections.push("[INFERRED] No owned source excerpts resolved for these Brain claims; structural evidence only.");
+            sections.push("");
+        }
+    }
     if (AUTH_RE.test(q)) {
         const authFiles = context.citations
             .filter((c) => c.path && /auth|login|session|password/i.test(c.path))
@@ -157,11 +209,28 @@ export async function answerDeterministicProjectQuestion(options) {
         sections.push(`Lockfiles: ${deps.lockfilesPresent.join(", ") || "none"}`);
         sections.push("");
     }
-    if (isArchitectureQuestion(q)) {
+    if (isArchitectureQuestion(q) && brainCitations.length === 0) {
         try {
             const graph = await buildIntelligenceGraph({ root, mode: "auto" });
             sections.push(`[INFERRED] Graph: ${graph.nodes.length} nodes, ${graph.edges.length} edges (${graph.builder})`);
-            const sample = graph.nodes.filter((n) => n.path).slice(0, 6);
+            const termLower = terms.map((t) => t.toLowerCase());
+            const filtered = graph.nodes
+                .filter((n) => n.path && n.label)
+                .filter((n) => {
+                if (/\.min\.js$/i.test(n.path) || /chart\.umd|node_modules/i.test(n.path))
+                    return false;
+                if (termLower.length === 0)
+                    return n.kind === "file" || n.kind === "module";
+                const blob = `${n.label} ${n.path}`.toLowerCase();
+                return termLower.some((t) => blob.includes(t));
+            })
+                .slice(0, 8);
+            const sample = filtered.length
+                ? filtered
+                : graph.nodes
+                    .filter((n) => n.path && !/\.min\.js$/i.test(n.path))
+                    .filter((n) => n.kind === "file")
+                    .slice(0, 6);
             for (const n of sample) {
                 sections.push(`  - ${n.kind}: ${n.label}${n.path ? ` @ ${n.path}` : ""}`);
             }
@@ -171,6 +240,17 @@ export async function answerDeterministicProjectQuestion(options) {
         }
         sections.push("");
     }
+    else if (isArchitectureQuestion(q)) {
+        // Brain already rendered; add a short graph filter if present in context.
+        const graphCite = context.citations.find((c) => c.source === "graph");
+        if (graphCite?.excerpt) {
+            sections.push("[INFERRED] Query-filtered graph nodes:");
+            for (const line of graphCite.excerpt.split("\n").slice(0, 6)) {
+                sections.push(`  - ${line}`);
+            }
+            sections.push("");
+        }
+    }
     const brain = await getBrainStatus(root);
     if (brain.hasSnapshot) {
         sections.push(`[INFERRED] Project brain snapshot present (${brain.snapshotCount} stored; latest ${brain.latestSnapshotId ?? "unknown"}).`);
@@ -178,6 +258,14 @@ export async function answerDeterministicProjectQuestion(options) {
     else {
         sections.push("[UNKNOWN] No project brain snapshot — run brain compile for richer answers.");
     }
+    if (brainCitations.length === 0 &&
+        sourceCitations.length === 0 &&
+        !AUTH_RE.test(q) &&
+        !DEPS_RE.test(q) &&
+        !isArchitectureQuestion(q)) {
+        sections.push("");
+        sections.push("[UNKNOWN] Insufficient Brain/source evidence for this question — try a more specific module or path name.");
+    }
     sections.push("");
     sections.push("Limitations: deterministic answers cannot invent behavior not present in evidence.");
     const bundle = {
@@ -188,7 +276,7 @@ export async function answerDeterministicProjectQuestion(options) {
         ],
     };
     return buildChatTurnResponse({
-        sessionId: options.sessionId,
+        sessionId,
         modelText: sections.join("\n"),
         context: bundle,
         provider: "deterministic",

package/dist/agent/chat/response.js

@@ -4,8 +4,12 @@ import { truthLabelHelp } from "../context/truth.js";
  * Never invents line ranges. Citations come only from the context bundle.
  */
 export function buildChatTurnResponse(options) {
-    const citations = options.context.citations.filter((c) => c.path && c.confidence === "VERIFIED");
-    const contextPaths = citations.map((c) => c.path).filter(Boolean);
+    const verifiedSource = options.context.citations.filter((c) => c.path && c.confidence === "VERIFIED" && c.evidenceType === "source-code");
+    const brainCitations = options.context.citations.filter((c) => c.source === "brain" || c.evidenceType === "project-brain");
+    const graphCitations = options.context.citations.filter((c) => c.source === "graph" || c.evidenceType === "graph");
+    // Surface verified source + brain/graph evidence (brain is never upgraded to VERIFIED).
+    const citations = [...verifiedSource, ...brainCitations, ...graphCitations];
+    const contextPaths = verifiedSource.map((c) => c.path).filter(Boolean);
     const mentioned = extractMentionedPaths(options.modelText, contextPaths);
     const truthClaims = [];
     for (const path of mentioned) {
@@ -15,13 +19,21 @@ export function buildChatTurnResponse(options) {
             citationPaths: [path],
         });
     }
-    if (citations.length === 0) {
+    const hasUsableEvidence = verifiedSource.length > 0 || brainCitations.length > 0;
+    if (!hasUsableEvidence) {
         truthClaims.push({
             text: "Insufficient repository evidence was retrieved for this question.",
             label: "UNKNOWN",
             citationPaths: [],
         });
     }
+    else if (brainCitations.length > 0 && verifiedSource.length === 0) {
+        truthClaims.push({
+            text: "Answer grounded in Project Brain structural evidence (INFERRED; no owned source excerpts).",
+            label: "INFERRED",
+            citationPaths: [],
+        });
+    }
     else if (options.modelText.trim()) {
         truthClaims.push({
             text: "Interpretive explanation based on retrieved project evidence.",
@@ -83,7 +95,16 @@ export function formatChatResponseForCli(response) {
     }
     if (response.citations.length > 0) {
         lines.push("Evidence:");
-        for (const c of response.citations.slice(0, 12)) {
+        for (const c of response.citations.slice(0, 16)) {
+            if (c.source === "brain" || c.evidenceType === "project-brain") {
+                lines.push(`  - ${c.excerpt ?? c.note ?? "brain claim"} (${c.confidence})`);
+                continue;
+            }
+            if (c.source === "graph" || c.evidenceType === "graph") {
+                const first = (c.excerpt ?? c.note ?? "graph").split("\n")[0] ?? "graph";
+                lines.push(`  - ${first} (${c.confidence})`);
+                continue;
+            }
             const path = c.path ?? "(unknown)";
             lines.push(`  - ${path}${c.range ? `:${c.range}` : ""} (${c.confidence})`);
         }

package/dist/agent/chat/service.d.ts

@@ -15,6 +15,7 @@ export declare class ChatService {
     private readonly budgetTokens;
     private readonly persistAudit;
     private readonly systemPrompt;
+    private readonly progress;
     private auditSession;
     private graphCache;
     private lastContext;

package/dist/agent/chat/service.js

@@ -9,6 +9,7 @@ import { PROJECT_CHAT_SYSTEM_PROMPT, wrapProjectData } from "./prompts.js";
 import { formatProjectSummary, summarizeProjectForChat, } from "./project-summary.js";
 import { buildChatTurnResponse, formatChatResponseForCli } from "./response.js";
 import { answerDeterministicProjectQuestion } from "./deterministic.js";
+import { noopAskProgress } from "../progress.js";
 export const CHAT_PROVIDER_NONE_MESSAGE = `AI chat is not configured.
 
 Configure an AI provider to use AgentDoctor Project Chat.
@@ -28,6 +29,7 @@ export class ChatService {
     budgetTokens;
     persistAudit;
     systemPrompt;
+    progress;
     auditSession;
     graphCache;
     lastContext;
@@ -37,6 +39,7 @@ export class ChatService {
         this.provider = options.provider ?? createModelProvider(loadAiConfig());
         this.budgetTokens = options.budgetTokens ?? 6_000;
         this.persistAudit = options.persistAudit !== false;
+        this.progress = options.progress ?? noopAskProgress;
         this.systemPrompt = options.systemPromptAddon
             ? `${PROJECT_CHAT_SYSTEM_PROMPT}\n\n${options.systemPromptAddon}`
             : PROJECT_CHAT_SYSTEM_PROMPT;
@@ -104,27 +107,40 @@ export class ChatService {
                 root: this.root,
                 question: safeUser,
                 sessionId: this.sessionId,
+                progress: this.progress,
             });
+            this.lastContext = undefined;
             this.memory.addAssistant(response.message, response.contextPaths);
             await this.audit("prompt", "CHAT_DETERMINISTIC", { status: response.status });
             return response;
         }
+        this.progress.stage("understand", "start");
         const query = this.memory.resolveQuery(safeUser);
-        const context = await retrieveProjectContext({
-            root: this.root,
-            query,
-            budgetTokens: this.budgetTokens,
-            includePaths: [
-                ...this.memory.getReferencedPaths().slice(-8),
-                ...this.memory.getLastContextPaths().slice(-8),
-            ],
-            ...(this.graphCache ? { graph: this.graphCache } : {}),
-        });
+        this.progress.stage("understand", "ok");
+        let context;
+        try {
+            context = await retrieveProjectContext({
+                root: this.root,
+                query,
+                budgetTokens: this.budgetTokens,
+                includePaths: [
+                    ...this.memory.getReferencedPaths().slice(-8),
+                    ...this.memory.getLastContextPaths().slice(-8),
+                ],
+                ...(this.graphCache ? { graph: this.graphCache } : {}),
+                progress: this.progress,
+            });
+        }
+        catch (error) {
+            this.progress.stop();
+            throw error;
+        }
         this.lastContext = context;
         await this.audit("file-read", "CHAT_CONTEXT_RETRIEVED", {
             citations: String(context.citations.length),
             tokens: String(context.estimatedTokens),
         });
+        this.progress.stage("prepare", "start");
         const history = this.memory.historyForModel().slice(0, -1); // exclude current user (added separately)
         const messages = [
             { role: "system", content: this.systemPrompt },
@@ -142,6 +158,7 @@ export class ChatService {
             maxTokens: 2048,
         });
         if (modelResult.error) {
+            this.progress.stage("prepare", "fail", sanitizeProviderError(modelResult.error));
             const response = buildChatTurnResponse({
                 sessionId: this.sessionId,
                 modelText: `AgentDoctor could not reach the configured AI provider.\n\nProvider: ${modelResult.provider}\nModel: ${modelResult.model}\nError: ${sanitizeProviderError(modelResult.error)}`,
@@ -158,6 +175,7 @@ export class ChatService {
             });
             return response;
         }
+        this.progress.stage("prepare", "ok");
         const text = redactForModel(modelResult.message.content || "");
         const response = buildChatTurnResponse({
             sessionId: this.sessionId,

package/dist/agent/chat/types.d.ts

@@ -1,5 +1,6 @@
 import type { TruthLabel, ContextCitation } from "../context/types.js";
 import type { AiProviderId, ModelProvider, TokenUsage } from "../../ai/types.js";
+import type { AskProgressReporter } from "../progress.js";
 export type ChatRole = "system" | "user" | "assistant";
 export interface ChatMessage {
     role: ChatRole;
@@ -45,4 +46,6 @@ export interface ChatServiceOptions {
     persistAudit?: boolean;
     /** Appended to PROJECT_CHAT_SYSTEM_PROMPT (modes) */
     systemPromptAddon?: string;
+    /** Optional ask progress reporter (CLI TTY UX). */
+    progress?: AskProgressReporter;
 }

package/dist/agent/context/brain-evidence.d.ts

@@ -0,0 +1,26 @@
+import { type BrainSearchHit } from "../../core/brain-cli/service.js";
+import type { ProjectBrain } from "../../core/understanding/brain/index.js";
+import type { ContextCitation } from "./types.js";
+/**
+ * AgentDoctor control-plane under `.agentdoctor/**` — usable internally,
+ * never as ordinary VERIFIED application source evidence.
+ */
+export declare function isControlPlaneRelativePath(relativePath: string): boolean;
+/** Significant tokens from a natural-language project question. */
+export declare function extractQueryTerms(query: string): string[];
+export interface BrainEvidencePack {
+    brain: ProjectBrain | null;
+    hits: BrainSearchHit[];
+    citations: ContextCitation[];
+    /** Owned-looking source paths derived from claims/components/evidence (not yet ownership-gated). */
+    candidateSourcePaths: string[];
+    limitations: string[];
+}
+/**
+ * Search the latest usable Project Brain for query-relevant claims/components.
+ * Brain hits are INFERRED structural evidence — never auto-upgraded to VERIFIED.
+ * Stale ownership-boundary brains load as null (same as CLI brain status).
+ */
+export declare function collectBrainEvidenceForQuery(root: string, query: string, options?: {
+    maxHits?: number;
+}): Promise<BrainEvidencePack>;