@codapult/guard 0.8.1 → 0.9.0

package/README.md

@@ -148,10 +148,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 +328,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 +407,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 +431,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.                         |
 

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.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 {
@@ -85,11 +86,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 +113,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 +135,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'));

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,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.8.1",
+  "version": "0.9.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",
@@ -98,7 +98,7 @@
     "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",
@@ -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.3",
+    "eslint": "^10.12.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"
+    "prettier": "^3.9.10",
+    "release-it": "^21.1.1",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
   }
 }