@codapult/guard 0.2.0 → 0.4.0

package/README.md

@@ -168,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:
@@ -186,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
@@ -218,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
@@ -259,6 +297,7 @@ Recommended agent loop:
 
 ```text
 task finished
+  → codapult_guard_next_action
   → codapult_guard_context
   → codapult_guard_review(requirement, diff)
   → codapult_guard_verify
@@ -269,6 +308,25 @@ 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.
+
 ## CI
 
 Copy the consumer workflow into a project that has installed and initialized Guard:
@@ -298,11 +356,25 @@ real project shapes.
 | `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.
+
+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,19 @@ export interface CommandResult {
     exitCode: number;
     stdout: string;
     stderr: string;
-    timedOut?: boolean;
-    truncated?: boolean;
+    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

@@ -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/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/cli/commands/guard.d.ts

@@ -1,58 +1,57 @@
 import { type GuardToolMode } from '../../core/guard.js';
-export declare function guardInitCommand(options?: {
-    force?: boolean;
-}): void;
-export declare function guardAnalyzeCommand(): 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;
+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 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 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 {};