@codapult/guard 0.7.0 → 0.8.0

package/README.md

@@ -172,6 +172,23 @@ Policy paths are validated as project-relative paths. Guard rejects traversal, a
 symlinks escaping the project root; import-boundary checks include imports, re-exports, and literal
 dynamic imports.
 
+### Policy scope and state changes
+
+Guard stores policy at the project level, while each policy item can target a narrower boundary:
+
+| Policy item | Scope controls                                                         |
+| ----------- | ---------------------------------------------------------------------- |
+| Rule        | `files`, import patterns, and rule kind                                |
+| Contract    | `scope`, `entrypoints`, import/package constraints, and required calls |
+| Budget      | `scope`, metric, limit, severity, and written reason                   |
+| Baseline    | Exact finding fingerprints already accepted as legacy debt             |
+| 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
+`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.
+
 ## What Guard discovers
 
 The model is framework-aware without being framework-dependent:
@@ -207,7 +224,7 @@ init once → edit → check --changed → review → verify → commit / merge
 ```
 
 1. `init` builds project memory and establishes the initial baseline.
-2. `check --changed` is the fast deterministic architecture gate.
+2. `check` scans the current project; `check --changed` is the fast change-scoped architecture gate.
 3. `review` prepares a bounded and redacted diff packet for an AI host; it does not call an LLM.
 4. `verify` runs Guard policy, configured project checks, adapters, runtime diagnostics, and
    contract validation.
@@ -238,6 +255,11 @@ Guard state is stored in `.codapult/guard/`:
 Commit policy and baseline files when the team wants shared guardrails. Treat cache artifacts as
 disposable according to the project’s policy, and never commit secrets.
 
+Baseline fingerprints do not include line numbers, so formatting and line movement do not recreate
+the same finding. They do include the rule and affected file/import identity, so a rename or module
+move can produce a new fingerprint and should be reviewed explicitly before accepting it into the
+baseline.
+
 ### Temporary waivers
 
 Baseline records legacy findings that existed when Guard was introduced. A waiver is different: it
@@ -315,9 +337,10 @@ Register that command in the MCP client from the project root. For example, Curs
 {
   "mcpServers": {
     "codapult-guard": {
+      "type": "stdio",
       "command": "pnpm",
       "args": ["exec", "codapult-guard", "mcp-server"],
-      "cwd": "."
+      "cwd": "${workspaceFolder}"
     }
   }
 }
