@codapult/guard 0.8.1 → 0.10.0

package/README.md

@@ -9,11 +9,14 @@
 
 ## Architecture guardrails for AI coding agents
 
-`@codapult/guard` is a local-first, model-agnostic architecture guard for JavaScript and
-TypeScript projects.
+`@codapult/guard` is local-first, model-agnostic **architecture guardrail software for AI coding
+agents**. Use it to detect architectural drift, enforce approved software architecture rules, and
+check code changes in JavaScript and TypeScript projects.
 
-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.
+Guard learns how your codebase is structured, records project architecture as reviewable memory, and
+checks future changes against the rules your team approves. It connects AI coding agents to those
+rules and returns deterministic evidence when a change introduces a covered architecture
+regression. Run the same project-specific checks locally and in CI.
 
 ### See the value in one change
 
@@ -148,10 +151,13 @@ Guard stores policy at the project level, while each policy item can target a na
 | Waiver      | One active finding fingerprint, with owner, reason, and expiry         |
 
 Routine checks do not change source code, rules, contracts, baseline, or waivers. Commands that
-change policy are explicit: `init`, `rules/contracts approve|reject`, `baseline accept|remove`, and
+change policy are explicit: `init`, `rules approve`, `contracts approve|reject`, `baseline accept|remove`, and
 `waiver add|renew|remove`. `analyze` refreshes derived project facts, while `verify` may run the
 project's configured commands and records a local run manifest; neither changes approved policy.
 
+For the complete mutation contract and host/CI controls, see
+[Policy mutation control](docs/policy-mutations.md).
+
 ## What Guard discovers
 
 The model is framework-aware without being framework-dependent:
@@ -325,6 +331,12 @@ task finished
   → repeat until pass or bounded iteration limit
 ```
 
+`codapult_guard_context` keeps the project state explicit for the host: `observations` are
+discovered facts only, `proposals.pendingRules` and `proposals.pendingContracts` are unapproved
+policy suggestions, `policy` contains only active rules/contracts plus baseline and waiver state,
+and `verification` reports whether a check has actually run. A context response with
+`verification.status: "not-run"` and `findings: null` is not a passing check.
+
 For Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and generic hosts, see
 [`docs/integrations/`](docs/integrations/).
 
@@ -398,7 +410,9 @@ cp node_modules/@codapult/guard/docs/guard-ci.yml .github/workflows/guard.yml
 ```
 
 Or copy it from [`docs/guard-ci.yml`](docs/guard-ci.yml). It runs project verification and exports
-Guard findings as SARIF for GitHub code scanning.
+Guard findings as SARIF for GitHub code scanning. Pull requests install dependencies without
+lifecycle scripts and use deterministic Guard checks without executing PR-owned scripts; trusted
+pushes may run the configured project checks.
 
 The package repository separately runs its own unit, typecheck, build, and packaging checks in
 [`.github/workflows/ci.yml`](.github/workflows/ci.yml), while the fixture workflow tests Guard on
