@codapult/guard 0.3.0 → 0.5.0

package/README.md

@@ -231,12 +231,37 @@ Guard state is stored in `.codapult/guard/`:
 ├── proposals.json     evidence and approval history
 ├── baseline.json      accepted pre-existing findings
 ├── agent.json         AI-host completion-gate configuration
-└── history/           project snapshots for comparison
+└── history/           project snapshots and local verification run manifests
 ```
 
 Commit policy and baseline files when the team wants shared guardrails. Treat cache artifacts as
 disposable according to the project’s policy, and never commit secrets.
 
+### Optional scoped budgets
+
+Budgets are policy, not a universal style rule. Add them only for a named risk boundary such as a
+service, route handler, or dependency-heavy module:
+
+```json
+{
+  "id": "service-lines",
+  "description": "Services must remain reviewable.",
+  "metric": "lines",
+  "scope": ["src/services"],
+  "limit": 300,
+  "severity": "warning",
+  "reason": "Keep service changes reviewable by one owner.",
+  "status": "active"
+}
+```
+
+Place budgets in the `budgets` array in `.codapult/guard/rules.json`. Supported metrics are
+`lines`, `bytes`, and `imports`. Generated files, schemas, migrations, and other paths are not
+checked unless they are explicitly included in `scope`; a wildcard such as `*` can intentionally
+cover the project root. Invalid, absolute, parent-directory, or nonexistent scopes fail the Guard
+gate. Changing a budget is a policy decision:
+review the diff and update its written `reason` rather than silently increasing the limit.
+
 ## AI agents and MCP
 
 Guard is deliberately model-agnostic. It does not send source code to a remote LLM and does not
@@ -283,6 +308,28 @@ task finished
 For Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and generic hosts, see
 [`docs/integrations/`](docs/integrations/).
 
+For workflows where the authoring agent must not approve its own policy proposals, set Guard to
+protected mode in `rules.json`:
+
+```json
+{
+  "approval": {
+    "mode": "protected",
+    "allowMcpApproval": false,
+    "requireDistinctActor": true
+  }
+}
+```
+
+MCP can then read and propose policy, while approval happens through the CLI or a protected CI/PR
+process. With `requireDistinctActor`, CLI and permitted MCP approvals require `GUARD_APPROVER`,
+and Guard rejects the same declared actor when a proposal was generated with `GUARD_PROPOSER`.
+These variables provide declared provenance only; external branch protection or signed identity
+remains responsible for proving who approved the change.
+
+See [the extension map](docs/extensions.md) for the supported AI-host, CI/PR, policy-pack, tool
+adapter, approval-governance, and observability integrations.
+
 ## CI
 
 Copy the consumer workflow into a project that has installed and initialized Guard:
@@ -319,8 +366,18 @@ real project shapes.
 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.
 
+Guard state is safe for concurrent CLI/MCP readers and writers: derived facts are published as an
+atomic generation, policy updates use revisions, and short write contention is waited out. A
+process that dies while holding the state lock is detected by its local PID and the lock is
+recovered; use `--no-wait` when an integration needs immediate contention feedback.
+
 Run `pnpm exec codapult-guard <command> --help` for command-specific options.
 
+Every `verify` run also writes a local manifest under
+`.codapult/guard/history/runs/<run-id>.json`. It records stage durations, the outcome, and the
+policy gate that decided the result. It contains no source code or external telemetry. These
+manifests make a failed run explainable without turning Guard into a production tracing system.
+
 ## Security and data handling
 
 - Deterministic discovery and checks run locally.

package/dist/adapters/command.d.ts

@@ -5,17 +5,20 @@ export interface CommandResult {
     exitCode: number;
     stdout: string;
     stderr: string;
-    timedOut?: boolean;
-    truncated?: boolean;
+    durationMs: number;
+    timedOut?: boolean | undefined;
+    truncated?: boolean | undefined;
 }
-export declare function runProjectCommand(command: string, cwd: string, options?: {
-    timeout?: number;
-    env?: NodeJS.ProcessEnv;
-}): CommandResult;
-export declare function commandResponse(result: CommandResult): {
+export interface RunProjectCommandOptions {
+    timeout?: number | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+}
+export interface CommandResponse {
     content: {
         type: 'text';
         text: string;
     }[];
     isError: boolean;
-};
+}
+export declare function runProjectCommand(command: string, cwd: string, options?: RunProjectCommandOptions): CommandResult;
+export declare function commandResponse(result: CommandResult): CommandResponse;

package/dist/adapters/command.js

@@ -24,6 +24,7 @@ function parseCommand(command) {
     return { executable: windowsExecutable, args };
 }
 export function runProjectCommand(command, cwd, options = {}) {
+    const startedAt = Date.now();
     const parsed = parseCommand(command);
     if (!parsed) {
         return {
@@ -33,6 +34,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode: 2,
             stdout: '',
             stderr: 'Unsafe or empty project command rejected.',
+            durationMs: 0,
         };
     }
     try {
@@ -51,6 +53,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode: 0,
             stdout: captured.value,
             stderr: '',
+            durationMs: Math.max(0, Date.now() - startedAt),
             truncated: captured.truncated,
         };
     }
@@ -68,6 +71,7 @@ export function runProjectCommand(command, cwd, options = {}) {
             exitCode,
             stdout: stdout.value,
             stderr: timedOut ? `${stderr.value}\n[command timed out]` : stderr.value,
+            durationMs: Math.max(0, Date.now() - startedAt),
             timedOut,
             truncated: stdout.truncated || stderr.truncated,
         };

package/dist/adapters/project-checks.d.ts

@@ -1,20 +1,33 @@
 import { type CommandResult } from './command.js';
-export type ProjectCheck = 'lint' | 'typecheck' | 'test' | 'build';
-export type GuardAdapter = 'dependency-graph' | 'security' | 'dependency-hygiene';
-export type ExternalToolMode = 'auto' | 'on' | 'off';
+import type { GuardAdapterName, GuardToolMode, ProjectCheck } from '../core/model/types.js';
+export type { ProjectCheck } from '../core/model/types.js';
+export type GuardAdapter = GuardAdapterName;
+export type ExternalToolMode = GuardToolMode;
 export type ProjectCheckResults = Partial<Record<ProjectCheck, CommandResult>>;
+export interface ProjectChecksOptions {
+    timeout?: number | undefined;
+}
+export interface WorkspaceProjectChecksOptions extends ProjectChecksOptions {
+    rootResults?: ProjectCheckResults | undefined;
+}
+export interface ProjectAdaptersOptions {
+    mode?: Exclude<ExternalToolMode, 'off'> | undefined;
+    timeout?: number | undefined;
+    tooling?: Partial<Record<GuardAdapter, {
+        script: string;
+        enabled: boolean;
+    }>> | undefined;
+}
 export interface ProjectRuntimeDiagnostics {
     node: string;
     packageManager: string;
-    declaredPackageManager?: string;
-    declaredNode?: string;
+    declaredPackageManager?: string | undefined;
+    declaredNode?: string | undefined;
     compatible: boolean;
     issues: string[];
 }
 export declare function inspectProjectRuntime(root: string): ProjectRuntimeDiagnostics;
-export declare function runProjectChecks(root: string, checks: ProjectCheck[], options?: {
-    timeout?: number;
-}): ProjectCheckResults;
+export declare function runProjectChecks(root: string, checks: ProjectCheck[], options?: ProjectChecksOptions): ProjectCheckResults;
 /**
  * Runs checks for workspace packages only when the root package does not own
  * the corresponding check. Root orchestration remains the source of truth.
@@ -22,16 +35,6 @@ export declare function runProjectChecks(root: string, checks: ProjectCheck[], o
 export declare function runWorkspaceProjectChecks(root: string, packages: {
     path: string;
     scripts: Record<string, string>;
-}[], checks: ProjectCheck[], options?: {
-    timeout?: number;
-    rootResults?: ProjectCheckResults;
-}): Record<string, ProjectCheckResults>;
+}[], checks: ProjectCheck[], options?: WorkspaceProjectChecksOptions): Record<string, ProjectCheckResults>;
 /** Runs only explicitly configured project scripts; Guard does not recreate these tools. */
-export declare function runProjectAdapters(root: string, options?: {
-    mode?: Exclude<ExternalToolMode, 'off'>;
-    timeout?: number;
-    tooling?: Partial<Record<GuardAdapter, {
-        script: string;
-        enabled: boolean;
-    }>>;
-}): Partial<Record<GuardAdapter, CommandResult>>;
+export declare function runProjectAdapters(root: string, options?: ProjectAdaptersOptions): Partial<Record<GuardAdapter, CommandResult>>;

package/dist/adapters/project-checks.js

@@ -12,6 +12,7 @@ function notConfigured(check) {
         exitCode: 0,
         stdout: '',
         stderr: `${check} script is not configured`,
+        durationMs: 0,
     };
 }
 function readPackageMetadata(root) {
@@ -119,6 +120,9 @@ const adapterScriptPatterns = {
     'dependency-graph': /(?:dep(?:endency)?[-:]?(?:check|graph|cruise)|madge|architecture)/i,
     security: /(?:security|semgrep|gitleaks|snyk|trivy|audit)/i,
     'dependency-hygiene': /(?:knip|dep(?:endency)?[-:]?(?:unused|hygiene))/i,
+    sast: /(?:semgrep|codeql|bearer|sast)/i,
+    'secret-scanning': /(?:gitleaks|trufflehog|secret[-_ ]?scan)/i,
+    'dependency-audit': /(?:npm audit|pnpm audit|yarn audit|osv|snyk|trivy|dependency[-_ ]?audit)/i,
 };
 /** Runs only explicitly configured project scripts; Guard does not recreate these tools. */
 export function runProjectAdapters(root, options = {}) {
@@ -126,6 +130,7 @@ export function runProjectAdapters(root, options = {}) {
     const manager = packageManager(root, metadata.packageManager);
     const scripts = metadata.scripts ?? {};
     const results = {};
+    const executed = new Map();
     for (const [adapter, pattern] of Object.entries(adapterScriptPatterns)) {
         const configured = options.tooling?.[adapter];
         const script = configured?.enabled
@@ -141,9 +146,13 @@ export function runProjectAdapters(root, options = {}) {
             continue;
         }
         const command = manager === 'npm' ? `npm run ${script}` : `${manager} run ${script}`;
-        results[adapter] = runProjectCommand(command, root, {
-            timeout: options.timeout ?? 120_000,
-        });
+        const previous = executed.get(command);
+        const result = previous ??
+            runProjectCommand(command, root, {
+                timeout: options.timeout ?? 120_000,
+            });
+        executed.set(command, result);
+        results[adapter] = result;
     }
     return results;
 }

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

@@ -1,64 +1,58 @@
 import { type GuardToolMode } from '../../core/guard.js';
-export declare function guardInitCommand(options?: {
-    force?: boolean;
-}): void;
-export declare function guardAnalyzeCommand(_options?: {
-    refresh?: boolean;
-}): void;
-export declare function guardProposeCommand(options?: {
-    json?: boolean;
-}): void;
-export declare function guardInstallAgentCommand(target?: string, options?: {
-    json?: boolean;
-}): void;
-export declare function guardDoctorCommand(options?: {
-    json?: boolean;
-    fixCache?: boolean;
+interface GuardOutputOptions {
+    json?: boolean | undefined;
+}
+interface GuardInitOptions {
+    force?: boolean | undefined;
+    wait?: boolean | undefined;
+}
+interface GuardAnalyzeOptions {
+    refresh?: boolean | undefined;
+    wait?: boolean | undefined;
+}
+interface GuardVerifyOptions extends GuardOutputOptions {
+    checks?: string | undefined;
+    changed?: boolean | undefined;
+    requirement?: string | undefined;
+    tools?: GuardToolMode | undefined;
+    strict?: boolean | undefined;
+    projectChecks?: boolean | undefined;
+}
+interface GuardCheckOptions extends GuardOutputOptions {
+    changed?: boolean | undefined;
+    sarif?: boolean | undefined;
+}
+interface GuardBaselineOptions extends GuardOutputOptions {
+    all?: boolean | undefined;
+    reason?: string | undefined;
+}
+interface GuardApprovalOptions {
+    all?: boolean | undefined;
+}
+interface GuardReviewOptions {
+    maxDiffChars?: string | undefined;
+    requirement?: string | undefined;
+    base?: string | undefined;
+}
+export declare function guardInitCommand(options?: GuardInitOptions): void;
+export declare function guardAnalyzeCommand(options?: GuardAnalyzeOptions): void;
+export declare function guardProposeCommand(options?: GuardOutputOptions): void;
+export declare function guardInstallAgentCommand(target?: string, options?: GuardOutputOptions): void;
+export declare function guardDoctorCommand(options?: GuardOutputOptions & {
+    fixCache?: boolean | undefined;
 }): 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;
-export declare function guardVerifyCommand(options?: {
-    checks?: string;
-    changed?: boolean;
-    json?: boolean;
-    requirement?: string;
-    tools?: GuardToolMode;
-    strict?: boolean;
-    projectChecks?: boolean;
-}): void;
-export declare function guardCheckCommand(options?: {
-    changed?: boolean;
-    json?: boolean;
-    sarif?: boolean;
-}): void;
-export declare function guardAuditCommand(options?: {
-    json?: boolean;
-}): void;
-export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove', ids?: string, options?: {
-    all?: boolean;
-    reason?: string;
-    json?: boolean;
-}): void;
-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;
-export declare function guardContractsRejectCommand(ids?: string, options?: {
-    all?: boolean;
-}): void;
-export declare function guardReviewCommand(options?: {
-    maxDiffChars?: string;
-    requirement?: string;
-    base?: string;
-}): void;
+export declare function guardRunsCommand(options?: GuardOutputOptions): void;
+export declare function guardImpactCommand(files: string[], options?: GuardOutputOptions): void;
+export declare function guardHistoryDiffCommand(from: string, to: string, options?: GuardOutputOptions): void;
+export declare function guardVerifyCommand(options?: GuardVerifyOptions): void;
+export declare function guardCheckCommand(options?: GuardCheckOptions): void;
+export declare function guardAuditCommand(options?: GuardOutputOptions): void;
+export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove', ids?: string, options?: GuardBaselineOptions): void;
+export declare function guardRulesApproveCommand(ids?: string, options?: GuardApprovalOptions): void;
+export declare function guardPolicyExplainCommand(id: string, options?: GuardOutputOptions): void;
+export declare function guardContractsApproveCommand(ids?: string, options?: GuardApprovalOptions): void;
+export declare function guardContractsRejectCommand(ids?: string, options?: GuardApprovalOptions): void;
+export declare function guardReviewCommand(options?: GuardReviewOptions): void;
 export declare function guardIsInitialized(root: string): boolean;
+export {};

package/dist/cli/commands/guard.js

@@ -1,6 +1,6 @@
 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, 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 { 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, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardPolicy, writeProjectState, } from '../../core/guard.js';
 import { guardErrorPayload } from '../../core/errors.js';
 import { runGuardVerification, } from '../../core/verification/verify.js';
 import { diagnoseGuard } from '../../core/analysis/doctor.js';
@@ -9,6 +9,7 @@ import { guardAgentTargets, installGuardAgentInstructions, installGuardAgentTarg
 import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
+import { listGuardRuns, summarizeGuardRuns } from '../../core/history/runs.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -70,7 +71,7 @@ export function guardInitCommand(options = {}) {
     const root = getRoot();
     let initialized;
     try {
-        initialized = initializeGuard(root, { force: options.force });
+        initialized = initializeGuard(root, options.wait === false ? { force: options.force, noWait: true } : { force: options.force });
     }
     catch (error) {
         if (error instanceof GuardAlreadyInitializedError) {
@@ -97,14 +98,12 @@ 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(_options = {}) {
+export function guardAnalyzeCommand(options = {}) {
     const root = getRoot();
     const { model: projectModel, metrics } = discoverProjectWithMetrics(root, {
         persistCache: true,
     });
-    writeProjectModel(root, projectModel);
-    writeGuardMemory(root, projectModel);
-    const revision = writeProjectSnapshot(root, projectModel);
+    const revision = writeProjectState(root, projectModel, options.wait === false ? { noWait: true } : undefined);
     heading('Codapult Guard Analyze');
     success(`Updated ${GUARD_PROJECT_FILE}, ${GUARD_ARCHITECTURE_FILE}, and ${GUARD_CONVENTIONS_FILE}`);
     info(`${projectModel.files.length} file(s), ${projectModel.modules.length} module(s), ${projectModel.insights.cycles.length} cycle(s) recorded as project context.`);
@@ -196,6 +195,19 @@ export function guardHistoryCommand() {
         info(`${snapshot.revision}: ${snapshot.files} files, ${snapshot.modules} modules, ${snapshot.cycles} cycles`);
     }
 }
+export function guardRunsCommand(options = {}) {
+    const root = getRoot();
+    const result = { summary: summarizeGuardRuns(root), runs: listGuardRuns(root) };
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    heading('Codapult Guard Runs');
+    info(`${result.summary.total} run(s); ${result.summary.failed} failed, ${result.summary.warnings} warning, average ${result.summary.averageDurationMs} ms`);
+    for (const run of result.runs) {
+        info(`${run.runId}: ${run.outcome}, gate=${run.gate}, ${run.durationMs} ms`);
+    }
+}
 export function guardImpactCommand(files, options = {}) {
     const root = getRoot();
     if (files.length === 0) {
@@ -326,7 +338,7 @@ export function guardCheckCommand(options = {}) {
         baseline: loadBaseline(root),
         includeArchitectureInsights: true,
     });
-    const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+    const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
     const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
     const contractFindings = contractIssues.map((issue) => ({
@@ -392,7 +404,7 @@ export function guardAuditCommand(options = {}) {
         return;
     }
     const report = scanGuard(root, config, { includeArchitectureInsights: true });
-    const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+    const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
     const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
     if (options.json) {
@@ -491,11 +503,16 @@ export function guardRulesApproveCommand(ids, options = {}) {
         return;
     }
     const selectedIds = new Set(selected.map((rule) => rule.id));
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         rules: config.rules.map((rule) => selectedIds.has(rule.id) ? { ...rule, status: 'active' } : rule),
-    });
-    recordGuardProposalDecision(root, selected.map((rule) => ({ id: rule.id, type: 'rule', decision: 'approved' })));
+    }, selected.map((rule) => ({ id: rule.id, type: 'rule', decision: 'approved' })), { source: 'cli' });
     for (const rule of selected)
         success(`Activated ${rule.id}`);
     process.exitCode = 0;
@@ -566,15 +583,20 @@ export function guardContractsApproveCommand(ids, options = {}) {
         return;
     }
     const selectedIds = new Set(selected.map((contract) => contract.id));
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         contracts: (config.contracts ?? []).map((contract) => selectedIds.has(contract.id) ? { ...contract, status: 'active' } : contract),
-    });
-    recordGuardProposalDecision(root, selected.map((contract) => ({
+    }, selected.map((contract) => ({
         id: contract.id,
         type: 'contract',
         decision: 'approved',
-    })));
+    })), { source: 'cli' });
     for (const contract of selected)
         success(`Activated ${contract.id}`);
     process.exitCode = 0;
@@ -601,15 +623,20 @@ export function guardContractsRejectCommand(ids, options = {}) {
         process.exitCode = 1;
         return;
     }
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         contracts: config.contracts ?? [],
-    });
-    recordGuardProposalDecision(root, selected.map((contract) => ({
+    }, selected.map((contract) => ({
         id: contract.id,
         type: 'contract',
         decision: 'rejected',
-    })));
+    })), { source: 'cli' });
     for (const contract of selected)
         success(`Rejected ${contract.id}`);
     process.exitCode = 0;

package/dist/cli/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
-import { GuardConfigError, GuardStateBusyError } from '../core/guard.js';
+import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
 import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
@@ -16,12 +16,13 @@ const program = new Command()
 // Guard is the standalone product, so its commands live at the package root:
 // `codapult-guard init`, not `codapult-guard guard init`.
 const guard = program;
-guard.command('init').option('--force').action(guardInitCommand);
-guard.command('analyze').option('--refresh').action(guardAnalyzeCommand);
+guard.command('init').option('--force').option('--no-wait').action(guardInitCommand);
+guard.command('analyze').option('--refresh').option('--no-wait').action(guardAnalyzeCommand);
 guard.command('propose').option('--json').action(guardProposeCommand);
 guard.command('install-agent [target]').option('--json').action(guardInstallAgentCommand);
 guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
+guard.command('runs').option('--json').action(guardRunsCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard
@@ -81,15 +82,28 @@ try {
     program.parse();
 }
 catch (error) {
-    if (error instanceof GuardConfigError || error instanceof GuardStateBusyError) {
+    if (error instanceof GuardConfigError ||
+        error instanceof GuardBaselineReasonError ||
+        error instanceof GuardStateBusyError ||
+        error instanceof GuardStateStaleError) {
         const isBusy = error instanceof GuardStateBusyError;
-        console.error(JSON.stringify(guardErrorPayload(isBusy ? 'GUARD_STATE_BUSY' : 'GUARD_CONFIG_INVALID', error.message, {
-            configured: !isBusy,
+        const isStale = error instanceof GuardStateStaleError;
+        const isInvalidInput = error instanceof GuardBaselineReasonError;
+        console.error(JSON.stringify(guardErrorPayload(isBusy
+            ? 'GUARD_STATE_BUSY'
+            : isStale
+                ? 'GUARD_STATE_STALE'
+                : isInvalidInput
+                    ? 'GUARD_INVALID_INPUT'
+                    : 'GUARD_CONFIG_INVALID', error.message, {
+            configured: !isBusy && !isStale,
             outcome: 'error',
             recoverable: true,
-            hint: isBusy
-                ? 'Retry after the other Guard process finishes.'
-                : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+            hint: isBusy || isStale
+                ? 'Re-read Guard state and retry the operation.'
+                : isInvalidInput
+                    ? 'Provide a written reason for the baseline decision.'
+                    : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
         }), null, 2));
         process.exitCode = 1;
     }

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

@@ -7,6 +7,6 @@ export interface GuardDoctorReport {
     status: 'ok' | 'warning' | 'fail';
     initialized: boolean;
     items: GuardDoctorItem[];
-    recommendation?: string;
+    recommendation?: string | undefined;
 }
 export declare function diagnoseGuard(root: string): GuardDoctorReport;

package/dist/core/analysis/doctor.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { GUARD_AGENT_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_BASELINE_FILE, GUARD_CONVENTIONS_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_RULES_FILE, loadGuardConfig, loadProjectModel, isGuardAgentConfig, isGuardContractsFile, isGuardProposalFile, validateGuardContracts, } from '../guard.js';
+import { GUARD_AGENT_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_BASELINE_FILE, GUARD_CONVENTIONS_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_RULES_FILE, loadGuardConfig, loadProjectModel, isGuardAgentConfig, isGuardContractsFile, isGuardProposalFile, validateGuardPolicy, } from '../guard.js';
 const requiredArtifacts = [
     GUARD_BASELINE_FILE,
     GUARD_RULES_FILE,
@@ -48,8 +48,7 @@ export function diagnoseGuard(root) {
             (() => {
                 try {
                     const guardConfig = loadGuardConfig(root);
-                    return (guardConfig !== undefined &&
-                        validateGuardContracts(root, guardConfig.contracts).length > 0);
+                    return guardConfig !== undefined && validateGuardPolicy(root, guardConfig).length > 0;
                 }
                 catch {
                     return true;