@codapult/guard 0.1.0 → 0.3.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![CI](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/ci.yml)
 [![Fixtures](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml/badge.svg)](https://github.com/codapult/codapult-guard/actions/workflows/guard-fixtures.yml)
+[![npm](https://img.shields.io/npm/v/@codapult/guard?logo=npm)](https://www.npmjs.com/package/@codapult/guard)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js >=20.19](https://img.shields.io/badge/node-%3E%3D20.19-339933.svg?logo=node.js&logoColor=white)](package.json)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -11,8 +12,43 @@
 `@codapult/guard` is a local-first, model-agnostic architecture guard for JavaScript and
 TypeScript projects.
 
-It learns what already exists, records the project’s architectural memory, and protects future
-changes from introducing regressions.
+It learns what already exists, records the project’s architectural memory, and can protect future
+changes from introducing regressions covered by the project’s approved policy.
+
+### See the value in one change
+
+Suppose a SaaS project has an established boundary:
+
+```text
+Client → Server Action → Service → Repository → Database
+```
+
+An AI agent can still produce code that is valid TypeScript but crosses that boundary:
+
+```text
+Client → Database
+```
+
+After the project has explicitly approved a matching import rule or deterministic contract, Guard
+checks the changed files and reports matching violations deterministically:
+
+```text
+Codapult Guard (changed files)
+Scanned 1 source file(s); suppressed 12 baseline finding(s).
+
+src/app/settings/page.tsx:1 [client-no-persistence-import]
+  Client modules should not import persistence-layer modules.
+  import: @/lib/db/client
+
+✗ 1 issue(s) found
+Exit code: 1
+```
+
+The file path, rule ID, message, and counts depend on the project. This is the actual CLI output
+shape: Guard does not infer that every `Client → Database` edge is forbidden, and it does not
+activate proposals silently. The team approves the relevant policy first; then existing findings
+can be baselined while newly matching violations fail the gate and give the agent bounded evidence
+to repair.
 
 > **Guard does not tell every project to use the same architecture.**
 > It discovers the architecture that is already there, then lets the team decide what becomes policy.
@@ -132,6 +168,10 @@ Guard does not assume a fixed `UI → actions → services → repositories →
 It can discover that shape when the project exhibits it, but observed patterns become enforceable
 only after explicit approval.
 
+Policy paths are validated as project-relative paths. Guard rejects traversal, absolute paths, and
+symlinks escaping the project root; import-boundary checks include imports, re-exports, and literal
+dynamic imports.
+
 ## What Guard discovers
 
 The model is framework-aware without being framework-dependent:
@@ -150,6 +190,15 @@ The model is framework-aware without being framework-dependent:
 Capabilities are evidence, not requirements. A Vite app, Express service, Hono project, Node
 package, monorepo, or Next.js SaaS can all use the same Guard core.
 
+## What Guard is — and is not
+
+Guard is an architecture control plane for AI-assisted development. It protects project-specific
+boundaries and change impact using local facts, approved policy, and deterministic verification.
+
+Guard is not a replacement for ESLint, TypeScript, tests, SAST, or a general-purpose PR bot. Those
+tools answer different questions; Guard connects their results with the architectural memory that
+an AI coding agent needs before and after changing a repository.
+
 ## The normal loop
 
 ```text
@@ -164,6 +213,12 @@ init once → edit → check --changed → review → verify → commit / merge
    contract validation.
 5. `audit` inspects the complete current state, including findings accepted by the baseline.
 
+For a focused change explanation, use `codapult-guard impact <file...>` or the equivalent
+`codapult_guard_impact` MCP tool. It reports both directions of the dependency graph: what the
+changed module uses and which transitive callers may be affected. `review` includes the same
+impact packet plus typed Git changes (`added`, `modified`, `deleted`, and `renamed`) for the AI
+host.
+
 Guard state is stored in `.codapult/guard/`:
 
 ```text
@@ -194,10 +249,30 @@ Start the standalone MCP server over stdio:
 pnpm exec codapult-guard mcp-server
 ```
 
+Register that command in the MCP client from the project root. For example, Cursor can use
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "codapult-guard": {
+      "command": "pnpm",
+      "args": ["exec", "codapult-guard", "mcp-server"],
+      "cwd": "."
+    }
+  }
+}
+```
+
+For clients that accept a generic stdio server, use the same command and set its working
+directory to the project root. Guard reads local files only; no API key or model provider is
+required. Host-specific examples are in [`docs/integrations/`](docs/integrations/).
+
 Recommended agent loop:
 
 ```text
 task finished
+  → codapult_guard_next_action
   → codapult_guard_context
   → codapult_guard_review(requirement, diff)
   → codapult_guard_verify
@@ -225,19 +300,24 @@ real project shapes.
 
 ## CLI surface
 
-| Command                    | Purpose                                                         |
-| -------------------------- | --------------------------------------------------------------- |
-| `init`                     | Create project memory and the initial baseline.                 |
-| `analyze`                  | Refresh facts without changing policy or baseline.              |
-| `propose`                  | Generate evidence-based rule and contract proposals.            |
-| `check --changed`          | Enforce active policy on changed and untracked files.           |
-| `audit`                    | Scan the complete current project, including baseline findings. |
-| `review`                   | Create a bounded semantic-review packet for an AI host.         |
-| `verify`                   | Run the configured completion gate.                             |
-| `doctor`                   | Diagnose invalid or missing Guard artifacts.                    |
-| `history` / `history-diff` | Inspect project model evolution.                                |
-| `rules` / `contracts`      | Approve or reject proposed policy.                              |
-| `baseline`                 | Review or intentionally accept existing findings.               |
+| Command                    | Purpose                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| `init`                     | Create project memory and the initial baseline.                                             |
+| `analyze`                  | Refresh facts without changing policy or baseline.                                          |
+| `propose`                  | Generate evidence-based rule and contract proposals.                                        |
+| `check --changed`          | Enforce active policy on changed and untracked files.                                       |
+| `audit`                    | Scan the complete current project, including baseline findings.                             |
+| `review`                   | Create a bounded semantic-review packet for an AI host.                                     |
+| `verify`                   | Run the configured completion gate.                                                         |
+| `doctor`                   | Diagnose invalid or missing Guard artifacts.                                                |
+| `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution.                       |
+| `impact <files...>`        | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. |
+| `policy explain <id>`      | Explain a policy item, its evidence, and approval history.                                  |
+| `rules` / `contracts`      | Approve or reject proposed policy.                                                          |
+| `baseline`                 | Review or intentionally accept existing findings.                                           |
+
+Use `analyze --refresh` after a structural change. `doctor --fix-cache` removes only the disposable
+discovery cache; it does not change rules, contracts, baseline, or source files.
 
 Run `pnpm exec codapult-guard <command> --help` for command-specific options.
 

package/dist/adapters/command.js

@@ -1,4 +1,4 @@
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 const MAX_OUTPUT_CHARS = 20_000;
 const MAX_BUFFER_BYTES = 2_000_000;
 function redactOutput(value) {
@@ -13,9 +13,30 @@ function captureOutput(value) {
         ? { value: `${redacted.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]`, truncated: true }
         : { value: redacted, truncated: false };
 }
+function parseCommand(command) {
+    const parts = command.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0 || parts.some((part) => /[;&|<>`$()]/.test(part)))
+        return undefined;
+    const [executable, ...args] = parts;
+    const windowsExecutable = process.platform === 'win32' && /^(?:npm|npx|pnpm|yarn|bun)$/.test(executable)
+        ? `${executable}.cmd`
+        : executable;
+    return { executable: windowsExecutable, args };
+}
 export function runProjectCommand(command, cwd, options = {}) {
+    const parsed = parseCommand(command);
+    if (!parsed) {
+        return {
+            command,
+            status: 'failed',
+            passed: false,
+            exitCode: 2,
+            stdout: '',
+            stderr: 'Unsafe or empty project command rejected.',
+        };
+    }
     try {
-        const stdout = execSync(command, {
+        const stdout = execFileSync(parsed.executable, parsed.args, {
             cwd,
             env: { ...process.env, ...options.env },
             stdio: 'pipe',

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

@@ -2,7 +2,9 @@ import { type GuardToolMode } from '../../core/guard.js';
 export declare function guardInitCommand(options?: {
     force?: boolean;
 }): void;
-export declare function guardAnalyzeCommand(): void;
+export declare function guardAnalyzeCommand(_options?: {
+    refresh?: boolean;
+}): void;
 export declare function guardProposeCommand(options?: {
     json?: boolean;
 }): void;
@@ -11,8 +13,12 @@ export declare function guardInstallAgentCommand(target?: string, options?: {
 }): void;
 export declare function guardDoctorCommand(options?: {
     json?: boolean;
+    fixCache?: boolean;
 }): void;
 export declare function guardHistoryCommand(): void;
+export declare function guardImpactCommand(files: string[], options?: {
+    json?: boolean;
+}): void;
 export declare function guardHistoryDiffCommand(from: string, to: string, options?: {
     json?: boolean;
 }): void;
@@ -41,6 +47,9 @@ export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove
 export declare function guardRulesApproveCommand(ids?: string, options?: {
     all?: boolean;
 }): void;
+export declare function guardPolicyExplainCommand(id: string, options?: {
+    json?: boolean;
+}): void;
 export declare function guardContractsApproveCommand(ids?: string, options?: {
     all?: boolean;
 }): void;

package/dist/cli/commands/guard.js

@@ -1,22 +1,46 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
-import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, writeGuardConfig, writeGuardProposals, recordGuardProposalDecision, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardContracts, writeProjectModel, writeGuardMemory, writeProjectSnapshot, } from '../../core/guard.js';
+import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, writeGuardConfig, writeGuardProposals, recordGuardProposalDecision, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardContracts, writeProjectModel, writeGuardMemory, writeProjectSnapshot, } from '../../core/guard.js';
+import { guardErrorPayload } from '../../core/errors.js';
 import { runGuardVerification, } from '../../core/verification/verify.js';
 import { diagnoseGuard } from '../../core/analysis/doctor.js';
 import { diffGuardSnapshots, listGuardSnapshots } from '../../core/history/history.js';
 import { guardAgentTargets, installGuardAgentInstructions, installGuardAgentTargets, } from '../../adapters/agents/agent-integration.js';
 import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
+import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
         printer(`${finding.file}:${finding.line} [${finding.ruleId}] ${finding.message}`);
         dim(`  import: ${finding.importPath}`);
+        if (finding.resolvedPath)
+            dim(`  resolved: ${finding.resolvedPath}`);
     }
 }
 function getRoot() {
     return findGuardRoot();
 }
+function loadConfigSafely(root, options = {}) {
+    try {
+        return { config: loadGuardConfig(root), invalid: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Guard configuration is invalid.';
+        const payload = guardErrorPayload('GUARD_CONFIG_INVALID', message, {
+            configured: false,
+            outcome: 'error',
+            recoverable: true,
+            hint: 'Repair or remove the invalid Guard artifact, then run `codapult-guard doctor`.',
+        });
+        if (options.json || options.machine)
+            console.log(JSON.stringify(payload, null, 2));
+        else
+            fail(`${payload.message} Run \`codapult-guard doctor\` for details.`);
+        process.exitCode = 1;
+        return { invalid: true };
+    }
+}
 function readRequirement(root, file) {
     if (!file)
         return undefined;
@@ -73,7 +97,7 @@ export function guardInitCommand(options = {}) {
     info(`${config.rules.length} rule(s) generated (${proposedRules} proposed); ${report.scannedFiles} source file(s) scanned.`);
     dim('Existing findings are baselined. New violations will be reported by `codapult-guard check`.');
 }
-export function guardAnalyzeCommand() {
+export function guardAnalyzeCommand(_options = {}) {
     const root = getRoot();
     const { model: projectModel, metrics } = discoverProjectWithMetrics(root, {
         persistCache: true,
@@ -90,7 +114,10 @@ export function guardAnalyzeCommand() {
 export function guardProposeCommand(options = {}) {
     const root = getRoot();
     const model = discoverProject(root);
-    const config = loadGuardConfig(root) ?? buildGeneratedGuardConfig(model);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config ?? buildGeneratedGuardConfig(model);
     const proposals = buildGuardProposals(model, config);
     const previous = loadGuardProposals(root);
     writeGuardProposals(root, {
@@ -134,9 +161,12 @@ export function guardInstallAgentCommand(target = 'generic', options = {}) {
     process.exitCode = 0;
 }
 export function guardDoctorCommand(options = {}) {
+    if (options.fixCache)
+        clearDiscoveryCache(getRoot());
     const report = diagnoseGuard(getRoot());
+    const result = options.fixCache ? { ...report, cacheFixed: true } : report;
     if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(result, null, 2));
     }
     else {
         heading('Codapult Guard Doctor');
@@ -153,7 +183,7 @@ export function guardDoctorCommand(options = {}) {
         else
             success('Guard state is healthy.');
     }
-    process.exitCode = report.status === 'fail' ? 1 : 0;
+    process.exitCode = result.status === 'fail' ? 1 : 0;
 }
 export function guardHistoryCommand() {
     const snapshots = listGuardSnapshots(getRoot());
@@ -166,6 +196,29 @@ export function guardHistoryCommand() {
         info(`${snapshot.revision}: ${snapshot.files} files, ${snapshot.modules} modules, ${snapshot.cycles} cycles`);
     }
 }
+export function guardImpactCommand(files, options = {}) {
+    const root = getRoot();
+    if (files.length === 0) {
+        fail('Specify at least one project-relative file.');
+        process.exitCode = 1;
+        return;
+    }
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const result = analyzeProjectImpact(discoverProject(root), files, loaded.config?.contracts ?? []);
+    if (options.json) {
+        console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
+        return;
+    }
+    heading('Codapult Guard Impact');
+    info(`Requested: ${result.requestedFiles.join(', ')}`);
+    info(`Direct modules: ${result.directModules.join(', ') || 'none'}`);
+    info(`Dependencies: ${result.dependencies.join(', ') || 'none'}`);
+    info(`Transitive dependents: ${result.dependents.join(', ') || 'none'}`);
+    info(`Capabilities: ${result.capabilities.join(', ') || 'none'}`);
+    info(`Relevant contracts: ${result.relevantContracts.map((contract) => contract.id).join(', ') || 'none'}`);
+}
 export function guardHistoryDiffCommand(from, to, options = {}) {
     const diff = diffGuardSnapshots(getRoot(), from, to);
     if (!diff) {
@@ -181,6 +234,9 @@ export function guardHistoryDiffCommand(from, to, options = {}) {
         info(`Removed files: ${diff.removedFiles.length}`);
         info(`Added dependencies: ${diff.addedDependencies.join(', ') || 'none'}`);
         info(`Removed dependencies: ${diff.removedDependencies.join(', ') || 'none'}`);
+        info(`Modules: +${diff.addedModules.length} / -${diff.removedModules.length}`);
+        info(`Dependency edges: +${diff.addedDependencyEdges.length} / -${diff.removedDependencyEdges.length}`);
+        info(`Layer edges: +${diff.addedLayerEdges.length} / -${diff.removedLayerEdges.length}`);
         info(`Capabilities: +${diff.addedCapabilities.join(', ') || 'none'} / -${diff.removedCapabilities.join(', ') || 'none'}`);
         info(`Cycles: ${diff.cycles.from} → ${diff.cycles.to}`);
     }
@@ -244,10 +300,20 @@ export function guardVerifyCommand(options = {}) {
 }
 export function guardCheckCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, { ...options, machine: options.json || options.sarif });
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -304,10 +370,20 @@ export function guardCheckCommand(options = {}) {
 }
 export function guardAuditCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -364,9 +440,12 @@ export function guardBaselineCommand(action, ids, options = {}) {
         process.exitCode = 0;
         return;
     }
+    const loaded = options.all ? loadConfigSafely(root, options) : { invalid: false };
+    if (loaded.invalid)
+        return;
     const selected = options.all
         ? [
-            ...scanGuard(root, loadGuardConfig(root) ?? buildGeneratedGuardConfig(discoverProject(root)), {
+            ...scanGuard(root, loaded.config ?? buildGeneratedGuardConfig(discoverProject(root)), {
                 includeArchitectureInsights: true,
             }).findings.map((finding) => finding.fingerprint),
         ]
@@ -391,7 +470,10 @@ export function guardBaselineCommand(action, ids, options = {}) {
 }
 export function guardRulesApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -418,9 +500,55 @@ export function guardRulesApproveCommand(ids, options = {}) {
         success(`Activated ${rule.id}`);
     process.exitCode = 0;
 }
+export function guardPolicyExplainCommand(id, options = {}) {
+    const root = getRoot();
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
+    const proposals = loadGuardProposals(root);
+    if (!config) {
+        fail('Guard is not initialized. Run `codapult-guard init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const item = [...config.rules, ...(config.contracts ?? [])].find((entry) => entry.id === id);
+    const proposed = [...(proposals?.rules ?? []), ...(proposals?.contracts ?? [])].find((entry) => entry.id === id);
+    if (!item && !proposed) {
+        fail(`Policy item not found: ${id}`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = {
+        id,
+        active: item?.status !== 'proposed' && item !== undefined,
+        definition: item ?? proposed,
+        proposal: proposed,
+        decisions: proposals?.decisions?.filter((decision) => decision.id === id) ?? [],
+    };
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        heading(`Guard Policy: ${id}`);
+        info(`Status: ${result.active ? 'active' : 'proposed'}`);
+        const definition = result.definition;
+        if (definition && 'description' in definition)
+            dim(definition.description);
+        if (definition && 'statement' in definition)
+            dim(definition.statement);
+        if ((definition?.evidence?.length ?? 0) > 0)
+            dim(`Evidence: ${definition?.evidence?.join(', ')}`);
+        if (result.decisions.length > 0)
+            dim(`Decisions: ${result.decisions.length}`);
+    }
+    process.exitCode = 0;
+}
 export function guardContractsApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -453,7 +581,10 @@ export function guardContractsApproveCommand(ids, options = {}) {
 }
 export function guardContractsRejectCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -488,7 +619,10 @@ export function guardReviewCommand(options = {}) {
     const requirement = readRequirement(root, options.requirement);
     if (options.requirement && !requirement)
         return;
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail(`Guard is not initialized. Run \`codapult-guard init\` first.`);
         process.exitCode = 1;

package/dist/cli/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardInitCommand, guardInstallAgentCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
+import { GuardConfigError, GuardStateBusyError } from '../core/guard.js';
+import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
     .description('Local-first architecture guardrails for JavaScript and TypeScript projects')
@@ -15,12 +17,13 @@ const program = new Command()
 // `codapult-guard init`, not `codapult-guard guard init`.
 const guard = program;
 guard.command('init').option('--force').action(guardInitCommand);
-guard.command('analyze').action(guardAnalyzeCommand);
+guard.command('analyze').option('--refresh').action(guardAnalyzeCommand);
 guard.command('propose').option('--json').action(guardProposeCommand);
 guard.command('install-agent [target]').option('--json').action(guardInstallAgentCommand);
-guard.command('doctor').option('--json').action(guardDoctorCommand);
+guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
+guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard
     .command('check')
     .option('--changed')
@@ -46,6 +49,8 @@ guard
     .action(guardReviewCommand);
 const rules = guard.command('rules');
 rules.command('approve [ids]').option('--all').action(guardRulesApproveCommand);
+const policy = guard.command('policy');
+policy.command('explain <id>').option('--json').action(guardPolicyExplainCommand);
 const contracts = guard.command('contracts');
 contracts.command('approve [ids]').option('--all').action(guardContractsApproveCommand);
 contracts.command('reject [ids]').option('--all').action(guardContractsRejectCommand);
@@ -72,4 +77,23 @@ program
     .action(async () => {
     await import('../mcp/server.js');
 });
-program.parse();
+try {
+    program.parse();
+}
+catch (error) {
+    if (error instanceof GuardConfigError || error instanceof GuardStateBusyError) {
+        const isBusy = error instanceof GuardStateBusyError;
+        console.error(JSON.stringify(guardErrorPayload(isBusy ? 'GUARD_STATE_BUSY' : 'GUARD_CONFIG_INVALID', error.message, {
+            configured: !isBusy,
+            outcome: 'error',
+            recoverable: true,
+            hint: isBusy
+                ? 'Retry after the other Guard process finishes.'
+                : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+        }), null, 2));
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/core/analysis/doctor.js

@@ -22,12 +22,18 @@ function parseJson(root, path) {
 export function diagnoseGuard(root) {
     const initialized = existsSync(resolve(root, GUARD_BASELINE_FILE));
     const items = requiredArtifacts.map((path) => {
-        const guardConfig = path === GUARD_CONTRACTS_FILE ? loadGuardConfig(root) : undefined;
         if (!existsSync(resolve(root, path))) {
             return { path, status: 'missing', message: 'Artifact is missing.' };
         }
-        if (path === GUARD_RULES_FILE && !loadGuardConfig(root)) {
-            return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+        if (path === GUARD_RULES_FILE) {
+            try {
+                if (!loadGuardConfig(root)) {
+                    return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+                }
+            }
+            catch {
+                return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+            }
         }
         if (path === GUARD_PROJECT_FILE && !loadProjectModel(root)) {
             return { path, status: 'invalid', message: 'Project model is invalid or unsupported.' };
@@ -39,8 +45,16 @@ export function diagnoseGuard(root) {
             return { path, status: 'invalid', message: 'Guard contracts are invalid or unsupported.' };
         }
         if (path === GUARD_CONTRACTS_FILE &&
-            guardConfig &&
-            validateGuardContracts(root, guardConfig.contracts).length > 0) {
+            (() => {
+                try {
+                    const guardConfig = loadGuardConfig(root);
+                    return (guardConfig !== undefined &&
+                        validateGuardContracts(root, guardConfig.contracts).length > 0);
+                }
+                catch {
+                    return true;
+                }
+            })()) {
             return { path, status: 'invalid', message: 'Guard contract scopes or references are stale.' };
         }
         if (path === GUARD_PROPOSALS_FILE && !isGuardProposalFile(parseJson(root, path))) {

package/dist/core/analysis/impact.d.ts

@@ -0,0 +1,22 @@
+import type { GuardContract } from '../guard.js';
+import { type ProjectModel } from '../discovery/discovery.js';
+export interface GuardImpactAnalysis {
+    requestedFiles: string[];
+    directModules: string[];
+    dependencies: string[];
+    dependents: string[];
+    affectedModules: string[];
+    impactPaths: ProjectModel['insights']['impactPaths'];
+    capabilities: string[];
+    relevantContracts: GuardContract[];
+    dependencyEdges: ProjectModel['insights']['dependencyEdges'];
+    layerEdges: ProjectModel['insights']['layerEdges'];
+}
+/**
+ * Computes the blast radius of a change from the discovered graph.
+ *
+ * The graph direction is importer -> imported module. Therefore `dependencies` are what the
+ * changed code relies on, while `dependents` are callers that can regress when the changed
+ * code changes. Both directions matter for an AI review packet.
+ */
+export declare function analyzeProjectImpact(model: ProjectModel, files: Iterable<string>, contracts?: GuardContract[]): GuardImpactAnalysis;