@@ -420,7 +434,7 @@ real project shapes.
 | `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.                                                          |
+| `rules` / `contracts`      | Approve rules; approve or reject contracts.                                                 |
 | `baseline`                 | Review or intentionally accept existing findings.                                           |
 | `waiver`                   | Manage owner-attributed, time-bounded exceptions to exact findings.                         |
 
@@ -444,6 +458,13 @@ audits this metadata and reports missing or overlapping declared actors. It cont
 or external telemetry. These manifests make a failed run explainable without turning Guard into a
 production tracing system or an identity/signature ledger.
 
+The manifest also contains a `verification-receipt` object. It is a compact, machine-readable
+record of the commit, policy base and fingerprint, decision IDs, check statuses, finding counts,
+contract issues, waiver state, and Guard version. It intentionally excludes command output and
+source code. The receipt describes what Guard decided; it is not a cryptographic signature or proof
+of CI identity. When a policy base is supplied, it separates the base diff from dirty working-tree
+files so local verification cannot silently present an incomplete change set.
+
 ## Security and data handling
 
 - Deterministic discovery and checks run locally.
@@ -488,12 +509,6 @@ Starting a SaaS from scratch? [Codapult](https://codapult.dev) is a production-r
 foundation built for AI-assisted development — with MCP context, built-in AI, modular
 architecture, and the source code under your control.
 
-## Project status
-
-`@codapult/guard` starts at `0.1.0` as a public alpha. The deterministic core is usable, tested,
-and intended for real projects, while policy schema and integration surfaces may still evolve
-before `1.0.0`.
-
 ## License
 
 MIT. See [LICENSE](LICENSE).

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

@@ -64,6 +64,7 @@ export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove
 export declare function guardWaiverCommand(action: 'list' | 'add' | 'remove' | 'renew', value?: string, options?: GuardWaiverOptions): void;
 export declare function guardRulesApproveCommand(ids?: string, options?: GuardApprovalOptions): void;
 export declare function guardPolicyExplainCommand(id: string, options?: GuardOutputOptions): void;
+export declare function guardPolicyMutationsCommand(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;

package/dist/cli/commands/guard.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 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, GuardWaiverError, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, loadGuardWaivers, updateBaseline, updateGuardWaivers, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardPolicy, writeProjectState, } 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, GuardWaiverError, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, loadGuardWaivers, updateBaseline, updateGuardWaivers, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, getGuardPolicyMutationPolicy, 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';
@@ -719,6 +719,26 @@ export function guardPolicyExplainCommand(id, options = {}) {
     }
     process.exitCode = 0;
 }
+export function guardPolicyMutationsCommand(options = {}) {
+    const root = getRoot();
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const policy = getGuardPolicyMutationPolicy(loaded.config);
+    if (options.json) {
+        console.log(JSON.stringify(policy, null, 2));
+    }
+    else {
+        heading('Guard Policy Mutations');
+        info(policy.message);
+        for (const operation of policy.operations) {
+            info(`${operation.id}: ${operation.surfaces.join(', ')}; ${operation.guardBlocksMcp === true
+                ? 'MCP blocked in protected mode'
+                : 'external control required'}`);
+        }
+    }
+    process.exitCode = 0;
+}
 export function guardContractsApproveCommand(ids, options = {}) {
     const root = getRoot();
     const loaded = loadConfigSafely(root);

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/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, guardGovernanceCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, guardWaiverCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardGovernanceCommand, guardPolicyExplainCommand, guardPolicyMutationsCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, guardWaiverCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
 import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, GuardWaiverError, } from '../core/guard.js';
 import { GuardAgentInstallError } from '../adapters/agents/agent-integration.js';
@@ -56,6 +56,7 @@ 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);
+policy.command('mutations').option('--json').action(guardPolicyMutationsCommand);
 const contracts = guard.command('contracts');
 contracts.command('approve [ids]').option('--all').action(guardContractsApproveCommand);
 contracts.command('reject [ids]').option('--all').action(guardContractsRejectCommand);

package/dist/core/discovery/discovery.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
 import { config } from '../config.js';
@@ -61,6 +61,23 @@ const DISCOVERY_CACHE_VERSION = 3;
 function discoveryCachePath(root) {
     return resolve(root, `.${config.appName}/guard/cache.json`);
 }
+function canPersistDiscoveryCache(root) {
+    const parent = resolve(root, `.${config.appName}`);
+    const directory = dirname(discoveryCachePath(root));
+    for (const path of [parent, directory]) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const stats = lstatSync(path);
+            if (stats.isSymbolicLink() || !stats.isDirectory())
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
 export function clearDiscoveryCache(root) {
     rmSync(discoveryCachePath(root), { force: true });
 }
@@ -941,7 +958,8 @@ function discoverProjectOnce(root, options = {}, attempt = 0) {
     }
     discoveryCache.set(cacheKey, { signature, model });
     discoveryReuse.set(cacheKey, reusedModules);
-    if (options.persistCache ?? existsSync(resolve(root, `.${config.appName}/guard`))) {
+    if (canPersistDiscoveryCache(root) &&
+        (options.persistCache ?? existsSync(resolve(root, `.${config.appName}/guard`)))) {
         try {
             mkdirSync(resolve(root, `.${config.appName}/guard`), { recursive: true });
             const cachePath = discoveryCachePath(root);

package/dist/core/guard.d.ts

@@ -87,11 +87,32 @@ export interface GuardConfig {
     approval?: GuardApprovalPolicy | undefined;
     waiverPolicy?: GuardWaiverPolicy | undefined;
 }
+export declare function getGuardPolicyMutationPolicy(guardConfig: GuardConfig | undefined): GuardPolicyMutationPolicy;
 export interface GuardApprovalPolicy {
     mode: GuardApprovalMode;
     allowMcpApproval: boolean;
     requireDistinctActor: boolean;
 }
+export type GuardPolicyMutationId = 'init.force' | 'proposal.approve' | 'proposal.reject' | 'rules.approve' | 'contracts.approve' | 'contracts.reject' | 'baseline.accept' | 'baseline.remove' | 'waiver.add' | 'waiver.renew' | 'waiver.remove' | 'policy-file.edit';
+export interface GuardPolicyMutationDescriptor {
+    id: GuardPolicyMutationId;
+    surfaces: ('cli' | 'mcp' | 'file')[];
+    changesPolicy: true;
+    guardConfirmation: boolean;
+    reasonRequired: boolean;
+    guardBlocksMcp?: boolean | undefined;
+    externalApprovalRequired: true;
+    externalControl: 'host-or-ci';
+}
+export interface GuardPolicyMutationPolicy {
+    version: 1;
+    status: 'declared';
+    humanOnlyEnforcedByGuard: false;
+    message: string;
+    approvalMode: GuardApprovalMode;
+    requireDistinctActor: boolean;
+    operations: GuardPolicyMutationDescriptor[];
+}
 export interface GuardProposalFile {
     version: 1;
     generatedAt: string;

package/dist/core/guard.js

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, extname, relative, resolve, sep } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
 import { buildModuleTargetGraph } from './discovery/discovery.js';
@@ -19,6 +19,79 @@ export function classifyGuardOutcome(input) {
         return 'needs-review';
     return (input.warnings ?? 0) > 0 ? 'warning' : 'pass';
 }
+export function getGuardPolicyMutationPolicy(guardConfig) {
+    const approval = guardConfig?.approval ?? {
+        mode: 'local',
+        allowMcpApproval: true,
+        requireDistinctActor: false,
+    };
+    const protectedMode = approval.mode === 'protected';
+    const mcpApprovalBlocked = protectedMode && !approval.allowMcpApproval;
+    const descriptor = (id, surfaces, options) => ({
+        id,
+        surfaces,
+        changesPolicy: true,
+        ...options,
+        ...(options.guardBlocksMcp !== undefined ? { guardBlocksMcp: options.guardBlocksMcp } : {}),
+        externalApprovalRequired: true,
+        externalControl: 'host-or-ci',
+    });
+    return {
+        version: 1,
+        status: 'declared',
+        humanOnlyEnforcedByGuard: false,
+        message: 'Guard identifies policy mutations and applies its configured checks; a host or CI system must enforce human/external approval.',
+        approvalMode: approval.mode,
+        requireDistinctActor: approval.requireDistinctActor,
+        operations: [
+            descriptor('init.force', ['cli', 'mcp'], {
+                guardConfirmation: true,
+                reasonRequired: false,
+                guardBlocksMcp: mcpApprovalBlocked,
+            }),
+            descriptor('proposal.approve', ['mcp'], {
+                guardConfirmation: true,
+                reasonRequired: false,
+                guardBlocksMcp: mcpApprovalBlocked,
+            }),
+            descriptor('proposal.reject', ['mcp'], {
+                guardConfirmation: true,
+                reasonRequired: false,
+                guardBlocksMcp: false,
+            }),
+            descriptor('rules.approve', ['cli'], { guardConfirmation: false, reasonRequired: false }),
+            descriptor('contracts.approve', ['cli'], {
+                guardConfirmation: false,
+                reasonRequired: false,
+            }),
+            descriptor('contracts.reject', ['cli'], {
+                guardConfirmation: false,
+                reasonRequired: false,
+            }),
+            descriptor('baseline.accept', ['cli'], { guardConfirmation: false, reasonRequired: true }),
+            descriptor('baseline.remove', ['cli'], { guardConfirmation: false, reasonRequired: true }),
+            descriptor('waiver.add', ['cli', 'mcp'], {
+                guardConfirmation: true,
+                reasonRequired: true,
+                guardBlocksMcp: mcpApprovalBlocked,
+            }),
+            descriptor('waiver.renew', ['cli', 'mcp'], {
+                guardConfirmation: true,
+                reasonRequired: true,
+                guardBlocksMcp: mcpApprovalBlocked,
+            }),
+            descriptor('waiver.remove', ['cli', 'mcp'], {
+                guardConfirmation: true,
+                reasonRequired: true,
+                guardBlocksMcp: mcpApprovalBlocked,
+            }),
+            descriptor('policy-file.edit', ['file'], {
+                guardConfirmation: false,
+                reasonRequired: false,
+            }),
+        ],
+    };
+}
 export const GUARD_DIR = `.${config.appName}/guard`;
 export const GUARD_RULES_FILE = `${GUARD_DIR}/rules.json`;
 export const GUARD_BASELINE_FILE = `${GUARD_DIR}/baseline.json`;
@@ -144,8 +217,24 @@ function getActiveStateRoot(path) {
 function safeGeneration(value) {
     return typeof value === 'string' && /^[A-Za-z0-9._-]+$/.test(value);
 }
+function assertGuardStateDirectory(root) {
+    const stateParent = resolve(root, dirname(GUARD_DIR));
+    const stateDirectory = resolve(root, GUARD_DIR);
+    for (const path of [stateParent, stateDirectory]) {
+        if (!existsSync(path))
+            continue;
+        const stats = lstatSync(path);
+        if (stats.isSymbolicLink()) {
+            throw new GuardConfigError(`${path} must not be a symbolic link.`);
+        }
+        if (!stats.isDirectory()) {
+            throw new GuardConfigError(`${path} must be a directory.`);
+        }
+    }
+}
 export function withGuardStateLock(root, callback, options = {}) {
     const normalizedRoot = resolve(root);
+    assertGuardStateDirectory(normalizedRoot);
     const activeDepth = activeStateLocks.get(normalizedRoot);
     if (activeDepth !== undefined) {
         activeStateLocks.set(normalizedRoot, activeDepth + 1);
@@ -222,6 +311,15 @@ function isGuardConfig(value) {
     return guardConfigSchema.safeParse(value).success;
 }
 function readJson(filePath) {
+    let stats;
+    try {
+        stats = lstatSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+    if (stats.isSymbolicLink())
+        throw new GuardConfigError(filePath);
     try {
         return JSON.parse(readFileSync(filePath, 'utf8'));
     }
@@ -555,9 +653,15 @@ export function loadBaseline(root) {
     if (!existsSync(path))
         return new Set();
     const value = readJson(path);
-    if (!Array.isArray(value))
+    if (!Array.isArray(value)) {
         throw new GuardConfigError(GUARD_BASELINE_FILE);
-    return new Set(value.filter((item) => typeof item === 'string'));
+    }
+    const entries = value;
+    const stringEntries = entries.filter((item) => typeof item === 'string');
+    if (stringEntries.length !== entries.length) {
+        throw new GuardConfigError(GUARD_BASELINE_FILE);
+    }
+    return new Set(stringEntries);
 }
 function validateGuardWaiversFile(value) {
     const ids = new Set();

package/dist/core/history/history.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { GUARD_HISTORY_DIR } from '../guard.js';
 function snapshotInsights(model) {
@@ -18,7 +18,10 @@ function readSnapshot(root, revision) {
     if (!/^[A-Za-z0-9._-]+$/.test(revision))
         return undefined;
     try {
-        return JSON.parse(readFileSync(resolve(root, GUARD_HISTORY_DIR, `${revision}.json`), 'utf8'));
+        const path = resolve(root, GUARD_HISTORY_DIR, `${revision}.json`);
+        if (!lstatSync(path).isFile())
+            return undefined;
+        return JSON.parse(readFileSync(path, 'utf8'));
     }
     catch {
         return undefined;
@@ -28,8 +31,23 @@ export function listGuardSnapshots(root) {
     const directory = resolve(root, GUARD_HISTORY_DIR);
     if (!existsSync(directory))
         return [];
+    try {
+        if (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
     return readdirSync(directory)
         .filter((file) => file.endsWith('.json'))
+        .filter((file) => {
+        try {
+            return lstatSync(resolve(directory, file)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
         .sort()
         .flatMap((file) => {
         const revision = file.slice(0, -5);

package/dist/core/history/runs.d.ts

@@ -13,6 +13,47 @@ export interface GuardRunPolicy {
     changedFromBase?: boolean | undefined;
     decisionIds?: string[] | undefined;
 }
+export interface GuardVerificationReceiptCheck {
+    status: 'passed' | 'failed' | 'not-configured';
+    exitCode: number;
+    durationMs: number;
+}
+export interface GuardVerificationReceipt {
+    version: 1;
+    kind: 'verification-receipt';
+    runId: string;
+    generatedAt: string;
+    outcome: GuardRunManifest['outcome'];
+    gate: string;
+    subject: {
+        commit?: string | undefined;
+        baseRef?: string | undefined;
+        baseCommit?: string | undefined;
+        changedFiles: string[];
+        baseChangedFiles?: string[] | undefined;
+        workingTreeFiles?: string[] | undefined;
+        workingTreeDirty: boolean;
+    };
+    policy?: GuardRunPolicy | undefined;
+    stages: Record<string, 'ok' | 'fail' | 'skipped'>;
+    checks: Record<string, GuardVerificationReceiptCheck>;
+    findings: {
+        total: number;
+        errors: number;
+        warnings: number;
+        waived: number;
+        waiverWarnings: number;
+        expiredWaivers: number;
+        fingerprints: string[];
+        ruleIds: string[];
+    };
+    contractIssues: string[];
+    decisionIds: string[];
+    tool: {
+        name: string;
+        version: string;
+    };
+}
 export interface GuardRunManifest {
     version: 1;
     runId: string;
@@ -25,6 +66,7 @@ export interface GuardRunManifest {
     stages: Record<string, GuardRunStage>;
     commit?: string | undefined;
     policy?: GuardRunPolicy | undefined;
+    receipt?: GuardVerificationReceipt | undefined;
 }
 export interface GuardRunContext {
     runId: string;
@@ -49,4 +91,4 @@ export declare function writeGuardRun(root: string, manifest: GuardRunManifest):
 /** Reads locally persisted run manifests without reaching a remote service. */
 export declare function listGuardRuns(root: string, limit?: number): GuardRunManifest[];
 export declare function summarizeGuardRuns(root: string, limit?: number): GuardRunSummary;
-export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy): GuardRunManifest;
+export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy, receipt?: Omit<GuardVerificationReceipt, 'runId' | 'generatedAt' | 'outcome' | 'gate' | 'subject'> & Pick<GuardVerificationReceipt, 'subject'>): GuardRunManifest;

package/dist/core/history/runs.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, lstatSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { resolve } from 'node:path';
 import { config } from '../config.js';
+import { withGuardStateLock } from '../guard.js';
 export const GUARD_RUNS_DIR = `.${config.appName}/guard/history/runs`;
 export const GUARD_RUN_RETENTION = 200;
 export class GuardRunManifestError extends Error {
@@ -11,11 +12,109 @@ export class GuardRunManifestError extends Error {
         this.name = 'GuardRunManifestError';
     }
 }
+function isGuardRunPolicy(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const policy = value;
+    return (typeof policy.fingerprint === 'string' &&
+        policy.fingerprint.length > 0 &&
+        (policy.source === 'working-tree' || policy.source === 'git-ref') &&
+        (policy.revision === undefined ||
+            (Number.isInteger(policy.revision) && policy.revision >= 0)) &&
+        (policy.ref === undefined || typeof policy.ref === 'string') &&
+        (policy.changedFromBase === undefined || typeof policy.changedFromBase === 'boolean') &&
+        (policy.decisionIds === undefined ||
+            (Array.isArray(policy.decisionIds) &&
+                new Set(policy.decisionIds).size === policy.decisionIds.length &&
+                policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0) &&
+                (policy.source === 'working-tree' || policy.decisionIds.length === 0))));
+}
 function isGuardRunManifest(value) {
     if (value === null || typeof value !== 'object')
         return false;
     const manifest = value;
     const stages = manifest.stages;
+    const receipt = manifest.receipt;
+    const validReceipt = receipt === undefined ||
+        (receipt !== null &&
+            typeof receipt === 'object' &&
+            receipt.version === 1 &&
+            receipt.kind === 'verification-receipt' &&
+            typeof receipt.runId === 'string' &&
+            receipt.runId === manifest.runId &&
+            typeof receipt.generatedAt === 'string' &&
+            Number.isFinite(Date.parse(receipt.generatedAt)) &&
+            (receipt.outcome === 'pass' ||
+                receipt.outcome === 'fail' ||
+                receipt.outcome === 'warning' ||
+                receipt.outcome === 'needs-review' ||
+                receipt.outcome === 'not-configured') &&
+            typeof receipt.gate === 'string' &&
+            receipt.subject !== null &&
+            typeof receipt.subject === 'object' &&
+            Array.isArray(receipt.subject.changedFiles) &&
+            receipt.subject.changedFiles.every((file) => typeof file === 'string') &&
+            (receipt.subject.baseChangedFiles === undefined ||
+                (Array.isArray(receipt.subject.baseChangedFiles) &&
+                    receipt.subject.baseChangedFiles.every((file) => typeof file === 'string'))) &&
+            (receipt.subject.workingTreeFiles === undefined ||
+                (Array.isArray(receipt.subject.workingTreeFiles) &&
+                    receipt.subject.workingTreeFiles.every((file) => typeof file === 'string'))) &&
+            typeof receipt.subject.workingTreeDirty === 'boolean' &&
+            (receipt.subject.commit === undefined || typeof receipt.subject.commit === 'string') &&
+            (receipt.subject.baseRef === undefined || typeof receipt.subject.baseRef === 'string') &&
+            (receipt.subject.baseCommit === undefined ||
+                typeof receipt.subject.baseCommit === 'string') &&
+            (receipt.policy === undefined || isGuardRunPolicy(receipt.policy)) &&
+            receipt.stages !== null &&
+            typeof receipt.stages === 'object' &&
+            !Array.isArray(receipt.stages) &&
+            Object.values(receipt.stages).every((status) => status === 'ok' || status === 'fail' || status === 'skipped') &&
+            receipt.checks !== null &&
+            typeof receipt.checks === 'object' &&
+            !Array.isArray(receipt.checks) &&
+            Object.values(receipt.checks).every((check) => {
+                if (check === null || typeof check !== 'object')
+                    return false;
+                const candidate = check;
+                return ((candidate.status === 'passed' ||
+                    candidate.status === 'failed' ||
+                    candidate.status === 'not-configured') &&
+                    Number.isInteger(candidate.exitCode) &&
+                    typeof candidate.durationMs === 'number' &&
+                    Number.isFinite(candidate.durationMs) &&
+                    candidate.durationMs >= 0);
+            }) &&
+            receipt.findings !== null &&
+            typeof receipt.findings === 'object' &&
+            ['total', 'errors', 'warnings', 'waived', 'waiverWarnings', 'expiredWaivers'].every((key) => {
+                const countValue = receipt.findings[key];
+                return typeof countValue === 'number' && Number.isInteger(countValue) && countValue >= 0;
+            }) &&
+            Array.isArray(receipt.findings.fingerprints) &&
+            receipt.findings.fingerprints.every((fingerprint) => typeof fingerprint === 'string') &&
+            Array.isArray(receipt.findings.ruleIds) &&
+            receipt.findings.ruleIds.every((ruleId) => typeof ruleId === 'string') &&
+            Array.isArray(receipt.contractIssues) &&
+            receipt.contractIssues.every((issue) => typeof issue === 'string') &&
+            Array.isArray(receipt.decisionIds) &&
+            new Set(receipt.decisionIds).size === receipt.decisionIds.length &&
+            receipt.decisionIds.every((decisionId) => typeof decisionId === 'string') &&
+            receipt.tool !== null &&
+            typeof receipt.tool === 'object' &&
+            typeof receipt.tool.name === 'string' &&
+            typeof receipt.tool.version === 'string');
+    const receiptMatchesManifest = receipt === undefined ||
+        (receipt.outcome === manifest.outcome &&
+            receipt.gate === manifest.gate &&
+            (manifest.commit === undefined
+                ? receipt.subject.commit === undefined
+                : receipt.subject.commit === manifest.commit) &&
+            (manifest.policy === undefined
+                ? receipt.policy === undefined
+                : receipt.policy?.fingerprint === manifest.policy.fingerprint &&
+                    receipt.policy.source === manifest.policy.source &&
+                    receipt.policy.revision === manifest.policy.revision));
     const validStages = stages !== null &&
         typeof stages === 'object' &&
         !Array.isArray(stages) &&
@@ -50,22 +149,9 @@ function isGuardRunManifest(value) {
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
         validStages &&
-        (manifest.policy === undefined ||
-            (manifest.policy !== null &&
-                typeof manifest.policy === 'object' &&
-                typeof manifest.policy.fingerprint === 'string' &&
-                manifest.policy.fingerprint.length > 0 &&
-                (manifest.policy.source === 'working-tree' || manifest.policy.source === 'git-ref') &&
-                (manifest.policy.revision === undefined ||
-                    (Number.isInteger(manifest.policy.revision) && manifest.policy.revision >= 0)) &&
-                (manifest.policy.ref === undefined || typeof manifest.policy.ref === 'string') &&
-                (manifest.policy.changedFromBase === undefined ||
-                    typeof manifest.policy.changedFromBase === 'boolean') &&
-                (manifest.policy.decisionIds === undefined ||
-                    (manifest.policy.source === 'working-tree' &&
-                        Array.isArray(manifest.policy.decisionIds) &&
-                        new Set(manifest.policy.decisionIds).size === manifest.policy.decisionIds.length &&
-                        manifest.policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0))))));
+        validReceipt &&
+        receiptMatchesManifest &&
+        (manifest.policy === undefined || isGuardRunPolicy(manifest.policy)));
 }
 export function startGuardRun() {
     return {
@@ -85,11 +171,15 @@ export function recordGuardRunStage(context, name, status, startedAtMs, detail)
 function pruneGuardRuns(root) {
     const directory = resolve(root, GUARD_RUNS_DIR);
     try {
+        if (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory())
+            return;
         const files = readdirSync(directory)
             .filter((file) => file.endsWith('.json'))
             .map((file) => ({
             file,
-            modifiedAt: statSync(resolve(directory, file)).mtimeMs,
+            modifiedAt: lstatSync(resolve(directory, file)).isSymbolicLink()
+                ? 0
+                : statSync(resolve(directory, file)).mtimeMs,
         }))
             .sort((left, right) => right.modifiedAt - left.modifiedAt);
         for (const entry of files.slice(GUARD_RUN_RETENTION)) {
@@ -108,13 +198,20 @@ function pruneGuardRuns(root) {
 export function writeGuardRun(root, manifest) {
     if (!isGuardRunManifest(manifest))
         throw new GuardRunManifestError();
-    const directory = resolve(root, GUARD_RUNS_DIR);
-    mkdirSync(directory, { recursive: true });
-    const path = resolve(directory, `${manifest.runId}.json`);
-    const temporaryPath = `${path}.tmp-${process.pid}-${manifest.runId}`;
-    writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-    renameSync(temporaryPath, path);
-    pruneGuardRuns(root);
+    withGuardStateLock(root, () => {
+        const directory = resolve(root, GUARD_RUNS_DIR);
+        if (existsSync(directory)) {
+            const stats = lstatSync(directory);
+            if (stats.isSymbolicLink() || !stats.isDirectory())
+                throw new GuardRunManifestError();
+        }
+        mkdirSync(directory, { recursive: true });
+        const path = resolve(directory, `${manifest.runId}.json`);
+        const temporaryPath = `${path}.tmp-${process.pid}-${manifest.runId}`;
+        writeFileSync(temporaryPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+        renameSync(temporaryPath, path);
+        pruneGuardRuns(root);
+    });
 }
 /** Reads locally persisted run manifests without reaching a remote service. */
 export function listGuardRuns(root, limit = 20) {
@@ -123,8 +220,19 @@ export function listGuardRuns(root, limit = 20) {
     const boundedLimit = Math.min(limit, 1_000);
     const directory = resolve(root, GUARD_RUNS_DIR);
     try {
+        const directoryStats = lstatSync(directory);
+        if (directoryStats.isSymbolicLink() || !directoryStats.isDirectory())
+            return [];
         return readdirSync(directory)
             .filter((file) => file.endsWith('.json'))
+            .filter((file) => {
+            try {
+                return lstatSync(resolve(directory, file)).isFile();
+            }
+            catch {
+                return false;
+            }
+        })
             .map((file) => {
             try {
                 const value = JSON.parse(readFileSync(resolve(directory, file), 'utf8'));
@@ -154,7 +262,7 @@ export function summarizeGuardRuns(root, limit = 100) {
         ...(total > 0 ? { last: runs[0] } : {}),
     };
 }
-export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy) {
+export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy, receipt) {
     let commit;
     try {
         commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' })
@@ -164,18 +272,50 @@ export function finishGuardRun(root, context, outcome, gate, command = 'verify',
     catch {
         commit = undefined;
     }
+    const completedAt = new Date().toISOString();
+    const completedReceipt = {
+        version: 1,
+        kind: 'verification-receipt',
+        runId: context.runId,
+        generatedAt: completedAt,
+        outcome,
+        gate,
+        subject: {
+            ...receipt?.subject,
+            ...(commit ? { commit } : {}),
+            changedFiles: receipt?.subject.changedFiles ?? [],
+            workingTreeDirty: receipt?.subject.workingTreeDirty ?? false,
+        },
+        ...(policy ? { policy } : {}),
+        stages: receipt?.stages ?? {},
+        checks: receipt?.checks ?? {},
+        findings: receipt?.findings ?? {
+            total: 0,
+            errors: 0,
+            warnings: 0,
+            waived: 0,
+            waiverWarnings: 0,
+            expiredWaivers: 0,
+            fingerprints: [],
+            ruleIds: [],
+        },
+        contractIssues: receipt?.contractIssues ?? [],
+        decisionIds: receipt?.decisionIds ?? policy?.decisionIds ?? [],
+        tool: receipt?.tool ?? { name: '@codapult/guard', version: 'unknown' },
+    };
     const manifest = {
         version: 1,
         runId: context.runId,
         command,
         startedAt: context.startedAt,
-        completedAt: new Date().toISOString(),
+        completedAt,
         durationMs: Math.max(0, Date.now() - context.startedAtMs),
         outcome,
         gate,
         stages: context.stages,
         ...(commit ? { commit } : {}),
         ...(policy ? { policy } : {}),
+        receipt: completedReceipt,
     };
     try {
         writeGuardRun(root, manifest);

package/dist/core/verification/verify.js

@@ -1,9 +1,13 @@
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import {} from '../../adapters/command.js';
 import { runProjectAdapters, runProjectChecks, runWorkspaceProjectChecks, inspectProjectRuntime, } from '../../adapters/project-checks.js';
 import { loadGuardPolicyAtRevision, loadGuardWorkingTreePolicy, scanGuard, classifyGuardOutcome, validateGuardPolicy, } from '../guard.js';
 import { analyzeProjectImpact } from '../analysis/impact.js';
 import { discoverProject } from '../discovery/discovery.js';
 import { finishGuardRun, recordGuardRunStage, startGuardRun, } from '../history/runs.js';
+const require = createRequire(import.meta.url);
+const packageJson = require('../../../package.json');
 function buildRunPolicy(snapshot, base, changedFromBase, decisionIds = []) {
     return {
         ...(snapshot.revision !== undefined ? { revision: snapshot.revision } : {}),
@@ -14,6 +18,94 @@ function buildRunPolicy(snapshot, base, changedFromBase, decisionIds = []) {
         ...(decisionIds.length > 0 ? { decisionIds } : {}),
     };
 }
+function receiptCheck(result) {
+    return {
+        status: result.status,
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+    };
+}
+function resolveGitCommit(root, ref) {
+    if (!ref)
+        return undefined;
+    try {
+        const commit = execFileSync('git', ['rev-parse', `${ref}^{commit}`], {
+            cwd: root,
+            stdio: 'pipe',
+            timeout: 5_000,
+        })
+            .toString()
+            .trim();
+        return /^[0-9a-f]{40}$/i.test(commit) ? commit : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function changedFilesSince(root, baseRef) {
+    if (!baseRef)
+        return undefined;
+    try {
+        return execFileSync('git', ['diff', '--name-only', `${baseRef}...HEAD`], {
+            cwd: root,
+            stdio: 'pipe',
+            timeout: 5_000,
+        })
+            .toString()
+            .split('\n')
+            .map((file) => file.trim().replace(/\\/g, '/'))
+            .filter(Boolean)
+            .sort();
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildVerificationReceipt(root, policy, impact, checks, workspaceChecks, adapters, architecture, contractIssues, stages) {
+    const baseCommit = resolveGitCommit(root, policy.ref);
+    const baseChangedFiles = changedFilesSince(root, policy.ref);
+    const workingTreeFiles = impact.requestedFiles;
+    const receiptChecks = {};
+    for (const [name, result] of Object.entries(checks)) {
+        receiptChecks[name] = receiptCheck(result);
+    }
+    for (const [workspacePackage, packageChecks] of Object.entries(workspaceChecks)) {
+        for (const [name, result] of Object.entries(packageChecks)) {
+            receiptChecks[`${workspacePackage}:${name}`] = receiptCheck(result);
+        }
+    }
+    for (const [name, result] of Object.entries(adapters)) {
+        receiptChecks[`adapter:${name}`] = receiptCheck(result);
+    }
+    return {
+        version: 1,
+        kind: 'verification-receipt',
+        subject: {
+            ...(policy.ref ? { baseRef: policy.ref } : {}),
+            ...(baseCommit ? { baseCommit } : {}),
+            ...(baseChangedFiles ? { baseChangedFiles } : {}),
+            ...(workingTreeFiles.length > 0 ? { workingTreeFiles } : {}),
+            changedFiles: [...new Set([...(baseChangedFiles ?? []), ...workingTreeFiles])].sort(),
+            workingTreeDirty: workingTreeFiles.length > 0,
+        },
+        policy,
+        stages,
+        checks: receiptChecks,
+        findings: {
+            total: architecture.findings.length,
+            errors: architecture.findings.filter((finding) => finding.severity === 'error').length,
+            warnings: architecture.findings.filter((finding) => finding.severity === 'warning').length,
+            waived: architecture.waived,
+            waiverWarnings: architecture.waiverWarnings.length,
+            expiredWaivers: architecture.expiredWaivers.length,
+            fingerprints: architecture.findings.map((finding) => finding.fingerprint).sort(),
+            ruleIds: [...new Set(architecture.findings.map((finding) => finding.ruleId))].sort(),
+        },
+        contractIssues: contractIssues.map((issue) => issue.contractId),
+        decisionIds: policy.decisionIds ?? [],
+        tool: { name: '@codapult/guard', version: packageJson.version },
+    };
+}
 export function runGuardVerification(root, options = {}) {
     const runContext = startGuardRun();
     const requirement = {
@@ -65,11 +157,12 @@ export function runGuardVerification(root, options = {}) {
         };
     }
     if (!workingTreeState) {
-        const run = finishGuardRun(root, runContext, 'not-configured', 'configuration');
+        const policyEnforcementFailed = options.failOnPolicyChange === true;
+        const run = finishGuardRun(root, runContext, policyEnforcementFailed ? 'fail' : 'not-configured', policyEnforcementFailed ? 'policy-change' : 'configuration');
         return {
-            status: 'not-configured',
-            outcome: 'not-configured',
-            errorCode: 'GUARD_NOT_CONFIGURED',
+            status: policyEnforcementFailed ? 'fail' : 'not-configured',
+            outcome: policyEnforcementFailed ? 'fail' : 'not-configured',
+            errorCode: policyEnforcementFailed ? 'GUARD_POLICY_CHANGED' : 'GUARD_NOT_CONFIGURED',
             recoverable: true,
             checks: {},
             workspaceChecks: {},
@@ -193,20 +286,27 @@ export function runGuardVerification(root, options = {}) {
     const commandFailed = Object.values(results).some((result) => result.status === 'failed');
     const workspaceCommandFailed = Object.values(workspaceChecks).some((packageResults) => Object.values(packageResults).some((result) => result.status === 'failed'));
     const adapterFailed = Object.values(adapters).some((result) => result.status === 'failed');
-    const missingRequiredTools = options.strict &&
-        [...Object.values(results), ...Object.values(adapters)].some((result) => result.status === 'not-configured');
+    const missingProjectChecks = projectChecks &&
+        (checks.length === 0 ||
+            Object.values(results).some((result) => result.status === 'not-configured') ||
+            Object.values(workspaceChecks).some((packageResults) => Object.values(packageResults).some((result) => result.status === 'not-configured')));
+    const missingAdapterTools = options.strict && Object.values(adapters).some((result) => result.status === 'not-configured');
+    const runtimeFailed = projectChecks && !runtime.compatible;
     const architectureFailed = architecture.findings.some((finding) => finding.severity === 'error');
+    const expiredWaivers = architecture.expiredWaivers.length > 0;
     const architectureWarnings = architecture.findings.some((finding) => finding.severity === 'warning') ||
         (architecture.waiverWarnings ?? []).length > 0;
-    const failed = (projectChecks && !runtime.compatible) ||
+    const failed = runtimeFailed ||
         commandFailed ||
         workspaceCommandFailed ||
         adapterFailed ||
         architectureFailed ||
+        expiredWaivers ||
         contractIssues.length > 0 ||
-        missingRequiredTools;
-    const projectChecksFailed = commandFailed || workspaceCommandFailed || (projectChecks && !runtime.compatible);
-    const adaptersFailed = adapterFailed || missingRequiredTools;
+        missingProjectChecks ||
+        missingAdapterTools;
+    const projectChecksFailed = commandFailed || workspaceCommandFailed || missingProjectChecks || runtimeFailed;
+    const adaptersFailed = adapterFailed || missingAdapterTools;
     runContext.stages['project-checks'] = {
         ...runContext.stages['project-checks'],
         status: projectChecks ? (projectChecksFailed ? 'fail' : 'ok') : 'skipped',
@@ -215,15 +315,19 @@ export function runGuardVerification(root, options = {}) {
         ...runContext.stages.adapters,
         status: toolMode === 'off' ? 'skipped' : adaptersFailed ? 'fail' : 'ok',
     };
+    runContext.stages.runtime = {
+        ...runContext.stages.runtime,
+        status: runtimeFailed ? 'fail' : 'ok',
+    };
     runContext.stages['architecture-policy'] = {
         ...runContext.stages['architecture-policy'],
-        status: architectureFailed || contractIssues.length > 0 ? 'fail' : 'ok',
+        status: architectureFailed || expiredWaivers || contractIssues.length > 0 ? 'fail' : 'ok',
     };
     const outcome = classifyGuardOutcome({
         errors: failed ? 1 : 0,
         warnings: architectureWarnings ? 1 : 0,
     });
-    const gate = architectureFailed
+    const gate = architectureFailed || expiredWaivers
         ? 'architecture'
         : contractIssues.length > 0
             ? 'contracts'
@@ -231,12 +335,15 @@ export function runGuardVerification(root, options = {}) {
                 ? 'project-checks'
                 : adapterFailed
                     ? 'adapters'
-                    : missingRequiredTools
-                        ? 'required-tools'
-                        : !runtime.compatible && projectChecks
-                            ? 'runtime'
-                            : 'none';
-    const run = finishGuardRun(root, runContext, outcome, gate, 'verify', policy);
+                    : missingProjectChecks
+                        ? 'project-checks'
+                        : missingAdapterTools
+                            ? 'required-tools'
+                            : runtimeFailed
+                                ? 'runtime'
+                                : 'none';
+    const receipt = buildVerificationReceipt(root, policy, impact, results, workspaceChecks, adapters, architecture, contractIssues, Object.fromEntries(Object.entries(runContext.stages).map(([name, stage]) => [name, stage.status])));
+    const run = finishGuardRun(root, runContext, outcome, gate, 'verify', policy, receipt);
     return {
         status: failed ? 'fail' : 'ok',
         outcome,

package/dist/mcp/context.d.ts

@@ -0,0 +1,48 @@
+import type { ProjectModel } from '../core/discovery/discovery.js';
+import { getPendingGuardProposals, type GuardConfig, type GuardProposalFile, type GuardWaiver } from '../core/guard.js';
+export interface GuardDiscoveryMetrics {
+    durationMs: number;
+    files: number;
+    modules: number;
+    changedFiles: number;
+    reusedModules: number;
+    cacheHit: boolean;
+    cacheAvailable: boolean;
+}
+export interface GuardContextState {
+    observations: {
+        status: 'observed-only';
+        project: ProjectModel;
+        architecture: Record<string, unknown>;
+        conventions: Record<string, unknown>;
+        discovery: GuardDiscoveryMetrics | undefined;
+    };
+    proposals: {
+        status: 'not-configured' | 'none' | 'pending-approval' | 'stale' | 'decided';
+        requiresApproval: boolean;
+        freshness: 'current' | 'stale' | 'unknown' | 'none';
+        proposalId?: string | undefined;
+        generatedBy?: string | undefined;
+        pendingRules: GuardConfig['rules'];
+        pendingContracts: NonNullable<GuardConfig['contracts']>;
+        questions: string[];
+        pending: ReturnType<typeof getPendingGuardProposals>;
+    };
+    policy: {
+        status: 'not-configured' | 'active';
+        rules: GuardConfig['rules'];
+        contracts: NonNullable<GuardConfig['contracts']>;
+        baseline: {
+            status: 'not-configured' | 'active';
+            count: number;
+        };
+        waivers: GuardWaiver[];
+    };
+    verification: {
+        status: 'not-run';
+        findings: null;
+        message: string;
+        next: 'codapult_guard_init' | 'codapult_guard_check';
+    };
+}
+export declare function buildGuardContextState(project: ProjectModel, discovery: GuardDiscoveryMetrics | undefined, architecture: Record<string, unknown>, conventions: Record<string, unknown>, config: GuardConfig | undefined, proposals: GuardProposalFile | undefined, baseline: Set<string>, waivers: GuardWaiver[]): GuardContextState;

package/dist/mcp/context.js

@@ -0,0 +1,49 @@
+import { getGuardProposalFreshness, getPendingGuardProposals, } from '../core/guard.js';
+export function buildGuardContextState(project, discovery, architecture, conventions, config, proposals, baseline, waivers) {
+    const pending = getPendingGuardProposals(proposals);
+    const freshness = proposals ? getGuardProposalFreshness(project, proposals) : 'none';
+    const pendingRuleIds = new Set(pending.filter((item) => item.type === 'rule').map((item) => item.id));
+    const pendingContractIds = new Set(pending.filter((item) => item.type === 'contract').map((item) => item.id));
+    const pendingRules = proposals?.rules.filter((rule) => rule.status === 'proposed' && pendingRuleIds.has(rule.id)) ??
+        [];
+    const pendingContracts = proposals?.contracts.filter((contract) => contract.status === 'proposed' && pendingContractIds.has(contract.id)) ?? [];
+    const proposalStatus = config === undefined
+        ? 'not-configured'
+        : proposals === undefined
+            ? 'none'
+            : freshness === 'stale'
+                ? 'stale'
+                : pending.length > 0
+                    ? 'pending-approval'
+                    : 'decided';
+    return {
+        observations: { status: 'observed-only', project, architecture, conventions, discovery },
+        proposals: {
+            status: proposalStatus,
+            requiresApproval: pending.length > 0 || freshness === 'stale',
+            freshness,
+            ...(proposals?.proposalId ? { proposalId: proposals.proposalId } : {}),
+            ...(proposals?.generatedBy ? { generatedBy: proposals.generatedBy } : {}),
+            pendingRules,
+            pendingContracts,
+            questions: proposals?.questions ?? [],
+            pending,
+        },
+        policy: {
+            status: config === undefined ? 'not-configured' : 'active',
+            rules: config?.rules.filter((rule) => rule.status === 'active') ?? [],
+            contracts: config?.contracts?.filter((contract) => contract.status === 'active') ?? [],
+            baseline: {
+                status: config === undefined ? 'not-configured' : 'active',
+                count: baseline.size,
+            },
+            waivers,
+        },
+        verification: {
+            status: 'not-run',
+            findings: null,
+            message: 'Context contains facts and policy state; it does not run verification.',
+            next: config === undefined ? 'codapult_guard_init' : 'codapult_guard_check',
+        },
+    };
+}

package/dist/mcp/resources.js

@@ -1,4 +1,5 @@
-import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, loadGuardWaivers, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, getGuardPolicyMutationPolicy, loadBaseline, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, loadGuardWaivers, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { buildGuardContextState } from './context.js';
 import { guardErrorPayload } from '../core/errors.js';
 import { DiscoveryStaleError } from '../core/discovery/discovery.js';
 import { listGuardRuns, summarizeGuardRuns } from '../core/history/runs.js';
@@ -62,15 +63,17 @@ export function registerGuardResources(server) {
         try {
             const project = discoverProject(root);
             const config = loadGuardConfig(root);
+            const architecture = (loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ??
+                buildArchitectureMemory(project));
+            const conventions = (loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ??
+                buildConventionsMemory(project));
+            const state = buildGuardContextState(project, undefined, architecture, conventions, config, loadGuardProposals(root), loadBaseline(root), loadGuardWaivers(root));
             return jsonResource('codapult://guard/context', {
                 version: 1,
                 root,
                 configured: config !== undefined,
-                project,
-                architecture: loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project),
-                conventions: loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project),
-                rules: config?.rules ?? [],
-                contracts: config?.contracts ?? [],
+                mutationPolicy: getGuardPolicyMutationPolicy(config),
+                ...state,
                 agent: loadGuardAgentConfig(root),
             });
         }

package/dist/mcp/tools/guard.js

@@ -1,11 +1,17 @@
 import { randomUUID } from 'node:crypto';
-import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, loadGuardWaivers, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, GuardStateBusyError, GuardStateStaleError, applyGuardProposalDecision, validateGuardProposalApproval, writeProjectState, scanGuard, updateGuardWaivers, validateGuardPolicy, classifyGuardOutcome, } from '../../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, loadGuardWaivers, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, GuardStateBusyError, GuardStateStaleError, applyGuardProposalDecision, validateGuardProposalApproval, writeProjectState, scanGuard, updateGuardWaivers, validateGuardPolicy, classifyGuardOutcome, getGuardPolicyMutationPolicy, } from '../../core/guard.js';
 import { guardErrorPayload } from '../../core/errors.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { z } from 'zod';
 import { runGuardVerification } from '../../core/verification/verify.js';
 import { auditGuardGovernance } from '../../core/audit/governance.js';
+import { buildGuardContextState } from '../context.js';
 const rootSchema = z.string().trim().min(1).optional().describe('Project path or workspace root.');
+function asGuardContextRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
 function getGuardRoot(root) {
     return root ? findGuardRoot(root) : findGuardRoot();
 }
@@ -61,6 +67,21 @@ function loadBaselineSafely(root) {
         };
     }
 }
+function loadWaiversSafely(root) {
+    try {
+        return { waivers: loadGuardWaivers(root) };
+    }
+    catch (error) {
+        return {
+            error: jsonToolResult(guardErrorPayload('GUARD_CONFIG_INVALID', error instanceof Error ? error.message : String(error), {
+                configured: true,
+                outcome: 'error',
+                recoverable: true,
+                hint: 'Repair waivers.json, then run codapult-guard doctor.',
+            }), true),
+        };
+    }
+}
 function stateErrorResult(error) {
     const isBusy = error instanceof GuardStateBusyError;
     const isStale = error instanceof GuardStateStaleError;
@@ -247,6 +268,22 @@ export function registerGuardTools(server) {
             ? discoverProjectWithMetrics(root, { persistCache: true })
             : { model: loadProjectModel(root) ?? discoverProject(root), metrics: undefined };
         const project = discovery.model;
+        const architecture = asGuardContextRecord(refresh
+            ? buildArchitectureMemory(project)
+            : (loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ?? buildArchitectureMemory(project)));
+        const conventions = asGuardContextRecord(refresh
+            ? buildConventionsMemory(project)
+            : (loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ?? buildConventionsMemory(project)));
+        const loadedProposals = loadProposalsSafely(root);
+        if ('error' in loadedProposals)
+            return loadedProposals.error;
+        const loadedBaseline = loadBaselineSafely(root);
+        if (loadedBaseline.error)
+            return loadedBaseline.error;
+        const loadedWaivers = loadWaiversSafely(root);
+        if (loadedWaivers.error)
+            return loadedWaivers.error;
+        const state = buildGuardContextState(project, discovery.metrics, architecture, conventions, config, loadedProposals.proposals, loadedBaseline.baseline ?? new Set(), loadedWaivers.waivers ?? []);
         return {
             content: [
                 {
@@ -259,18 +296,8 @@ export function registerGuardTools(server) {
                         tools: agentConfig.tools,
                         tooling: agentConfig.tooling,
                         completionGate: agentConfig.completionGate,
-                        rules: config?.rules ?? [],
-                        contracts: config?.contracts ?? [],
-                        architecture: refresh
-                            ? buildArchitectureMemory(project)
-                            : (loadGuardArtifact(root, GUARD_ARCHITECTURE_FILE) ??
-                                buildArchitectureMemory(project)),
-                        conventions: refresh
-                            ? buildConventionsMemory(project)
-                            : (loadGuardArtifact(root, GUARD_CONVENTIONS_FILE) ??
-                                buildConventionsMemory(project)),
-                        project,
-                        discovery: discovery.metrics,
+                        mutationPolicy: getGuardPolicyMutationPolicy(config),
+                        ...state,
                     }, null, 2),
                 },
             ],
@@ -337,6 +364,19 @@ export function registerGuardTools(server) {
         const root = getGuardRoot(requestedRoot);
         if (!confirm)
             return jsonToolResult({ status: 'needs-confirmation', root, force });
+        const loadedConfig = loadConfigSafely(root);
+        if (loadedConfig.error)
+            return loadedConfig.error;
+        if (force &&
+            loadedConfig.config?.approval?.mode === 'protected' &&
+            !loadedConfig.config.approval.allowMcpApproval) {
+            return jsonToolResult({
+                status: 'approval-required',
+                message: 'Protected Guard policy requires forced initialization outside the MCP agent surface.',
+                source: 'mcp',
+                force,
+            }, true);
+        }
         try {
             const result = initializeGuard(root, { force, waitMs: wait_ms, noWait: no_wait });
             return jsonToolResult({ status: 'ok', root, report: result.report });

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@codapult/guard",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "mcpName": "io.github.codapult/guard",
   "description": "Local-first architecture guardrails for JavaScript and TypeScript projects, with first-class support for Next.js SaaS and AI-assisted development",
   "license": "MIT",
-  "packageManager": "pnpm@12.4.2+sha512.08adc6613180275c7c9edada39dcf08c9c61ad4e7eaf330a4f3461f102b0f907423454d117f98e72d47fef0616070644d7bffc973a6a57f5090a6d7c368b07c9",
+  "packageManager": "pnpm@12.14.0+sha512.c18ba6d87993d3d164cb5e8948f32b2c06ee854487e06cd8d86781342fb3e5bb4634367034711e86802baa9c37bea906ce1929ad08d70884c97d801df13389a6",
   "engines": {
     "node": ">=20.19.0"
   },
@@ -98,13 +98,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "commander": "^15.0.0",
     "picocolors": "^1.1.1",
     "semver": "^7.8.5",
     "ts-morph": "^28.0.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@js-toolkit/config-utils": "^1.0.1",
@@ -112,15 +112,15 @@
     "@js-toolkit/prettier-config": "^1.0.1",
     "@js-toolkit/tsconfig": "^1.0.1",
     "@release-it/conventional-changelog": "^12.0.2",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.5",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "^5.0.1",
-    "eslint": "^10.11.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.6",
-    "prettier": "^3.9.8",
-    "release-it": "^21.1.0",
-    "typescript-eslint": "^8.70.1",
-    "vitest": "^5.0.1"
+    "eslint-plugin-prettier": "^5.5.7",
+    "prettier": "^3.9.10",
+    "release-it": "^21.1.1",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
   }
 }