@praneeth_54/agentdoctor 2.0.0 → 2.1.0

package/dist/cli/program.js

@@ -13,10 +13,19 @@ import { runBaselineCommand, runChangesCommand, runContextHealthCommand, runDash
 import { runPlatformCommand } from "./commands/platform.js";
 import { runInitCommand, runV2SurfaceCommand } from "./commands/complete.js";
 import { runMcpCommand } from "./commands/mcp.js";
+import { runChangeAnalyzeCommand, runChangeDiffCommand, runChangeExplainCommand, runChangeStatusCommand, runChangeVerifyCommand, runEvidenceInspectCommand, runEvidenceVerifyCommand, runProofBuildCommand, runProofExplainCommand, runProofExportCommand, runProofInspectCommand, runProofVerifyCommand, } from "./commands/assurance.js";
+import { runGraphSurfaceCommand, runPolicyCheckCommand, runPolicyEnforceCommand, runPolicyExplainCommand, runRunCommand, runRunExplainCommand, } from "./commands/policy-graph-run.js";
+import { runArchitectureCommand } from "./commands/architecture.js";
+import { runWorkspaceCommand } from "./commands/workspace.js";
+import { runAskCommand, runChatCommand } from "./commands/chat.js";
+import { runAgentCommand, runPlanCommand } from "./commands/agent.js";
+import { runLearnCommand } from "./commands/learn.js";
 import { collectOpsHealth } from "../ops/health.js";
 import { listSessions, loadSession } from "../platform/sessions/store.js";
 import { exportReports } from "../platform/reports/export.js";
 import { runPlatformScan } from "../platform/index.js";
+import { analyzeTestImpact, formatTestImpactHuman, persistTestImpactReport, } from "../platform/test-impact/analyze.js";
+import { resolveRepoRoot } from "../utils/path.js";
 function parseMinScore(value) {
     const parsed = Number(value);
     if (!Number.isFinite(parsed) || parsed < 0 || parsed > 100) {
@@ -89,7 +98,7 @@ export function createProgram() {
     const program = new Command();
     addScanOptions(program
         .name("agentdoctor")
-        .description("Audit AI coding agent configuration in a repository (local, deterministic, no API key).")
+        .description("Engineering intelligence and safety for AI coding agents — scan, knowledge, MCP, and verification (local, deterministic; no API key required for core flows).")
         .version(PACKAGE_VERSION, "-V, --version", "Print AgentDoctor version")
         .argument("[path]", "Repository path to scan (default: current directory)")).action(async (pathArg, _options, command) => {
         await runScanFromCli(pathArg, command);
@@ -317,21 +326,76 @@ export function createProgram() {
             ...(options.domain ? { domain: options.domain } : {}),
         });
     });
-    program
+    const graph = program
         .command("graph")
-        .description("Build intelligence graph (TypeScript AST when available; regex fallback)")
+        .description("Build / update intelligence graph (TypeScript AST when available; regex fallback). Bare `graph` aliases build.")
         .argument("[path]", "Repository path")
         .option("--mode <mode>", "auto|regex|typescript-ast", "auto")
         .option("--json", "Emit JSON", false)
         .action(async (pathArg, _options, command) => {
         const options = command.optsWithGlobals();
-        process.exitCode = await runV2SurfaceCommand({
-            action: "graph-ast",
+        // Backward compat: `agentdoctor graph --json` → build + persist
+        process.exitCode = await runGraphSurfaceCommand({
+            action: "build",
+            root: resolveTargetArgument(pathArg),
+            mode: options.mode ?? "auto",
+            json: Boolean(options.json),
+        });
+    });
+    graph
+        .command("build")
+        .description("Build graph and persist .agentdoctor/graph/index.json")
+        .argument("[path]", "Repository path")
+        .option("--mode <mode>", "auto|regex|typescript-ast", "auto")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runGraphSurfaceCommand({
+            action: "build",
+            root: resolveTargetArgument(pathArg),
+            mode: options.mode ?? "auto",
+            json: Boolean(options.json),
+        });
+    });
+    graph
+        .command("update")
+        .description("Incrementally update graph from git/hash changes (rebuilds on corruption)")
+        .argument("[path]", "Repository path")
+        .option("--mode <mode>", "auto|regex|typescript-ast", "auto")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runGraphSurfaceCommand({
+            action: "update",
+            root: resolveTargetArgument(pathArg),
+            mode: options.mode ?? "auto",
+            json: Boolean(options.json),
+        });
+    });
+    graph
+        .command("rebuild")
+        .description("Force full graph rebuild")
+        .argument("[path]", "Repository path")
+        .option("--mode <mode>", "auto|regex|typescript-ast", "auto")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runGraphSurfaceCommand({
+            action: "rebuild",
             root: resolveTargetArgument(pathArg),
             mode: options.mode ?? "auto",
             json: Boolean(options.json),
         });
     });