@@ -369,6 +392,37 @@ and Guard rejects the same declared actor when a proposal was generated with `GU
 These variables provide declared provenance only; external branch protection or signed identity
 remains responsible for proving who approved the change.
 
+### Verifying against protected policy
+
+In CI, verify pull requests against the policy from the protected base commit rather than the
+copy carried by the branch:
+
+```bash
+codapult-guard verify --policy-base "$BASE_SHA" --json
+```
+
+Guard then evaluates the changed source with the base commit's rules, contracts, baseline, waivers,
+and completion-gate configuration. The result reports `policy.source`, `policy.ref`,
+`policy.revision`, `policy.fingerprint`, and whether the checked-out policy differs from that
+base. A branch cannot relax its policy or disable the gate and use that relaxed copy for the same
+verification run.
+
+The supplied [`docs/guard-ci.yml`](docs/guard-ci.yml) fetches the full Git history and passes the
+pull request base SHA automatically. Protect `.codapult/guard/` with CODEOWNERS or the equivalent
+review control when policy changes require a separate approval. For example, a repository can add
+`.codapult/guard/* @architecture-owners` to `CODEOWNERS`. Guard reports the policy change; the
+hosting platform enforces reviewer authorization.
+
+To make policy changes fail this invocation explicitly, add:
+
+```bash
+codapult-guard verify --policy-base "$BASE_SHA" --fail-on-policy-change
+```
+
+This is useful for a dedicated policy-review gate. It is intentionally separate from using the
+base policy for source verification, so teams can choose how their protected review workflow
+handles an approved policy update.
+
 See [the extension map](docs/extensions.md) for the supported AI-host, CI/PR, policy-pack, tool
 adapter, approval-governance, and observability integrations.
 
@@ -394,16 +448,18 @@ real project shapes.
 | `init`                     | Create project memory and the initial baseline.                                             |
 | `analyze`                  | Refresh facts without changing policy or baseline.                                          |
 | `propose`                  | Generate evidence-based rule and contract proposals.                                        |
-| `check --changed`          | Enforce active policy on changed and untracked files.                                       |
+| `check [--changed]`        | Enforce active policy; `--changed` limits findings to changed and untracked files.          |
 | `audit`                    | Scan the complete current project, including baseline findings.                             |
 | `review`                   | Create a bounded semantic-review packet for an AI host.                                     |
 | `verify`                   | Run the configured completion gate.                                                         |
+| `governance`               | Audit declared proposal/approval provenance and decision-to-run reachability.               |
 | `doctor`                   | Diagnose invalid or missing Guard artifacts.                                                |
 | `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution.                       |
 | `impact <files...>`        | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. |
 | `policy explain <id>`      | Explain a policy item, its evidence, and approval history.                                  |
 | `rules` / `contracts`      | Approve or reject proposed policy.                                                          |
 | `baseline`                 | Review or intentionally accept existing findings.                                           |
+| `waiver`                   | Manage owner-attributed, time-bounded exceptions to exact findings.                         |
 
 Use `analyze --refresh` after a structural change. `doctor --fix-cache` removes only the disposable
 discovery cache; it does not change rules, contracts, baseline, or source files.
@@ -417,8 +473,13 @@ Run `pnpm exec codapult-guard <command> --help` for command-specific options.
 
 Every `verify` run also writes a local manifest under
 `.codapult/guard/history/runs/<run-id>.json`. It records stage durations, the outcome, and the
-policy gate that decided the result. It contains no source code or external telemetry. These
-manifests make a failed run explainable without turning Guard into a production tracing system.
+policy gate that decided the result. It also records the effective policy revision and fingerprint;
+when a base ref was supplied, it records the ref and whether the working-tree policy differed.
+When an approved policy decision caused the current policy, the manifest also retains its decision
+ID, making the relationship traversable from approval to verification. The `governance` command
+audits this metadata and reports missing or overlapping declared actors. It contains no source code
+or external telemetry. These manifests make a failed run explainable without turning Guard into a
+production tracing system or an identity/signature ledger.
 
 ## Security and data handling
 

package/dist/adapters/agents/agent-integration.d.ts

@@ -4,6 +4,9 @@ export interface GuardAgentInstallResult {
     path: string;
     action: 'created' | 'updated';
 }
+export declare class GuardAgentInstallError extends Error {
+    constructor(message: string);
+}
 export declare function installGuardAgentInstructions(root: string, target: GuardAgentTarget): GuardAgentInstallResult;
 export declare function installGuardAgentTargets(root: string, targetsToInstall: GuardAgentTarget[]): GuardAgentInstallResult[];
 export declare const guardAgentTargets: GuardAgentTarget[];

package/dist/adapters/agents/agent-integration.js

@@ -1,18 +1,24 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+export class GuardAgentInstallError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GuardAgentInstallError';
+    }
+}
 const START_MARKER = '<!-- codapult-guard:start -->';
 const END_MARKER = '<!-- codapult-guard:end -->';
 const instruction = `${START_MARKER}
 ## Codapult Guard completion gate
 
-After completing a coding task, read the project Guard context, review the requirement and diff,
-then run Guard verification. Use the host's Guard MCP tools when available:
+After completing a coding task, use the host's Guard MCP tools when available:
 
-1. Call \`codapult_guard_context\`.
-2. Call \`codapult_guard_review\` with the requirement and changed diff.
-3. Call \`codapult_guard_verify\`.
-4. If an error is reported, fix it and repeat steps 2–3 up to \`completionGate.maxIterations\`.
-5. Report warnings and unresolved requirements; never hide them or activate proposals silently.
+1. Call \`codapult_guard_next_action\` and follow its bounded next step.
+2. Normally call \`codapult_guard_context\`.
+3. Call \`codapult_guard_review\` with the requirement and changed diff.
+4. Call \`codapult_guard_verify\`.
+5. If an error is reported, fix it and repeat steps 3–4 up to \`completionGate.maxIterations\`.
+6. Report warnings and unresolved requirements; never hide them or activate proposals silently.
 
 Guard does not edit source files or invoke an LLM. The host agent owns the repair loop. CI remains
 the independent final gate.
@@ -31,8 +37,23 @@ const targets = {
 function renderContent(target) {
     return `${targets[target].prefix ?? ''}${instruction}\n`;
 }
+function assertNoSymlinkPath(root, relativePath) {
+    let current = resolve(root);
+    const rootStats = lstatSync(current, { throwIfNoEntry: false });
+    if (rootStats?.isSymbolicLink()) {
+        throw new GuardAgentInstallError(`Refusing to update ${relativePath}: project root is a symbolic link.`);
+    }
+    for (const segment of relativePath.split('/')) {
+        current = resolve(current, segment);
+        const stats = lstatSync(current, { throwIfNoEntry: false });
+        if (stats?.isSymbolicLink()) {
+            throw new GuardAgentInstallError(`Refusing to update ${relativePath}: ${current} is a symbolic link.`);
+        }
+    }
+}
 export function installGuardAgentInstructions(root, target) {
     const relativePath = targets[target].path;
+    assertNoSymlinkPath(root, relativePath);
     const path = resolve(root, relativePath);
     const nextBlock = instruction;
     const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';

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

@@ -17,6 +17,11 @@ interface GuardVerifyOptions extends GuardOutputOptions {
     tools?: GuardToolMode | undefined;
     strict?: boolean | undefined;
     projectChecks?: boolean | undefined;
+    policyBase?: string | undefined;
+    failOnPolicyChange?: boolean | undefined;
+}
+interface GuardGovernanceOptions extends GuardOutputOptions {
+    strict?: boolean | undefined;
 }
 interface GuardCheckOptions extends GuardOutputOptions {
     changed?: boolean | undefined;
@@ -49,6 +54,7 @@ export declare function guardDoctorCommand(options?: GuardOutputOptions & {
 }): void;
 export declare function guardHistoryCommand(): void;
 export declare function guardRunsCommand(options?: GuardOutputOptions): void;
+export declare function guardGovernanceCommand(options?: GuardGovernanceOptions): void;
 export declare function guardImpactCommand(files: string[], options?: GuardOutputOptions): void;
 export declare function guardHistoryDiffCommand(from: string, to: string, options?: GuardOutputOptions): void;
 export declare function guardVerifyCommand(options?: GuardVerifyOptions): void;

package/dist/cli/commands/guard.js

@@ -11,6 +11,7 @@ import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { listGuardRuns, summarizeGuardRuns } from '../../core/history/runs.js';
+import { auditGuardGovernance } from '../../core/audit/governance.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -221,6 +222,32 @@ export function guardRunsCommand(options = {}) {
         info(`${run.runId}: ${run.outcome}, gate=${run.gate}, ${run.durationMs} ms`);
     }
 }
+export function guardGovernanceCommand(options = {}) {
+    const root = getRoot();
+    let result;
+    try {
+        result = auditGuardGovernance(root);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        heading('Codapult Guard Governance');
+        info(`Approvals: ${result.approvals.approved} approved, ${result.approvals.actors.length} declared actor(s), ${result.approvals.missingActors} missing actor(s).`);
+        info(`Declared actor/proposal-author overlap: ${result.approvals.actorAuthorOverlap.length}.`);
+        info(`Policy-linked approvals: ${result.reachability.approvedLinkedToRun}/${result.reachability.approvedWithPolicyFingerprint} linked to a retained verification run.`);
+        for (const warning of result.warnings)
+            warn(warning);
+        if (result.warnings.length === 0)
+            success('No governance completeness warnings.');
+    }
+    process.exitCode = options.strict && result.warnings.length > 0 ? 1 : 0;
+}
 export function guardImpactCommand(files, options = {}) {
     const root = getRoot();
     if (files.length === 0) {
@@ -283,6 +310,8 @@ export function guardVerifyCommand(options = {}) {
         tools: options.tools,
         strict: options.strict,
         projectChecks: options.projectChecks,
+        policyBase: options.policyBase,
+        failOnPolicyChange: options.failOnPolicyChange,
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -295,6 +324,12 @@ export function guardVerifyCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
+    if (result.policy?.source === 'git-ref') {
+        dim(`policy: ${result.policy.ref ?? 'Git ref'} (${result.policy.fingerprint})`);
+        if (result.policyChanged) {
+            warn('The working-tree policy differs from the base policy; the base policy was used.');
+        }
+    }
     for (const [name, check] of Object.entries(result.checks)) {
         if (check.status === 'passed')
             success(`${name}: passed`);

package/dist/cli/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, guardWaiverCommand, } from './commands/guard.js';
+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 { config } from '../core/config.js';
 import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, GuardWaiverError, } from '../core/guard.js';
+import { GuardAgentInstallError } from '../adapters/agents/agent-integration.js';
 import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
@@ -23,6 +24,7 @@ guard.command('install-agent [target]').option('--json').action(guardInstallAgen
 guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('runs').option('--json').action(guardRunsCommand);
+guard.command('governance').option('--json').option('--strict').action(guardGovernanceCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard
@@ -40,6 +42,8 @@ guard
     .option('--no-project-checks')
     .option('--requirement <file>')
     .option('--changed')
+    .option('--policy-base <ref>', 'read policy artifacts from this Git ref')
+    .option('--fail-on-policy-change', 'fail when the working-tree policy differs from the base ref')
     .option('--json')
     .action(guardVerifyCommand);
 guard
@@ -110,10 +114,12 @@ catch (error) {
         error instanceof GuardBaselineReasonError ||
         error instanceof GuardStateBusyError ||
         error instanceof GuardStateStaleError ||
-        error instanceof GuardWaiverError) {
+        error instanceof GuardWaiverError ||
+        error instanceof GuardAgentInstallError) {
         const isBusy = error instanceof GuardStateBusyError;
         const isStale = error instanceof GuardStateStaleError;
         const isInvalidInput = error instanceof GuardBaselineReasonError;
+        const isInstallError = error instanceof GuardAgentInstallError;
         console.error(JSON.stringify(guardErrorPayload(isBusy
             ? 'GUARD_STATE_BUSY'
             : isStale
@@ -128,7 +134,9 @@ catch (error) {
                 ? 'Re-read Guard state and retry the operation.'
                 : isInvalidInput
                     ? 'Provide a written reason for the baseline decision.'
-                    : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+                    : isInstallError
+                        ? 'Remove the symbolic link or choose a regular project path, then retry.'
+                        : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
         }), null, 2));
         process.exitCode = 1;
     }

package/dist/core/audit/governance.d.ts

@@ -0,0 +1,37 @@
+export interface GuardGovernanceAudit {
+    version: 1;
+    generatedAt: string;
+    configured: boolean;
+    policy?: {
+        revision?: number | undefined;
+        fingerprint: string;
+    } | undefined;
+    proposals: {
+        currentId?: string | undefined;
+        currentAuthor?: string | undefined;
+        decisions: number;
+        authors: string[];
+        missingAuthors: number;
+    };
+    approvals: {
+        total: number;
+        approved: number;
+        rejected: number;
+        actors: string[];
+        missingActors: number;
+        actorAuthorOverlap: string[];
+        commitAuthors: string[];
+        actorCommitAuthorOverlap: string[];
+        missingCommits: number;
+        sources: Record<string, number>;
+    };
+    reachability: {
+        approvedWithPolicyFingerprint: number;
+        approvedLinkedToRun: number;
+        approvedWithoutRun: number;
+        runsWithPolicy: number;
+        runsWithoutPolicy: number;
+    };
+    warnings: string[];
+}
+export declare function auditGuardGovernance(root: string): GuardGovernanceAudit;

package/dist/core/audit/governance.js

@@ -0,0 +1,166 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createGuardPolicySnapshot, loadBaseline, loadGuardAgentConfig, loadGuardConfig, loadGuardProposals, loadGuardWaivers, withGuardStateLock, GUARD_DIR, } from '../guard.js';
+import { GUARD_RUN_RETENTION, listGuardRuns } from '../history/runs.js';
+function commitAuthor(root, commit, cache) {
+    if (!commit || !/^[0-9a-f]{7,64}$/i.test(commit))
+        return undefined;
+    if (cache.has(commit))
+        return cache.get(commit);
+    try {
+        const value = execFileSync('git', ['show', '-s', '--format=%ae', commit], {
+            cwd: root,
+            stdio: 'pipe',
+            timeout: 5_000,
+            maxBuffer: 64 * 1024,
+        })
+            .toString()
+            .trim();
+        const author = value || undefined;
+        cache.set(commit, author);
+        return author;
+    }
+    catch {
+        cache.set(commit, undefined);
+        return undefined;
+    }
+}
+function currentProposalAuthor(proposals, decision) {
+    if (decision.proposalAuthor)
+        return decision.proposalAuthor;
+    if (decision.proposalId && decision.proposalId === proposals?.proposalId) {
+        return proposals.generatedBy;
+    }
+    return undefined;
+}
+function auditGuardGovernanceUnlocked(root) {
+    const config = loadGuardConfig(root);
+    const proposals = loadGuardProposals(root);
+    const decisions = proposals?.decisions ?? [];
+    const approved = decisions.filter((decision) => decision.decision === 'approved');
+    const authors = [
+        ...new Set(decisions
+            .map((decision) => currentProposalAuthor(proposals, decision))
+            .filter((author) => Boolean(author))),
+    ].sort();
+    const actors = [
+        ...new Set(approved
+            .map((decision) => decision.actor?.trim())
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const commitAuthorCache = new Map();
+    const enrichedApprovals = approved.map((decision) => ({
+        decision,
+        author: currentProposalAuthor(proposals, decision),
+        commitAuthor: commitAuthor(root, decision.commit, commitAuthorCache),
+    }));
+    const commitAuthors = [
+        ...new Set(enrichedApprovals
+            .map((item) => item.commitAuthor)
+            .filter((author) => Boolean(author))),
+    ].sort();
+    const actorAuthorOverlap = [
+        ...new Set(enrichedApprovals
+            .filter((item) => item.decision.actor && item.author && item.decision.actor === item.author)
+            .map((item) => item.decision.actor)
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const actorCommitAuthorOverlap = [
+        ...new Set(enrichedApprovals
+            .filter((item) => item.decision.actor && item.commitAuthor === item.decision.actor)
+            .map((item) => item.decision.actor)
+            .filter((actor) => Boolean(actor))),
+    ].sort();
+    const runs = listGuardRuns(root, GUARD_RUN_RETENTION);
+    const runDecisionBindings = new Map();
+    for (const run of runs) {
+        const fingerprint = run.policy?.fingerprint;
+        if (!fingerprint)
+            continue;
+        for (const decisionId of run.policy?.decisionIds ?? []) {
+            const fingerprints = runDecisionBindings.get(decisionId) ?? new Set();
+            fingerprints.add(fingerprint);
+            runDecisionBindings.set(decisionId, fingerprints);
+        }
+    }
+    const approvedWithPolicyFingerprint = approved.filter((decision) => decision.policyFingerprint !== undefined).length;
+    const approvedLinkedToRun = approved.filter((decision) => decision.policyFingerprint !== undefined &&
+        runDecisionBindings
+            .get(decision.decisionId ??
+            `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)
+            ?.has(decision.policyFingerprint)).length;
+    const warnings = [];
+    if (approved.some((decision) => !decision.actor)) {
+        warnings.push('Some approved decisions do not declare an approval actor.');
+    }
+    if (approved.some((decision) => !currentProposalAuthor(proposals, decision))) {
+        warnings.push('Some approved decisions do not retain a proposal author.');
+    }
+    if (actorAuthorOverlap.length > 0) {
+        warnings.push('At least one declared approval actor also authored an approved proposal.');
+    }
+    if (approved.some((decision) => !decision.policyFingerprint)) {
+        warnings.push('Some approved decisions are not bound to a resulting policy fingerprint.');
+    }
+    if (approved.some((decision) => decision.policyFingerprint === undefined ||
+        !runDecisionBindings
+            .get(decision.decisionId ??
+            `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)
+            ?.has(decision.policyFingerprint))) {
+        warnings.push('Some approved decisions have no retained verification run linked by decision ID.');
+    }
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        configured: config !== undefined,
+        ...(config
+            ? {
+                policy: (() => {
+                    const snapshot = createGuardPolicySnapshot(config, loadBaseline(root), loadGuardWaivers(root), 'working-tree', undefined, loadGuardAgentConfig(root));
+                    return {
+                        ...(snapshot.revision !== undefined ? { revision: snapshot.revision } : {}),
+                        fingerprint: snapshot.fingerprint,
+                    };
+                })(),
+            }
+            : {}),
+        proposals: {
+            ...(proposals?.proposalId ? { currentId: proposals.proposalId } : {}),
+            ...(proposals?.generatedBy ? { currentAuthor: proposals.generatedBy } : {}),
+            decisions: decisions.length,
+            authors,
+            missingAuthors: decisions.filter((decision) => !currentProposalAuthor(proposals, decision))
+                .length,
+        },
+        approvals: {
+            total: decisions.length,
+            approved: approved.length,
+            rejected: decisions.filter((decision) => decision.decision === 'rejected').length,
+            actors,
+            missingActors: approved.filter((decision) => !decision.actor).length,
+            actorAuthorOverlap,
+            commitAuthors,
+            actorCommitAuthorOverlap,
+            missingCommits: approved.filter((decision) => !decision.commit).length,
+            sources: decisions.reduce((counts, decision) => {
+                const source = decision.source ?? 'unknown';
+                counts[source] = (counts[source] ?? 0) + 1;
+                return counts;
+            }, {}),
+        },
+        reachability: {
+            approvedWithPolicyFingerprint,
+            approvedLinkedToRun,
+            approvedWithoutRun: approvedWithPolicyFingerprint - approvedLinkedToRun,
+            runsWithPolicy: runs.filter((run) => run.policy !== undefined).length,
+            runsWithoutPolicy: runs.filter((run) => run.policy === undefined).length,
+        },
+        warnings,
+    };
+}
+export function auditGuardGovernance(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return auditGuardGovernanceUnlocked(root);
+    return withGuardStateLock(root, () => auditGuardGovernanceUnlocked(root));
+}

package/dist/core/errors.d.ts

@@ -1,4 +1,4 @@
-export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_STATE_STALE' | 'GUARD_INVALID_INPUT';
+export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_STATE_STALE' | 'GUARD_POLICY_BASE_INVALID' | 'GUARD_POLICY_CHANGED' | 'GUARD_INVALID_INPUT';
 export interface GuardErrorPayload {
     status: 'error';
     outcome: 'not-configured' | 'error';

package/dist/core/guard.d.ts

@@ -106,6 +106,7 @@ export interface GuardProposalFile {
     decisions?: GuardProposalDecision[] | undefined;
 }
 export interface GuardProposalDecision {
+    decisionId?: string | undefined;
     id: string;
     type: 'rule' | 'contract';
     decision: 'approved' | 'rejected';
@@ -114,8 +115,11 @@ export interface GuardProposalDecision {
     proposalFingerprint?: string | undefined;
     revision?: number | undefined;
     source?: 'cli' | 'mcp' | 'external' | undefined;
+    proposalAuthor?: string | undefined;
     actor?: string | undefined;
     commit?: string | undefined;
+    policyFingerprint?: string | undefined;
+    policyRevision?: number | undefined;
 }
 export type GuardProposalFreshness = 'current' | 'stale' | 'unknown';
 export interface GuardAgentConfig {
@@ -233,6 +237,30 @@ export declare function isGuardContractsFile(value: unknown): value is {
 export declare function isGuardProposalFile(value: unknown): value is GuardProposalFile;
 export declare function fingerprintProjectModel(model: ProjectModel): string;
 export declare function fingerprintGuardConfig(guardConfig: GuardConfig): string;
+export interface GuardPolicySnapshot {
+    config: GuardConfig;
+    agentConfig: GuardAgentConfig;
+    baseline: Set<string>;
+    waivers: GuardWaiver[];
+    revision?: number | undefined;
+    fingerprint: string;
+    source: 'working-tree' | 'git-ref';
+    ref?: string | undefined;
+}
+/**
+ * Fingerprints the effective policy used by a verification run.
+ *
+ * The rules revision alone is not sufficient: baseline and waiver changes also
+ * affect the verdict. Keeping them in this fingerprint makes a run auditable
+ * without pretending that a numeric revision covers every policy artifact.
+ */
+export declare function fingerprintGuardPolicy(guardConfig: GuardConfig, baseline?: Set<string>, waivers?: GuardWaiver[], agentConfig?: GuardAgentConfig): string;
+export declare function createGuardPolicySnapshot(guardConfig: GuardConfig, baseline: Set<string>, waivers: GuardWaiver[], source?: GuardPolicySnapshot['source'], ref?: string, agentConfig?: GuardAgentConfig): GuardPolicySnapshot;
+/**
+ * Loads policy artifacts from a trusted Git ref instead of the checked-out
+ * working tree. This is intended for CI verification of untrusted branches.
+ */
+export declare function loadGuardPolicyAtRevision(root: string, revision: string): GuardPolicySnapshot | undefined;
 export declare function getGuardProposalFreshness(model: ProjectModel, proposals: GuardProposalFile | undefined): GuardProposalFreshness;
 export declare function loadGuardConfig(root: string): GuardConfig | undefined;
 export declare function loadGuardProposals(root: string): GuardProposalFile | undefined;

