@praneeth_54/agentdoctor 2.1.0 → 3.0.1

package/dist/ai/redact.js

@@ -1,18 +1,58 @@
 /**
  * Redaction for outbound model payloads.
  * Extends the local-ai redaction patterns; never send raw secrets to providers.
+ * Patterns avoid nested unbounded quantifiers (ReDoS-safe).
  */
-const SECRET_PATTERNS = [
+const REDACTED = "[REDACTED]";
+const SIMPLE_SECRET_PATTERNS = [
     /\b(AKIA[0-9A-Z]{16})\b/g,
     /\b(ghp_[A-Za-z0-9]{36})\b/g,
-    /\b(sk-[A-Za-z0-9]{20,})\b/g,
-    /-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/g,
-    /\b((?:export\s+)?(?:AWS_SECRET_ACCESS_KEY|GITHUB_TOKEN|NPM_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|STRIPE_SECRET_KEY|AGENTDOCTOR_AI_API_KEY)\s*=\s*)(['"]?)[^\s'"]+\2/gi,
+    /\b(sk-[A-Za-z0-9]{20,80})\b/g,
+    /\b((?:export\s+)?(?:AWS_SECRET_ACCESS_KEY|GITHUB_TOKEN|NPM_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|STRIPE_SECRET_KEY|AGENTDOCTOR_AI_API_KEY)\s*=\s*)(\S+)/gi,
 ];
+/** Linear scan — avoids polynomial backtracking on PEM fences. */
+function redactPrivateKeyBlocks(text) {
+    const beginToken = "-----BEGIN ";
+    const endToken = "-----END ";
+    const keySuffix = "PRIVATE KEY-----";
+    let out = "";
+    let i = 0;
+    while (i < text.length) {
+        const start = text.indexOf(beginToken, i);
+        if (start === -1) {
+            out += text.slice(i);
+            break;
+        }
+        out += text.slice(i, start);
+        const afterBegin = start + beginToken.length;
+        const keyLabelEnd = text.indexOf(keySuffix, afterBegin);
+        if (keyLabelEnd === -1 || keyLabelEnd - afterBegin > 64) {
+            out += text.slice(start, afterBegin);
+            i = afterBegin;
+            continue;
+        }
+        const headerEnd = keyLabelEnd + keySuffix.length;
+        const endStart = text.indexOf(endToken, headerEnd);
+        if (endStart === -1) {
+            out += text.slice(start, headerEnd);
+            i = headerEnd;
+            continue;
+        }
+        const endLabelEnd = text.indexOf(keySuffix, endStart + endToken.length);
+        if (endLabelEnd === -1 || endLabelEnd - (endStart + endToken.length) > 64) {
+            out += text.slice(start, headerEnd);
+            i = headerEnd;
+            continue;
+        }
+        out += REDACTED;
+        i = endLabelEnd + keySuffix.length;
+    }
+    return out;
+}
 export function redactForModel(text) {
-    let out = text;
-    for (const re of SECRET_PATTERNS) {
-        out = out.replace(re, "[REDACTED]");
+    let out = redactPrivateKeyBlocks(text);
+    for (const re of SIMPLE_SECRET_PATTERNS) {
+        out = out.replace(re, (_m, prefix) => typeof prefix === "string" && prefix.includes("=") ? `${prefix}${REDACTED}` : REDACTED);
     }
     return out;
 }

package/dist/ai/types.d.ts

@@ -2,7 +2,7 @@
  * Provider-agnostic model types for AgentDoctor 2.1 Project AI Agent.
  * The model reasons; AgentDoctor owns context, tools, and verification.
  */
-export type AiProviderId = "none" | "mock" | "openai-compatible" | "ollama" | "anthropic" | "gemini";
+export type AiProviderId = "none" | "deterministic" | "mock" | "openai-compatible" | "ollama" | "anthropic" | "gemini";
 export type ChatRole = "system" | "user" | "assistant" | "tool";
 export interface ChatMessage {
     role: ChatRole;

package/dist/cli/commands/agent.d.ts

@@ -1,3 +1,4 @@
+import { type AgentRole } from "../../agent/roles.js";
 import { type ExitCode } from "../../types/index.js";
 /**
  * agentdoctor plan — produce an implementation plan (no writes unless --apply elsewhere).
@@ -24,4 +25,5 @@ export declare function runAgentCommand(options: {
     applyOpsJson?: string;
     verify?: boolean;
     runTests?: boolean;
+    role?: AgentRole;
 }): Promise<ExitCode>;

package/dist/cli/commands/agent.js

@@ -1,15 +1,21 @@
 import { approvePlan, buildAgentPlan, formatAgentPlan } from "../../agent/plan.js";
 import { evaluateApproval, formatApprovalPrompt } from "../../agent/approvals.js";
 import { runCodingLoop } from "../../agent/loop.js";
+import { runRoleAgent } from "../../agent/roles.js";
 import { executeAgentTool, getToolSpec, listAgentToolSpecs, newToolCall, } from "../../agent/tools/index.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { colors } from "../../utils/colors.js";
 /**
  * agentdoctor plan — produce an implementation plan (no writes unless --apply elsewhere).
  */
 export async function runPlanCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const plan = await buildAgentPlan({ root, goal: options.goal });
     if (options.approve) {
         const approved = approvePlan(plan, true);
@@ -34,7 +40,12 @@ export async function runPlanCommand(options) {
  * agentdoctor agent — inspect, plan, and (with --approve) mutate via controlled tools.
  */
 export async function runAgentCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const approvedByHuman = options.approve === true;
     if (options.listTools) {
         const tools = listAgentToolSpecs({ includeWrite: true, includeExecute: true });
@@ -107,14 +118,24 @@ export async function runAgentCommand(options) {
                 return EXIT_CODES.USAGE_ERROR;
             }
         }
-        const result = await runCodingLoop({
-            root,
-            goal: options.goal,
-            approvedByHuman: true,
-            ...(toolCalls ? { toolCalls } : {}),
-            verify: options.verify !== false,
-            runTests: options.runTests === true,
-        });
+        const result = options.role
+            ? await runRoleAgent({
+                role: options.role,
+                root,
+                goal: options.goal,
+                approvedByHuman: true,
+                ...(toolCalls ? { toolCalls } : {}),
+                verify: options.verify !== false,
+                runTests: options.runTests === true,
+            })
+            : await runCodingLoop({
+                root,
+                goal: options.goal,
+                approvedByHuman: true,
+                ...(toolCalls ? { toolCalls } : {}),
+                verify: options.verify !== false,
+                runTests: options.runTests === true,
+            });
         if (options.json) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         }

package/dist/cli/commands/architecture.js

@@ -1,5 +1,5 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { buildC4Views } from "../../architecture/c4.js";
 import { checkArchitectureAtRoot, explainArchitecture, initArchitecture, loadArchitectureContract, } from "../../architecture/contract.js";
@@ -7,7 +7,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runArchitectureCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         switch (options.action) {
             case "init": {

package/dist/cli/commands/brain.js

@@ -1,12 +1,17 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { exportBrain, getBrainStatus, importBrain, initBrainStore, inspectBrainSummary, listBrainSnapshots, loadLatestBrain, rebuildBrain, searchBrain, showBrainSnapshot, } from "../../core/brain-cli/service.js";
 import { listProposals, reviewProposal, writeBrainProductSnapshot, } from "../../core/brain-product/init.js";
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runBrainCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const json = options.json === true;
     try {
         switch (options.action) {

package/dist/cli/commands/chat.js

@@ -1,9 +1,9 @@
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { ChatService, CHAT_PROVIDER_NONE_MESSAGE, formatChatResponseForCli, } from "../../agent/chat/index.js";
+import { ChatService, formatChatResponseForCli } from "../../agent/chat/index.js";
 import { MockModelProvider, createModelProvider, loadAiConfig } from "../../ai/index.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { colors } from "../../utils/colors.js";
 function printBanner(options) {
     const lines = [
@@ -51,7 +51,12 @@ function printHelp() {
     ].join("\n"));
 }
 export async function runAskCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const provider = options.useMock ? new MockModelProvider() : createModelProvider(loadAiConfig());
     const chat = new ChatService({
         root,
@@ -78,7 +83,12 @@ export async function runAskCommand(options) {
     }
 }
 export async function runChatCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const provider = options.useMock ? new MockModelProvider() : createModelProvider(loadAiConfig());
     const chat = new ChatService({
         root,
@@ -94,9 +104,7 @@ export async function runChatCommand(options) {
         frameworks: started.summary.frameworks,
     });
     if (provider.id === "none" && !options.useMock) {
-        process.stdout.write(`${CHAT_PROVIDER_NONE_MESSAGE}\n`);
-        await chat.end();
-        return EXIT_CODES.USAGE_ERROR;
+        process.stdout.write("Deterministic project chat (no LLM). Architecture, auth, and dependency questions use local analyzers.\n\n");
     }
     const scripted = options.scriptedInputs ? [...options.scriptedInputs] : undefined;
     const rl = scripted === undefined

package/dist/cli/commands/complete.js

@@ -1,5 +1,5 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { runProjectInit } from "../../core/brain-product/init.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { analyzeGitIntelligence, deadCodeCategory } from "../../intelligence/git/analyze.js";
@@ -14,7 +14,12 @@ function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runInitCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const result = await runProjectInit(root, {
         ...(options.name ? { projectName: options.name } : {}),
         ...(options.domain ? { businessDomain: options.domain } : {}),
@@ -27,7 +32,12 @@ export async function runInitCommand(options) {
     return EXIT_CODES.SUCCESS;
 }
 export async function runV2SurfaceCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         switch (options.action) {
             case "graph-ast": {

package/dist/cli/commands/fix.js

@@ -6,6 +6,7 @@ import { buildFixPlan } from "../../core/fix/plan.js";
 import { renderFixPlanTerminal } from "../../core/fix/render.js";
 import { runFix } from "../../core/fix/run.js";
 import { scan } from "../../core/scanner/scan.js";
+import { classifyBroadUserScanRoot } from "../../product/discovery/roots.js";
 import { colors } from "../../utils/colors.js";
 /**
  * Safe Repository Mutation — apply allowlisted agent-config exclusions.
@@ -16,6 +17,11 @@ export async function runFixCommand(options) {
         console.error(`Error: not a directory: ${target}`);
         return EXIT_CODES.USAGE_ERROR;
     }
+    const broad = classifyBroadUserScanRoot(target);
+    if (broad.blocked) {
+        console.error(`Error: ${broad.reason}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
     const dryRun = options.dryRun === true;
     const yes = options.yes === true;
     try {

package/dist/cli/commands/learn.js

@@ -2,9 +2,14 @@ import { MockModelProvider, createModelProvider, loadAiConfig } from "../../ai/i
 import { StudentService } from "../../agent/student.js";
 import { parseAgentMode, defaultStudentMode } from "../../agent/modes.js";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 export async function runLearnCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     const mode = parseAgentMode(options.mode) ?? defaultStudentMode();
     const provider = options.useMock ? new MockModelProvider() : createModelProvider(loadAiConfig());
     const resolvedMode = options.build

package/dist/cli/commands/mcp.js

@@ -1,13 +1,17 @@
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { runAgentDoctorMcpStdio } from "../../mcp/agentdoctor/server.js";
 /**
  * Start combined AgentDoctor MCP (Brain tools + intelligence tools) over STDIO.
  */
 export async function runMcpCommand(options) {
-    const root = resolveRepoRoot(options.root);
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
     await runAgentDoctorMcpStdio({
-        root,
+        root: gated.root,
         buildIfMissing: options.buildIfMissing !== false,
     });
     return EXIT_CODES.SUCCESS;

package/dist/cli/commands/platform.js

@@ -1,13 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { EXIT_CODES } from "../../types/index.js";
-import { resolveRepoRoot } from "../../utils/path.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 import { analyzeRenameImpact, analyzeTestImpact, appendSessionEvent, buildProvenance, compareCommits, createSession, endSession, evaluateAgentAction, exportSessionMarkdown, formatTestImpactHuman, listSessions, loadSession, persistTestImpactReport, planContext, runPlatformScan, saveProvenance, EVALUATE_ONLY, } from "../../platform/index.js";
 import { buildRepositoryGraph } from "../../platform/graph/build.js";
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 export async function runPlatformCommand(options) {
-    const root = resolveRepoRoot(options.root ?? process.cwd());
+    const gated = await resolveCliProjectRoot(options.root ?? process.cwd());
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
     try {
         switch (options.action) {
             case "scan": {

package/dist/cli/commands/policy-graph-run.js

@@ -3,6 +3,7 @@ import { runControlledCommand } from "../../enforcement/runner.js";
 import { graphBuild, graphRebuild, graphStatus, graphUpdate, } from "../../intelligence/graph/incremental.js";
 import { buildIntelligenceGraph } from "../../intelligence/graph/build.js";
 import { EXIT_CODES } from "../../types/index.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
 function emit(json, value, human) {
     if (json) {
         process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
@@ -13,6 +14,12 @@ function emit(json, value, human) {
 }
 export async function runGraphSurfaceCommand(options) {
     try {
+        const gated = await resolveCliProjectRoot(options.root);
+        if (!gated.ok) {
+            console.error(`Error: ${gated.message}`);
+            return gated.code;
+        }
+        options = { ...options, root: gated.root };
         const mode = options.mode ?? "auto";
         if (options.action === "status") {
             const status = await graphStatus({ root: options.root });

package/dist/cli/commands/product.d.ts

@@ -0,0 +1,19 @@
+import { type ExitCode } from "../../types/index.js";
+import { type AgentRole } from "../../agent/roles.js";
+export type ProductCommandAction = "requirements" | "api" | "database" | "events" | "dependency" | "health-code" | "map" | "what-if" | "decisions" | "forensic" | "twin" | "eval-lab" | "self-check" | "infra" | "incident" | "security-doctor" | "privacy-doctor" | "search" | "tech-debt" | "features" | "evolution" | "memory" | "org" | "role-agent" | "test-brain";
+export declare function runProductCommand(options: {
+    action: ProductCommandAction;
+    root?: string;
+    json?: boolean;
+    target?: string;
+    changedFiles?: string[];
+    query?: string;
+    role?: AgentRole;
+    goal?: string;
+    approve?: boolean;
+    apply?: boolean;
+}): Promise<ExitCode>;
+export declare function runChangeLedgerListCommand(options: {
+    root?: string;
+    json?: boolean;
+}): Promise<ExitCode>;

package/dist/cli/commands/product.js

@@ -0,0 +1,157 @@
+import { EXIT_CODES } from "../../types/index.js";
+import { resolveCliProjectRoot } from "../safe-root.js";
+import { resolveTargetArgument } from "./scan.js";
+import { traceRequirements, analyzeApiSurface, analyzeDatabaseSchema, analyzeEvents, analyzeDependencies, analyzeCodeHealth, buildSoftwareMap, analyzeWhatIf, loadDecisionLedger, runForensicAnalysis, buildSoftwareDigitalTwin, runEvalLab, diagnoseAgentDoctorSelf, analyzeInfra, buildIncidentHypotheses, readChangeLedger, analyzeSecuritySurface, analyzePrivacySurface, searchSymbolsAndConcepts, buildTechnicalDebtRoadmap, analyzeFeatureIntelligence, buildSoftwareEvolutionTimeline, queryMemory, loadOrganizationModel, analyzeTestBrain, } from "../../product/index.js";
+import { runRoleAgent } from "../../agent/roles.js";
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export async function runProductCommand(options) {
+    const gated = await resolveCliProjectRoot(options.root ?? resolveTargetArgument(undefined));
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
+    try {
+        let payload;
+        switch (options.action) {
+            case "requirements":
+                payload = await traceRequirements(root);
+                break;
+            case "api":
+                payload = await analyzeApiSurface(root);
+                break;
+            case "database":
+                payload = await analyzeDatabaseSchema(root);
+                break;
+            case "events":
+                payload = await analyzeEvents(root);
+                break;
+            case "dependency":
+                payload = await analyzeDependencies(root);
+                break;
+            case "health-code":
+                payload = await analyzeCodeHealth(root);
+                break;
+            case "map":
+                payload = await buildSoftwareMap(root);
+                break;
+            case "what-if":
+                if (!options.target) {
+                    console.error("Error: what-if requires a file path or symbol target (--target or argument)");
+                    return EXIT_CODES.USAGE_ERROR;
+                }
+                payload = await analyzeWhatIf(root, options.target);
+                break;
+            case "decisions":
+                payload = await loadDecisionLedger(root);
+                break;
+            case "forensic":
+                payload = await runForensicAnalysis(root);
+                break;
+            case "twin":
+                payload = await buildSoftwareDigitalTwin(root);
+                break;
+            case "eval-lab":
+                payload = await runEvalLab(root);
+                break;
+            case "self-check":
+                payload = await diagnoseAgentDoctorSelf(root);
+                break;
+            case "infra":
+                payload = await analyzeInfra(root);
+                break;
+            case "incident":
+                payload = await buildIncidentHypotheses(root, options.changedFiles ? { changedFiles: options.changedFiles } : undefined);
+                break;
+            case "security-doctor":
+                payload = await analyzeSecuritySurface(root);
+                break;
+            case "privacy-doctor":
+                payload = await analyzePrivacySurface(root);
+                break;
+            case "search":
+                if (!options.query?.trim()) {
+                    console.error("Error: search requires a query (--query or argument)");
+                    return EXIT_CODES.USAGE_ERROR;
+                }
+                payload = await searchSymbolsAndConcepts(root, options.query);
+                break;
+            case "tech-debt":
+                payload = await buildTechnicalDebtRoadmap(root);
+                break;
+            case "features":
+                payload = await analyzeFeatureIntelligence(root);
+                break;
+            case "evolution":
+                payload = await buildSoftwareEvolutionTimeline(root);
+                break;
+            case "memory":
+                if (!options.query?.trim()) {
+                    console.error("Error: memory requires a query (--query or argument)");
+                    return EXIT_CODES.USAGE_ERROR;
+                }
+                payload = await queryMemory(root, options.query);
+                break;
+            case "org":
+                payload = await loadOrganizationModel(root);
+                break;
+            case "test-brain":
+                payload = await analyzeTestBrain({ root });
+                break;
+            case "role-agent":
+                if (!options.role || !options.goal?.trim()) {
+                    console.error("Error: role-agent requires --role and --goal");
+                    return EXIT_CODES.USAGE_ERROR;
+                }
+                if (options.apply && !options.approve) {
+                    console.error("Error: role-agent --apply requires --approve");
+                    return EXIT_CODES.USAGE_ERROR;
+                }
+                payload = await runRoleAgent({
+                    role: options.role,
+                    goal: options.goal,
+                    root,
+                    approvedByHuman: options.approve === true,
+                });
+                break;
+            default:
+                return EXIT_CODES.USAGE_ERROR;
+        }
+        if (options.json) {
+            printJson(payload);
+        }
+        else {
+            const action = options.action;
+            process.stdout.write(`AgentDoctor ${action} completed for ${root}\n`);
+            if (action === "self-check" && payload && typeof payload === "object" && "ok" in payload) {
+                process.stdout.write(`  ok: ${payload.ok}\n`);
+            }
+            if (action === "eval-lab" && payload && typeof payload === "object" && "passed" in payload) {
+                process.stdout.write(`  passed: ${payload.passed}\n`);
+            }
+            process.stdout.write("  (use --json for full report)\n");
+        }
+        return EXIT_CODES.SUCCESS;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        return EXIT_CODES.INTERNAL_ERROR;
+    }
+}
+export async function runChangeLedgerListCommand(options) {
+    const gated = await resolveCliProjectRoot(options.root);
+    if (!gated.ok) {
+        console.error(`Error: ${gated.message}`);
+        return gated.code;
+    }
+    const root = gated.root;
+    const payload = await readChangeLedger(root);
+    if (options.json)
+        printJson(payload);
+    else
+        process.stdout.write(`Change ledger entries: ${payload.entries.length}\n`);
+    return EXIT_CODES.SUCCESS;
+}

package/dist/cli/commands/scan.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { evaluateScanPolicy } from "../../core/policy/evaluate.js";
 import { scan } from "../../core/scanner/scan.js";
+import { classifyBroadUserScanRoot } from "../../product/discovery/roots.js";
 import { emitGithubReports } from "../../reporters/github/emit.js";
 import { renderJsonReport } from "../../reporters/json/report.js";
 import { renderTerminalReport } from "../../reporters/terminal/report.js";
@@ -13,6 +14,11 @@ export async function runScanCommand(options) {
         console.error(`Error: not a directory: ${target}`);
         return EXIT_CODES.USAGE_ERROR;
     }
+    const broad = classifyBroadUserScanRoot(target);
+    if (broad.blocked) {
+        console.error(`Error: ${broad.reason}`);
+        return EXIT_CODES.USAGE_ERROR;
+    }
     try {
         const result = await scan({
             cwd: target,

package/dist/cli/commands/start.d.ts

@@ -0,0 +1,15 @@
+import { type ExitCode } from "../../types/index.js";
+export declare function runStartCommand(options: {
+    root?: string;
+    json?: boolean;
+    select?: string;
+    maxEntries?: number;
+    initBrain?: boolean;
+    rebuildBrain?: boolean;
+    listOnly?: boolean;
+}): Promise<ExitCode>;
+export declare function runDnaCommand(options: {
+    root?: string;
+    json?: boolean;
+    persist?: boolean;
+}): Promise<ExitCode>;