+    graph
+        .command("status")
+        .description("Show persisted graph index status")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runGraphSurfaceCommand({
+            action: "status",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
     program
         .command("health")
         .description("Git hotspot / engineering intelligence report")
@@ -347,29 +411,63 @@ export function createProgram() {
     });
     program
         .command("impact")
-        .description("Change/test impact analysis")
+        .description("Change/test impact analysis (heuristic by default; coverage-backed with --coverage)")
         .argument("[path]", "Repository path")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--since <ref>", "Diff since git ref")
         .option("--json", "Emit JSON", false)
         .action(async (pathArg, _options, command) => {
         const options = command.optsWithGlobals();
-        process.exitCode = await runV2SurfaceCommand({
-            action: "impact",
-            root: resolveTargetArgument(pathArg),
-            json: Boolean(options.json),
-        });
+        const root = resolveTargetArgument(pathArg);
+        try {
+            const impact = await analyzeTestImpact({
+                root,
+                ...(options.coverage ? { coveragePath: options.coverage } : {}),
+                ...(options.since ? { since: options.since } : {}),
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(impact, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(formatTestImpactHuman(impact));
+            }
+            process.exitCode = EXIT_CODES.SUCCESS;
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = EXIT_CODES.INTERNAL_ERROR;
+        }
     });
     program
         .command("test-impact")
         .description("Test-impact analysis (alias of impact)")
         .argument("[path]", "Repository path")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--since <ref>", "Diff since git ref")
         .option("--json", "Emit JSON", false)
         .action(async (pathArg, _options, command) => {
         const options = command.optsWithGlobals();
-        process.exitCode = await runV2SurfaceCommand({
-            action: "impact",
-            root: resolveTargetArgument(pathArg),
-            json: Boolean(options.json),
-        });
+        const root = resolveTargetArgument(pathArg);
+        try {
+            const impact = await analyzeTestImpact({
+                root,
+                ...(options.coverage ? { coveragePath: options.coverage } : {}),
+                ...(options.since ? { since: options.since } : {}),
+            });
+            const out = await persistTestImpactReport(resolveRepoRoot(root), impact);
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({ ...impact, reportPath: out }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(formatTestImpactHuman(impact));
+                process.stdout.write(`  wrote: ${out}\n`);
+            }
+            process.exitCode = EXIT_CODES.SUCCESS;
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = EXIT_CODES.INTERNAL_ERROR;
+        }
     });
     program
         .command("refactor-impact")
@@ -458,6 +556,57 @@ export function createProgram() {
             json: Boolean(options.json),
         });
     });