package/dist/core/guard.js

@@ -271,7 +271,9 @@ function atomicWriteFile(path, content) {
 }
 function writeGuardArtifactUnlocked(root, relativePath, value) {
     mkdirSync(resolve(root, GUARD_DIR), { recursive: true });
-    atomicWriteFile(resolve(root, relativePath), `${JSON.stringify(value, null, 2)}\n`);
+    const path = resolve(root, relativePath);
+    mkdirSync(dirname(path), { recursive: true });
+    atomicWriteFile(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 function writeGuardArtifact(root, relativePath, value) {
     withGuardStateLock(root, () => writeGuardArtifactUnlocked(root, relativePath, value));
@@ -308,16 +310,136 @@ export function isGuardProposalFile(value) {
 export function fingerprintProjectModel(model) {
     return createHash('sha256').update(JSON.stringify(model)).digest('hex');
 }
+function stableSerialize(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableSerialize(item)).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
 export function fingerprintGuardConfig(guardConfig) {
     return createHash('sha256')
-        .update(JSON.stringify({
-        rules: guardConfig.rules,
-        contracts: guardConfig.contracts ?? [],
-        budgets: guardConfig.budgets ?? [],
+        .update(stableSerialize({
+        rules: [...guardConfig.rules].sort((left, right) => left.id.localeCompare(right.id)),
+        contracts: [...(guardConfig.contracts ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
+        budgets: [...(guardConfig.budgets ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
         approval: guardConfig.approval ?? defaultGuardConfig.approval,
     }))
         .digest('hex');
 }
+/**
+ * Fingerprints the effective policy used by a verification run.
+ *
+ * The rules revision alone is not sufficient: baseline and waiver changes also
+ * affect the verdict. Keeping them in this fingerprint makes a run auditable
+ * without pretending that a numeric revision covers every policy artifact.
+ */
+export function fingerprintGuardPolicy(guardConfig, baseline = new Set(), waivers = [], agentConfig = defaultGuardAgentConfig) {
+    return createHash('sha256')
+        .update(stableSerialize({
+        config: fingerprintGuardConfig(guardConfig),
+        agentConfig,
+        baseline: [...baseline].sort(),
+        waivers: [...waivers].sort((left, right) => left.id.localeCompare(right.id)),
+    }))
+        .digest('hex');
+}
+export function createGuardPolicySnapshot(guardConfig, baseline, waivers, source = 'working-tree', ref, agentConfig = defaultGuardAgentConfig) {
+    return {
+        config: guardConfig,
+        agentConfig,
+        baseline,
+        waivers,
+        ...(typeof guardConfig.revision === 'number' ? { revision: guardConfig.revision } : {}),
+        fingerprint: fingerprintGuardPolicy(guardConfig, baseline, waivers, agentConfig),
+        source,
+        ...(ref ? { ref } : {}),
+    };
+}
+function readGitFileAtRevision(root, revision, relativePath) {
+    try {
+        return execFileSync('git', ['show', `${revision}:${relativePath}`], {
+            cwd: root,
+            stdio: 'pipe',
+            maxBuffer: 4_000_000,
+        }).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseGitJsonAtRevision(root, revision, relativePath) {
+    const text = readGitFileAtRevision(root, revision, relativePath);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new GuardConfigError(`${relativePath} at ${revision}`);
+    }
+}
+/**
+ * Loads policy artifacts from a trusted Git ref instead of the checked-out
+ * working tree. This is intended for CI verification of untrusted branches.
+ */
+export function loadGuardPolicyAtRevision(root, revision) {
+    if (!/^[\w./@-]+$/.test(revision) || revision.startsWith('-')) {
+        throw new GuardConfigError(`unsafe policy ref: ${revision}`);
+    }
+    const rulesValue = parseGitJsonAtRevision(root, revision, GUARD_RULES_FILE);
+    if (rulesValue === undefined || !isGuardConfig(rulesValue)) {
+        if (rulesValue === undefined)
+            return undefined;
+        throw new GuardConfigError(`${GUARD_RULES_FILE} at ${revision}`);
+    }
+    const contractsValue = parseGitJsonAtRevision(root, revision, GUARD_CONTRACTS_FILE);
+    if (contractsValue !== undefined && !isGuardContractsFile(contractsValue)) {
+        throw new GuardConfigError(`${GUARD_CONTRACTS_FILE} at ${revision}`);
+    }
+    const guardConfig = {
+        ...rulesValue,
+        contracts: contractsValue ? contractsValue.contracts : (rulesValue.contracts ?? []),
+        budgets: rulesValue.budgets ?? [],
+        approval: rulesValue.approval ?? defaultGuardConfig.approval,
+    };
+    const agentValue = parseGitJsonAtRevision(root, revision, GUARD_AGENT_FILE);
+    const agentConfig = agentValue === undefined
+        ? defaultGuardAgentConfig
+        : // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            isGuardAgentConfig(agentValue)
+                ? agentValue
+                : (() => {
+                    throw new GuardConfigError(`${GUARD_AGENT_FILE} at ${revision}`);
+                })();
+    const baselineValue = parseGitJsonAtRevision(root, revision, GUARD_BASELINE_FILE);
+    const baselineEntries = [];
+    if (baselineValue !== undefined) {
+        if (!Array.isArray(baselineValue)) {
+            throw new GuardConfigError(`${GUARD_BASELINE_FILE} at ${revision}`);
+        }
+        for (const item of baselineValue) {
+            if (typeof item !== 'string') {
+                throw new GuardConfigError(`${GUARD_BASELINE_FILE} at ${revision}`);
+            }
+            baselineEntries.push(item);
+        }
+    }
+    const waiversValue = parseGitJsonAtRevision(root, revision, GUARD_WAIVERS_FILE);
+    const parsedWaivers = guardWaiversFileSchema.safeParse(waiversValue ?? { version: 1, waivers: [], decisions: [] });
+    if (!parsedWaivers.success)
+        throw new GuardConfigError(`${GUARD_WAIVERS_FILE} at ${revision}`);
+    // The validator is declared with the waiver file model below the policy readers.
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    validateGuardWaiversFile(parsedWaivers.data);
+    return createGuardPolicySnapshot(guardConfig, new Set(baselineEntries), parsedWaivers.data.waivers, 'git-ref', revision, agentConfig);
+}
 export function getGuardProposalFreshness(model, proposals) {
     if (!proposals?.projectFingerprint)
         return 'unknown';
@@ -607,15 +729,24 @@ function buildGuardProposalWithDecisionsUnlocked(root, decisions, options) {
             return undefined;
         }
     })();
+    const currentRevision = readGuardConfigFilesUnlocked(root)?.revision ?? 0;
+    const policyFingerprint = options.resultingPolicy
+        ? fingerprintGuardPolicy(options.resultingPolicy, loadBaseline(root), readGuardWaiversUnlocked(root).waivers, loadGuardAgentConfig(root))
+        : undefined;
     const nextDecisions = decisions.map((decision) => ({
         ...decision,
+        decisionId: randomUUID(),
         decidedAt,
         source: options.source,
         ...(process.env.GUARD_APPROVER?.trim() ? { actor: process.env.GUARD_APPROVER.trim() } : {}),
         ...(commit ? { commit } : {}),
+        ...(proposals.generatedBy ? { proposalAuthor: proposals.generatedBy } : {}),
         ...(proposals.proposalId ? { proposalId: proposals.proposalId } : {}),
         ...(proposals.contentFingerprint ? { proposalFingerprint: proposals.contentFingerprint } : {}),
         ...(typeof proposals.revision === 'number' ? { revision: proposals.revision } : {}),
+        ...(decision.decision === 'approved' && policyFingerprint
+            ? { policyFingerprint, policyRevision: currentRevision + 1 }
+            : {}),
     }));
     return {
         ...proposals,
@@ -635,7 +766,10 @@ export function recordGuardProposalDecision(root, decisions, options = { source:
 }
 export function applyGuardProposalDecision(root, guardConfig, decisions, options) {
     withGuardStateLock(root, () => {
-        const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, options);
+        const proposals = buildGuardProposalWithDecisionsUnlocked(root, decisions, {
+            ...options,
+            resultingPolicy: guardConfig,
+        });
         writeGuardArtifactUnlocked(root, GUARD_POLICY_TRANSACTION_FILE, {
             version: 1,
             createdAt: new Date().toISOString(),
@@ -1107,6 +1241,23 @@ export function validateGuardBudgets(root, budgets = []) {
 }
 export function validateGuardPolicy(root, guardConfig) {
     const issues = [];
+    const validateUniqueIds = (items, kind) => {
+        const seen = new Set();
+        for (const item of items) {
+            if (seen.has(item.id)) {
+                issues.push({
+                    contractId: `${kind}:${item.id}`,
+                    field: 'definition',
+                    value: item.id,
+                    message: `${kind} IDs must be unique: ${item.id}`,
+                });
+            }
+            seen.add(item.id);
+        }
+    };
+    validateUniqueIds(guardConfig.rules, 'rule');
+    validateUniqueIds(guardConfig.contracts ?? [], 'contract');
+    validateUniqueIds(guardConfig.budgets ?? [], 'budget');
     for (const rule of guardConfig.rules) {
         for (const file of rule.files ?? []) {
             if (!isProjectPath(root, file)) {

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

@@ -5,6 +5,14 @@ export interface GuardRunStage {
     status: 'ok' | 'fail' | 'skipped';
     detail?: string | undefined;
 }
+export interface GuardRunPolicy {
+    revision?: number | undefined;
+    fingerprint: string;
+    source: 'working-tree' | 'git-ref';
+    ref?: string | undefined;
+    changedFromBase?: boolean | undefined;
+    decisionIds?: string[] | undefined;
+}
 export interface GuardRunManifest {
     version: 1;
     runId: string;
@@ -16,6 +24,7 @@ export interface GuardRunManifest {
     gate: string;
     stages: Record<string, GuardRunStage>;
     commit?: string | undefined;
+    policy?: GuardRunPolicy | undefined;
 }
 export interface GuardRunContext {
     runId: string;
@@ -40,4 +49,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): GuardRunManifest;
+export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy): GuardRunManifest;

package/dist/core/history/runs.js

@@ -33,7 +33,22 @@ function isGuardRunManifest(value) {
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
         manifest.stages !== null &&
-        typeof manifest.stages === 'object');
+        typeof manifest.stages === 'object' &&
+        (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 ||
+                    (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))))));
 }
 export function startGuardRun() {
     return {
@@ -122,7 +137,7 @@ export function summarizeGuardRuns(root, limit = 100) {
         ...(total > 0 ? { last: runs[0] } : {}),
     };
 }
-export function finishGuardRun(root, context, outcome, gate, command = 'verify') {
+export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy) {
     let commit;
     try {
         commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' })
@@ -143,6 +158,7 @@ export function finishGuardRun(root, context, outcome, gate, command = 'verify')
         gate,
         stages: context.stages,
         ...(commit ? { commit } : {}),
+        ...(policy ? { policy } : {}),
     };
     try {
         writeGuardRun(root, manifest);

package/dist/core/policy/schemas.d.ts

@@ -266,6 +266,7 @@ export declare const guardContractsFileSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const guardProposalDecisionSchema: z.ZodObject<{
+    decisionId: z.ZodOptional<z.ZodString>;
     id: z.ZodString;
     type: z.ZodEnum<{
         contract: "contract";
@@ -284,8 +285,11 @@ export declare const guardProposalDecisionSchema: z.ZodObject<{
         external: "external";
         mcp: "mcp";
     }>>;
+    proposalAuthor: z.ZodOptional<z.ZodString>;
     actor: z.ZodOptional<z.ZodString>;
     commit: z.ZodOptional<z.ZodString>;
+    policyFingerprint: z.ZodOptional<z.ZodString>;
+    policyRevision: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const guardProposalSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -357,6 +361,7 @@ export declare const guardProposalSchema: z.ZodObject<{
     }, z.core.$strip>>;
     questions: z.ZodArray<z.ZodString>;
     decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        decisionId: z.ZodOptional<z.ZodString>;
         id: z.ZodString;
         type: z.ZodEnum<{
             contract: "contract";
@@ -375,8 +380,11 @@ export declare const guardProposalSchema: z.ZodObject<{
             external: "external";
             mcp: "mcp";
         }>>;
+        proposalAuthor: z.ZodOptional<z.ZodString>;
         actor: z.ZodOptional<z.ZodString>;
         commit: z.ZodOptional<z.ZodString>;
+        policyFingerprint: z.ZodOptional<z.ZodString>;
+        policyRevision: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const guardAgentConfigSchema: z.ZodObject<{

package/dist/core/policy/schemas.js

@@ -95,6 +95,7 @@ export const guardContractsFileSchema = z.object({
     contracts: z.array(guardContractSchema),
 });
 export const guardProposalDecisionSchema = z.object({
+    decisionId: z.string().trim().min(1).optional(),
     id: z.string().trim().min(1),
     type: z.enum(['rule', 'contract']),
     decision: z.enum(['approved', 'rejected']),
@@ -103,8 +104,11 @@ export const guardProposalDecisionSchema = z.object({
     proposalFingerprint: z.string().optional(),
     revision: z.number().optional(),
     source: z.enum(['cli', 'mcp', 'external']).optional(),
+    proposalAuthor: z.string().trim().min(1).optional(),
     actor: z.string().optional(),
     commit: z.string().optional(),
+    policyFingerprint: z.string().trim().min(1).optional(),
+    policyRevision: z.number().int().nonnegative().optional(),
 });
 export const guardProposalSchema = z.object({
     version: z.literal(1),

package/dist/core/verification/verify.d.ts

@@ -3,7 +3,7 @@ import type { ProjectCheck } from '../model/types.js';
 import { type GuardAdapter, type ProjectCheckResults, type ProjectRuntimeDiagnostics } from '../../adapters/project-checks.js';
 import { type GuardToolMode, type GuardContractIssue, type GuardReport } from '../guard.js';
 import { type GuardImpactAnalysis } from '../analysis/impact.js';
-import { type GuardRunManifest } from '../history/runs.js';
+import { type GuardRunManifest, type GuardRunPolicy } from '../history/runs.js';
 export type GuardVerificationCheck = ProjectCheck;
 export interface GuardVerificationOptions {
     checks?: GuardVerificationCheck[] | undefined;
@@ -13,11 +13,13 @@ export interface GuardVerificationOptions {
     tools?: GuardToolMode | undefined;
     strict?: boolean | undefined;
     projectChecks?: boolean | undefined;
+    policyBase?: string | undefined;
+    failOnPolicyChange?: boolean | undefined;
 }
 export interface GuardVerificationResult {
     status: 'ok' | 'fail' | 'not-configured';
     outcome: 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
-    errorCode?: 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | undefined;
+    errorCode?: 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_POLICY_BASE_INVALID' | 'GUARD_POLICY_CHANGED' | undefined;
     recoverable?: boolean | undefined;
     tools?: GuardToolMode | undefined;
     checks: ProjectCheckResults;
@@ -34,5 +36,7 @@ export interface GuardVerificationResult {
         message: string;
     };
     run: GuardRunManifest;
+    policy?: GuardRunPolicy | undefined;
+    policyChanged?: boolean | undefined;
 }
 export declare function runGuardVerification(root: string, options?: GuardVerificationOptions): GuardVerificationResult;

package/dist/core/verification/verify.js

@@ -1,9 +1,19 @@
 import {} from '../../adapters/command.js';
 import { runProjectAdapters, runProjectChecks, runWorkspaceProjectChecks, inspectProjectRuntime, } from '../../adapters/project-checks.js';
-import { loadBaseline, loadGuardAgentConfig, loadGuardConfig, scanGuard, classifyGuardOutcome, validateGuardPolicy, } from '../guard.js';
+import { loadBaseline, loadGuardPolicyAtRevision, createGuardPolicySnapshot, loadGuardWaivers, loadGuardAgentConfig, loadGuardConfig, loadGuardProposals, 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';
+function buildRunPolicy(snapshot, base, changedFromBase, decisionIds = []) {
+    return {
+        ...(snapshot.revision !== undefined ? { revision: snapshot.revision } : {}),
+        fingerprint: snapshot.fingerprint,
+        source: snapshot.source,
+        ...(base ? { ref: base } : {}),
+        ...(base ? { changedFromBase } : {}),
+        ...(decisionIds.length > 0 ? { decisionIds } : {}),
+    };
+}
 export function runGuardVerification(root, options = {}) {
     const runContext = startGuardRun();
     const requirement = {
@@ -16,6 +26,23 @@ export function runGuardVerification(root, options = {}) {
     const runtimeStartedAt = Date.now();
     const runtime = inspectProjectRuntime(root);
     recordGuardRunStage(runContext, 'runtime', 'ok', runtimeStartedAt);
+    if (options.failOnPolicyChange && !options.policyBase) {
+        const run = finishGuardRun(root, runContext, 'fail', 'policy-base');
+        return {
+            status: 'fail',
+            outcome: 'fail',
+            errorCode: 'GUARD_POLICY_BASE_INVALID',
+            recoverable: true,
+            checks: {},
+            workspaceChecks: {},
+            adapters: {},
+            runtime,
+            configError: '`failOnPolicyChange` requires `policyBase`.',
+            contractIssues: [],
+            requirement,
+            run,
+        };
+    }
     let config;
     try {
         config = loadGuardConfig(root);
@@ -53,7 +80,82 @@ export function runGuardVerification(root, options = {}) {
             run,
         };
     }
-    const agentConfig = loadGuardAgentConfig(root);
+    let policySnapshot;
+    let workingTreeSnapshot;
+    let policyChanged;
+    let policyDecisionIds = [];
+    try {
+        workingTreeSnapshot = createGuardPolicySnapshot(config, loadBaseline(root), loadGuardWaivers(root), 'working-tree', undefined, loadGuardAgentConfig(root));
+        const baseSnapshot = options.policyBase
+            ? loadGuardPolicyAtRevision(root, options.policyBase)
+            : undefined;
+        if (options.policyBase && !baseSnapshot) {
+            const run = finishGuardRun(root, runContext, 'fail', 'policy-base');
+            return {
+                status: 'fail',
+                outcome: 'fail',
+                errorCode: 'GUARD_POLICY_BASE_INVALID',
+                recoverable: true,
+                checks: {},
+                workspaceChecks: {},
+                adapters: {},
+                runtime,
+                configError: `Guard policy was not found at Git ref: ${options.policyBase}`,
+                contractIssues: [],
+                requirement,
+                run,
+            };
+        }
+        policySnapshot = baseSnapshot ?? workingTreeSnapshot;
+        policyChanged =
+            baseSnapshot !== undefined && baseSnapshot.fingerprint !== workingTreeSnapshot.fingerprint;
+        if (policySnapshot.source === 'working-tree') {
+            policyDecisionIds = (loadGuardProposals(root)?.decisions ?? [])
+                .filter((decision) => decision.policyFingerprint === policySnapshot.fingerprint)
+                .map((decision) => decision.decisionId ??
+                `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)
+                .sort();
+        }
+        if (options.failOnPolicyChange && policyChanged) {
+            const policy = buildRunPolicy(policySnapshot, options.policyBase, policyChanged, policyDecisionIds);
+            const run = finishGuardRun(root, runContext, 'fail', 'policy-change', 'verify', policy);
+            return {
+                status: 'fail',
+                outcome: 'fail',
+                errorCode: 'GUARD_POLICY_CHANGED',
+                recoverable: true,
+                checks: {},
+                workspaceChecks: {},
+                adapters: {},
+                runtime,
+                configError: 'Guard policy changed relative to the supplied Git base ref.',
+                contractIssues: [],
+                requirement,
+                run,
+                policy,
+                policyChanged,
+            };
+        }
+    }
+    catch (error) {
+        const run = finishGuardRun(root, runContext, 'fail', 'policy-base');
+        return {
+            status: 'fail',
+            outcome: 'fail',
+            errorCode: 'GUARD_POLICY_BASE_INVALID',
+            recoverable: true,
+            checks: {},
+            workspaceChecks: {},
+            adapters: {},
+            runtime,
+            configError: error instanceof Error ? error.message : String(error),
+            contractIssues: [],
+            requirement,
+            run,
+        };
+    }
+    const policy = buildRunPolicy(policySnapshot, options.policyBase, policyChanged, policyDecisionIds);
+    const agentConfig = policySnapshot.agentConfig;
     const projectChecks = options.projectChecks ?? agentConfig.completionGate.projectChecks;
     const checks = projectChecks ? (options.checks ?? agentConfig.completionGate.checks) : [];
     const checksStartedAt = Date.now();
@@ -63,7 +165,7 @@ export function runGuardVerification(root, options = {}) {
     const workspaceModel = discoverProject(root);
     const impact = analyzeProjectImpact(workspaceModel, options.changedOnly === false
         ? workspaceModel.modules.map((module) => module.path)
-        : workspaceModel.git.changedFiles, config.contracts ?? []);
+        : workspaceModel.git.changedFiles, policySnapshot.config.contracts ?? []);
     const workspaceChecks = runWorkspaceProjectChecks(root, workspaceModel.project.workspacePackages ?? [], checks, {
         timeout: options.timeout,
         rootResults: results,
@@ -80,12 +182,13 @@ export function runGuardVerification(root, options = {}) {
         });
     recordGuardRunStage(runContext, 'adapters', toolMode === 'off' ? 'skipped' : 'ok', adaptersStartedAt);
     const architectureStartedAt = Date.now();
-    const architecture = scanGuard(root, config, {
+    const architecture = scanGuard(root, policySnapshot.config, {
         changedOnly: options.changedOnly,
-        baseline: loadBaseline(root),
+        baseline: policySnapshot.baseline,
         includeArchitectureInsights: true,
+        waivers: policySnapshot.waivers,
     });
-    const contractIssues = validateGuardPolicy(root, config);
+    const contractIssues = validateGuardPolicy(root, policySnapshot.config);
     recordGuardRunStage(runContext, 'architecture-policy', 'ok', architectureStartedAt);
     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'));
@@ -133,7 +236,7 @@ export function runGuardVerification(root, options = {}) {
                         : !runtime.compatible && projectChecks
                             ? 'runtime'
                             : 'none';
-    const run = finishGuardRun(root, runContext, outcome, gate);
+    const run = finishGuardRun(root, runContext, outcome, gate, 'verify', policy);
     return {
         status: failed ? 'fail' : 'ok',
         outcome,
@@ -147,5 +250,7 @@ export function runGuardVerification(root, options = {}) {
         contractIssues,
         requirement,
         run,
+        policy,
+        ...(policy.changedFromBase !== undefined ? { policyChanged: policy.changedFromBase } : {}),
     };
 }

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
 export * from './core/analysis/impact.js';
+export * from './core/audit/governance.js';
 export * from './adapters/project-checks.js';

package/dist/index.js

@@ -10,4 +10,5 @@ export * from './core/output/sarif.js';
 export * from './core/analysis/doctor.js';
 export * from './core/analysis/packs.js';
 export * from './core/analysis/impact.js';
+export * from './core/audit/governance.js';
 export * from './adapters/project-checks.js';

package/dist/mcp/tools/guard.js

@@ -4,6 +4,7 @@ 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';
 const rootSchema = z.string().trim().min(1).optional().describe('Project path or workspace root.');
 function getGuardRoot(root) {
     return root ? findGuardRoot(root) : findGuardRoot();
@@ -450,9 +451,19 @@ export function registerGuardTools(server) {
                 .boolean()
                 .optional()
                 .describe('Override completionGate.projectChecks for this invocation.'),
+            policy_base: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Git ref whose Guard policy should be used for this verification.'),
+            fail_on_policy_change: z
+                .boolean()
+                .optional()
+                .describe('Fail when the checked-out policy differs from policy_base.'),
             iteration: z.number().int().positive().default(1),
         },
-    }, ({ root: requestedRoot, checks, changed_only, requirement, tools, strict, project_checks, iteration, }) => {
+    }, ({ root: requestedRoot, checks, changed_only, requirement, tools, strict, project_checks, policy_base, fail_on_policy_change, iteration, }) => {
         const root = getGuardRoot(requestedRoot);
         const agent = loadAgentSafely(root);
         if ('error' in agent)
@@ -464,6 +475,8 @@ export function registerGuardTools(server) {
             tools,
             strict,
             projectChecks: project_checks,
+            policyBase: policy_base,
+            failOnPolicyChange: fail_on_policy_change,
         });
         const completionGate = agent.config.completionGate;
         return jsonToolResult({
@@ -475,6 +488,18 @@ export function registerGuardTools(server) {
             },
         }, result.status === 'fail');
     });
+    server.registerTool('codapult_guard_governance', {
+        title: 'Guard Governance Audit',
+        description: 'Audit declared proposal and approval provenance, policy bindings, and retained verification reachability. This reports metadata; it does not prove identity or signatures.',
+        inputSchema: { root: rootSchema },
+    }, ({ root: requestedRoot }) => {
+        try {
+            return jsonToolResult(auditGuardGovernance(getGuardRoot(requestedRoot)));
+        }
+        catch (error) {
+            return jsonToolResult({ status: 'fail', message: error instanceof Error ? error.message : String(error) }, true);
+        }
+    });
     server.registerTool('codapult_guard_audit', {
         title: 'Guard Audit',
         description: 'Run a full Guard audit, ignoring baseline suppression and validating contracts.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.7.0",
+  "version": "0.8.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",