+    const architecture = program
+        .command("architecture")
+        .description("Architecture contract + C4 views (rules are advisory until you treat check as a gate)");
+    architecture
+        .command("init")
+        .description("Write default .agentdoctor/architecture.json if missing")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runArchitectureCommand({
+            action: "init",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
+    architecture
+        .command("analyze")
+        .description("C4 views + architecture contract summary")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runArchitectureCommand({
+            action: "analyze",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
+    architecture
+        .command("check")
+        .description("Check import edges against .agentdoctor/architecture.json|.yml")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runArchitectureCommand({
+            action: "check",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
+    architecture
+        .command("explain")
+        .description("Explain architecture layers, forbidden/allowed rules, and recent violations")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runArchitectureCommand({
+            action: "explain",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
     program
         .command("knowledge")
         .description("List governed knowledge records")
@@ -554,6 +703,374 @@ export function createProgram() {
             json: Boolean(options.json),
         });
     });
+    const change = program
+        .command("change")
+        .description("Change assurance — structured assessment and evidence (never claims verified without evidence)");
+    change
+        .command("analyze")
+        .description("Assemble a ChangeAssessment from git, graph, policy, knowledge, and test signals")
+        .argument("[path]", "Repository path")
+        .option("--since <ref>", "Diff since git ref (e.g. main)")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runChangeAnalyzeCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.since ? { since: options.since } : {}),
+            ...(options.coverage ? { coverage: options.coverage } : {}),
+            json: Boolean(options.json),
+        });
+    });
+    change
+        .command("verify")
+        .description("Produce a durable evidence bundle under .agentdoctor/evidence/<id>/ (status: evidence-produced)")
+        .argument("[path]", "Repository path")
+        .option("--since <ref>", "Diff since git ref (e.g. main)")
+        .option("--change-id <id>", "Reuse a change id")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runChangeVerifyCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.since ? { since: options.since } : {}),
+            ...(options.changeId ? { changeId: options.changeId } : {}),
+            ...(options.coverage ? { coverage: options.coverage } : {}),
+            json: Boolean(options.json),
+        });
+    });
+    change
+        .command("explain")
+        .description("Human explanation of a change assessment (does not claim correctness)")
+        .argument("[path]", "Repository path")
+        .option("--since <ref>", "Diff since git ref")
+        .option("--change-id <id>", "Change id")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runChangeExplainCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.since ? { since: options.since } : {}),
+            ...(options.changeId ? { changeId: options.changeId } : {}),
+            ...(options.coverage ? { coverage: options.coverage } : {}),
+            json: Boolean(options.json),
+        });
+    });
+    change
+        .command("diff")
+        .description("Summarize base/target file diffs from git")
+        .argument("[path]", "Repository path")
+        .option("--since <ref>", "Diff since git ref")
+        .option("--change-id <id>", "Change id (label only)")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runChangeDiffCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.since ? { since: options.since } : {}),
+            ...(options.changeId ? { changeId: options.changeId } : {}),
+            json: Boolean(options.json),
+        });
+    });
+    change
+        .command("status")
+        .description("Verification / evidence status for latest or --change-id")
+        .argument("[path]", "Repository path")
+        .option("--change-id <id>", "Change id")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runChangeStatusCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.changeId ? { changeId: options.changeId } : {}),
+            json: Boolean(options.json),
+        });
+    });
+    const evidence = program
+        .command("evidence")
+        .description("Inspect and hash-verify change evidence bundles");
+    evidence
+        .command("inspect")
+        .description("List evidence artifacts for a change id")
+        .argument("<changeId>", "Change id (chg_…)")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (changeId, pathArg, options) => {
+        process.exitCode = await runEvidenceInspectCommand({
+            root: resolveTargetArgument(pathArg),
+            changeId,
+            json: Boolean(options.json),
+        });
+    });
+    evidence
+        .command("verify")
+        .description("Hash-check evidence bundle; status verified only when all hashes match")
+        .argument("<changeId>", "Change id (chg_…)")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (changeId, pathArg, options) => {
+        process.exitCode = await runEvidenceVerifyCommand({
+            root: resolveTargetArgument(pathArg),
+            changeId,
+            json: Boolean(options.json),
+        });
+    });
+    const proof = program
+        .command("proof")
+        .description("ChangeProof — hash integrity over evidence (never claims engineering correctness)");
+    proof
+        .command("build")
+        .description("Build a ChangeProof from an evidence bundle")
+        .argument("<changeId>", "Change id (chg_…)")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (changeId, pathArg, options) => {
+        process.exitCode = await runProofBuildCommand({
+            root: resolveTargetArgument(pathArg),
+            changeId,
+            json: Boolean(options.json),
+        });
+    });
+    proof
+        .command("inspect")
+        .description("Inspect a proof by proofId or changeId")
+        .argument("<id>", "proofId or changeId")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (id, pathArg, options) => {
+        process.exitCode = await runProofInspectCommand({
+            root: resolveTargetArgument(pathArg),
+            id,
+            json: Boolean(options.json),
+        });
+    });
+    proof
+        .command("explain")
+        .description("Human explanation of a ChangeProof (does not claim correctness)")
+        .argument("<id>", "proofId or changeId")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (id, pathArg, options) => {
+        process.exitCode = await runProofExplainCommand({
+            root: resolveTargetArgument(pathArg),
+            id,
+            json: Boolean(options.json),
+        });
+    });
+    proof
+        .command("verify")
+        .description("Re-hash evidence and compare to proof (integrity only)")
+        .argument("<id>", "proofId or changeId")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (id, pathArg, options) => {
+        process.exitCode = await runProofVerifyCommand({
+            root: resolveTargetArgument(pathArg),
+            id,
+            json: Boolean(options.json),
+        });
+    });
+    proof
+        .command("export")
+        .description("Export a proof JSON file")
+        .argument("<id>", "proofId or changeId")
+        .requiredOption("--out <file>", "Output file path")
+        .argument("[path]", "Repository path")
+        .option("--json", "Emit JSON", false)
+        .action(async (id, pathArg, options) => {
+        process.exitCode = await runProofExportCommand({
+            root: resolveTargetArgument(pathArg),
+            id,
+            out: options.out,
+            json: Boolean(options.json),
+        });
+    });
+    const policy = program
+        .command("policy")
+        .description("Action policy check / explain / enforce (controlled runner)");
+    policy
+        .command("check")
+        .description("Evaluate a command against local policy (evaluate-only)")
+        .requiredOption("--command <cmd>", "Command string")
+        .argument("[path]", "Repository path")
+        .option("--fail-closed", "Deny on invalid local policy", false)
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runPolicyCheckCommand({
+            root: resolveTargetArgument(pathArg),
+            command: options.command,
+            failClosed: Boolean(options.failClosed),
+            json: Boolean(options.json),
+        });
+    });
+    policy
+        .command("explain")
+        .description("Explain why a command receives its policy decision")
+        .requiredOption("--command <cmd>", "Command string")
+        .argument("[path]", "Repository path")
+        .option("--fail-closed", "Deny on invalid local policy", false)
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runPolicyExplainCommand({
+            root: resolveTargetArgument(pathArg),
+            command: options.command,
+            failClosed: Boolean(options.failClosed),
+            json: Boolean(options.json),
+        });
+    });
+    policy
+        .command("enforce")
+        .description("Evaluate policy; optionally execute when --execute and decision=allow")
+        .requiredOption("--command <cmd>", "Command string")
+        .option("--execute", "Execute via controlled runner when allowed", false)
+        .argument("[path]", "Repository path")
+        .option("--fail-closed", "Deny on invalid local policy", false)
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runPolicyEnforceCommand({
+            root: resolveTargetArgument(pathArg),
+            command: options.command,
+            execute: Boolean(options.execute),
+            failClosed: Boolean(options.failClosed),
+            json: Boolean(options.json),
+        });
+    });
+    const runCmd = program
+        .command("run")
+        .description("Controlled execution (shell=false by default). Prefer: agentdoctor run -- <cmd> <args...>");
+    runCmd
+        .command("explain")
+        .description("Explain controlled-runner decision for a command (evaluate-only, never executes)")
+        .requiredOption("--command <cmd>", "Command string")
+        .argument("[path]", "Repository path")
+        .option("--shell", "Explain as if shell=true were requested", false)
+        .option("--fail-closed", "Deny on invalid local policy", false)
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runRunExplainCommand({
+            root: resolveTargetArgument(pathArg),
+            command: options.command,
+            shell: Boolean(options.shell),
+            failClosed: Boolean(options.failClosed),
+            json: Boolean(options.json),
+        });
+    });
+    runCmd
+        .option("--shell", "HIGH RISK: allow shell interpretation (still requires policy allow)", false)
+        .option("--timeout <ms>", "Kill after timeout milliseconds", "30000")
+        .option("--fail-closed", "Deny on invalid local policy", false)
+        .option("--json", "Emit JSON", false)
+        .argument("[path]", "Repository path (ignored when -- separates args; use cwd)")
+        .argument("[command...]", "Command argv after --")
+        .allowUnknownOption(false)
+        .action(async (pathArg, commandParts, cmd) => {
+        const options = cmd.opts();
+        // Commander may put path as first arg when no `--`; prefer argv after `--` via raw args.
+        const raw = cmd.args;
+        let root = process.cwd();
+        let argv = [];
+        // If first token looks like a path-only invocation without command, treat as root.
+        if (commandParts && commandParts.length > 0) {
+            argv = commandParts;
+            if (pathArg)
+                root = resolveTargetArgument(pathArg);
+        }
+        else if (pathArg && !pathArg.startsWith("-")) {
+            // `run npm --version` style: pathArg is actually first command token
+            argv = [pathArg, ...(raw.slice(1) ?? [])];
+        }
+        // Prefer explicit `--` remainder from process.argv
+        const dd = process.argv.indexOf("--");
+        if (dd >= 0) {
+            argv = process.argv.slice(dd + 1);
+            root = process.cwd();
+        }
+        const timeoutMs = Number(options.timeout ?? 30000);
+        process.exitCode = await runRunCommand({
+            root: resolveTargetArgument(root),
+            argv,
+            shell: Boolean(options.shell),
+            timeoutMs: Number.isFinite(timeoutMs) ? timeoutMs : 30000,
+            failClosed: Boolean(options.failClosed),
+            json: Boolean(options.json),
+        });
+    });
+    const workspace = program
+        .command("workspace")
+        .description("Multi-repo workspace model under .agentdoctor/workspaces/ (local isolation)");
+    workspace
+        .command("init")
+        .description("Create a workspace JSON record")
+        .requiredOption("--name <name>", "Workspace display name")
+        .option("--id <id>", "Optional workspace id")
+        .option("--repo <path>", "Initial repository root to add")
+        .option("--allow-cross-read", "Allow reading other member repos (default false)", false)
+        .argument("[path]", "Control root (stores .agentdoctor/workspaces)")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runWorkspaceCommand({
+            action: "init",
+            root: resolveTargetArgument(pathArg),
+            name: options.name,
+            ...(options.id ? { id: options.id } : {}),
+            ...(options.repo ? { repositoryRoot: resolveTargetArgument(options.repo) } : {}),
+            allowCrossRead: Boolean(options.allowCrossRead),
+            json: Boolean(options.json),
+        });
+    });
+    workspace
+        .command("add")
+        .description("Add a repository root to a workspace")
+        .requiredOption("--id <id>", "Workspace id")
+        .requiredOption("--repo <path>", "Repository root to add")
+        .argument("[path]", "Control root")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runWorkspaceCommand({
+            action: "add",
+            root: resolveTargetArgument(pathArg),
+            id: options.id,
+            repositoryRoot: resolveTargetArgument(options.repo),
+            json: Boolean(options.json),
+        });
+    });
+    workspace
+        .command("list")
+        .description("List workspaces")
+        .argument("[path]", "Control root")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runWorkspaceCommand({
+            action: "list",
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
+    workspace
+        .command("status")
+        .description("Show workspace membership and missing roots")
+        .requiredOption("--id <id>", "Workspace id")
+        .argument("[path]", "Control root")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runWorkspaceCommand({
+            action: "status",
+            root: resolveTargetArgument(pathArg),
+            id: options.id,
+            json: Boolean(options.json),
+        });
+    });
+    workspace
+        .command("remove")
+        .description("Delete a workspace record")
+        .requiredOption("--id <id>", "Workspace id")
+        .argument("[path]", "Control root")
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runWorkspaceCommand({
+            action: "remove",
+            root: resolveTargetArgument(pathArg),
+            id: options.id,
+            json: Boolean(options.json),
+        });
+    });
     program
         .command("changes")
         .description("Analyze git working-tree / range changes")
@@ -721,6 +1238,95 @@ export function createProgram() {
             json: Boolean(options.json),
         });
     });
+    program
+        .command("chat")
+        .description("Project Chat (2.1): evidence-backed conversation about this repository (requires AI provider)")
+        .argument("[path]", "Repository path (default: current directory)")
+        .action(async (pathArg) => {
+        process.exitCode = await runChatCommand({
+            root: resolveTargetArgument(pathArg),
+        });
+    });
+    program
+        .command("ask")
+        .description("One-shot Project Chat question (same engine as chat)")
+        .argument("<question>", "Question about the project")
+        .argument("[path]", "Repository path (default: current directory)")
+        .option("--json", "Emit JSON response", false)
+        .action(async (question, pathArg, options) => {
+        process.exitCode = await runAskCommand({
+            question,
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+        });
+    });
+    program
+        .command("plan")
+        .description("Project Agent plan (2.1 M3): understand goal, list likely files, request approval — no file edits")
+        .argument("<goal>", "What you want to build or change")
+        .argument("[path]", "Repository path (default: current directory)")
+        .option("--json", "Emit JSON plan", false)
+        .option("--approve", "Record human approval (still no writes in M3)", false)
+        .action(async (goal, pathArg, options) => {
+        process.exitCode = await runPlanCommand({
+            goal,
+            root: resolveTargetArgument(pathArg),
+            json: Boolean(options.json),
+            approve: Boolean(options.approve),
+        });
+    });
+    program
+        .command("agent")
+        .description("Project Agent (2.1): list tools, run tools, plan, or apply approved file/command changes")
+        .argument("[path]", "Repository path (default: current directory)")
+        .option("--list-tools", "List available agent tools", false)
+        .option("--tool <name>", "Run a single tool by name")
+        .option("--goal <text>", "Build a change plan for this goal")
+        .option("--approve", "Record explicit human approval", false)
+        .option("--apply", "Apply approved changes (requires --approve)", false)
+        .option("--apply-ops <json>", "JSON array of {name, arguments} tool ops for --apply")
+        .option("--skip-verify", "Skip post-change verification after apply", false)
+        .option("--run-tests", "Run controlled tests during verification", false)
+        .option("--json", "Emit JSON", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runAgentCommand({
+            root: resolveTargetArgument(pathArg),
+            listTools: Boolean(options.listTools),
+            ...(options.tool !== undefined ? { tool: options.tool } : {}),
+            ...(options.goal !== undefined ? { goal: options.goal } : {}),
+            approve: Boolean(options.approve),
+            apply: Boolean(options.apply),
+            ...(options.applyOps !== undefined ? { applyOpsJson: options.applyOps } : {}),
+            verify: !options.skipVerify,
+            runTests: Boolean(options.runTests),
+            json: Boolean(options.json),
+        });
+    });
+    program
+        .command("learn")
+        .description("Student Learn mode (2.1 M6): explain project, viva questions, grounded documentation")
+        .argument("[path]", "Repository path (default: current directory)")
+        .option("--mode <mode>", "LEARN | BUILD_WITH_ME | BUILD_FOR_ME | DEVELOPER", "LEARN")
+        .option("--viva", "Generate viva questions from detected stack", false)
+        .option("--docs", "Generate project documentation sections", false)
+        .option("--build <goal>", "BUILD_WITH_ME / BUILD_FOR_ME: explain, plan, then coding loop")
+        .option("--approve", "Human approval required before BUILD writes", false)
+        .option("--apply-ops <json>", "Deterministic tool ops JSON array for --build --approve")
+        .option("--json", "Emit JSON", false)
+        .option("--mock", "Use MockModelProvider", false)
+        .action(async (pathArg, options) => {
+        process.exitCode = await runLearnCommand({
+            root: resolveTargetArgument(pathArg),
+            ...(options.mode !== undefined ? { mode: options.mode } : {}),
+            viva: Boolean(options.viva),
+            docs: Boolean(options.docs),
+            ...(options.build !== undefined ? { build: options.build } : {}),
+            approve: Boolean(options.approve),
+            ...(options.applyOps !== undefined ? { applyOpsJson: options.applyOps } : {}),
+            json: Boolean(options.json),
+            useMock: Boolean(options.mock),
+        });
+    });
     const platform = program
         .command("platform")
         .description("AgentDoctor 2.0 local platform (intelligence, Action Policy Evaluator, sessions, reports)");
@@ -752,8 +1358,10 @@ export function createProgram() {
     });
     platform
         .command("test-impact")
-        .description("Analyze which tests likely relate to git changes (heuristic; does not run tests)")
+        .description("Analyze which tests relate to git changes (heuristic; coverage-backed with --coverage; does not run tests)")
         .argument("[path]", "Repository path")
+        .option("--coverage <path>", "LCOV / Istanbul JSON / Cobertura XML coverage file")
+        .option("--since <ref>", "Diff since git ref")
         .option("--json", "Emit JSON", false)
         .action(async (pathArg, _options, command) => {
         const options = command.optsWithGlobals();
@@ -761,6 +1369,8 @@ export function createProgram() {
             action: "test-impact",
             root: resolveTargetArgument(pathArg),
             json: Boolean(options.json),
+            ...(options.coverage ? { coverage: options.coverage } : {}),
+            ...(options.since ? { since: options.since } : {}),
         });
     });
     const registerPolicyCheck = (name, aliasNote) => {