@codapult/guard 0.7.0 → 0.8.1

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';
@@ -475,6 +597,25 @@ export function loadGuardWaivers(root) {
         return readGuardWaiversUnlocked(root).waivers;
     return withGuardStateLock(root, () => readGuardWaiversUnlocked(root).waivers);
 }
+function readGuardWorkingTreePolicyUnlocked(root) {
+    recoverGuardPolicyTransaction(root);
+    const guardConfig = readGuardConfigFilesUnlocked(root);
+    if (!guardConfig)
+        return undefined;
+    const baseline = loadBaseline(root);
+    const waivers = readGuardWaiversUnlocked(root).waivers;
+    const agentConfig = loadGuardAgentConfig(root);
+    return {
+        config: guardConfig,
+        snapshot: createGuardPolicySnapshot(guardConfig, baseline, waivers, 'working-tree', undefined, agentConfig),
+        proposals: loadGuardProposalsUnlocked(root),
+    };
+}
+export function loadGuardWorkingTreePolicy(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return readGuardWorkingTreePolicyUnlocked(root);
+    return withGuardStateLock(root, () => readGuardWorkingTreePolicyUnlocked(root));
+}
 export function writeGuardWaivers(root) {
     withGuardStateLock(root, () => {
         const file = { version: 1, waivers: [], decisions: [] };
@@ -607,15 +748,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 +785,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 +1260,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

@@ -15,6 +15,22 @@ function isGuardRunManifest(value) {
     if (value === null || typeof value !== 'object')
         return false;
     const manifest = value;
+    const stages = manifest.stages;
+    const validStages = stages !== null &&
+        typeof stages === 'object' &&
+        !Array.isArray(stages) &&
+        Object.values(stages).every((stage) => {
+            if (stage === null || typeof stage !== 'object')
+                return false;
+            const candidate = stage;
+            return (typeof candidate.durationMs === 'number' &&
+                Number.isFinite(candidate.durationMs) &&
+                candidate.durationMs >= 0 &&
+                (candidate.status === 'ok' ||
+                    candidate.status === 'fail' ||
+                    candidate.status === 'skipped') &&
+                (candidate.detail === undefined || typeof candidate.detail === 'string'));
+        });
     return (manifest.version === 1 &&
         typeof manifest.runId === 'string' &&
         /^guard-[A-Za-z0-9-]+$/.test(manifest.runId) &&
@@ -23,6 +39,7 @@ function isGuardRunManifest(value) {
         Number.isFinite(Date.parse(manifest.startedAt)) &&
         typeof manifest.completedAt === 'string' &&
         Number.isFinite(Date.parse(manifest.completedAt)) &&
+        Date.parse(manifest.completedAt) >= Date.parse(manifest.startedAt) &&
         typeof manifest.durationMs === 'number' &&
         Number.isFinite(manifest.durationMs) &&
         manifest.durationMs >= 0 &&
@@ -32,8 +49,23 @@ function isGuardRunManifest(value) {
             manifest.outcome === 'needs-review' ||
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
-        manifest.stages !== null &&
-        typeof manifest.stages === 'object');
+        validStages &&
+        (manifest.policy === undefined ||
+            (manifest.policy !== null &&
+                typeof manifest.policy === 'object' &&
+                typeof manifest.policy.fingerprint === 'string' &&
+                manifest.policy.fingerprint.length > 0 &&
+                (manifest.policy.source === 'working-tree' || manifest.policy.source === 'git-ref') &&
+                (manifest.policy.revision === undefined ||
+                    (Number.isInteger(manifest.policy.revision) && manifest.policy.revision >= 0)) &&
+                (manifest.policy.ref === undefined || typeof manifest.policy.ref === 'string') &&
+                (manifest.policy.changedFromBase === undefined ||
+                    typeof manifest.policy.changedFromBase === 'boolean') &&
+                (manifest.policy.decisionIds === undefined ||
+                    (manifest.policy.source === 'working-tree' &&
+                        Array.isArray(manifest.policy.decisionIds) &&
+                        new Set(manifest.policy.decisionIds).size === manifest.policy.decisionIds.length &&
+                        manifest.policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0))))));
 }
 export function startGuardRun() {
     return {
@@ -122,7 +154,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 +175,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

@@ -94,7 +94,9 @@ export const guardContractsFileSchema = z.object({
     version: z.literal(1),
     contracts: z.array(guardContractSchema),
 });
-export const guardProposalDecisionSchema = z.object({
+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,10 +105,30 @@ export const guardProposalDecisionSchema = z.object({
     proposalFingerprint: z.string().optional(),
     revision: z.number().optional(),
     source: z.enum(['cli', 'mcp', 'external']).optional(),
-    actor: z.string().optional(),
-    commit: z.string().optional(),
+    proposalAuthor: z.string().trim().min(1).optional(),
+    actor: z.string().trim().min(1).optional(),
+    commit: z.string().trim().min(1).optional(),
+    policyFingerprint: z.string().trim().min(1).optional(),
+    policyRevision: z.number().int().nonnegative().optional(),
+})
+    .superRefine((decision, context) => {
+    if (decision.policyFingerprint !== undefined && decision.decision !== 'approved') {
+        context.addIssue({
+            code: 'custom',
+            message: 'policyFingerprint is only valid for approved decisions.',
+            path: ['policyFingerprint'],
+        });
+    }
+    if (decision.policyRevision !== undefined && decision.policyFingerprint === undefined) {
+        context.addIssue({
+            code: 'custom',
+            message: 'policyRevision requires policyFingerprint.',
+            path: ['policyRevision'],
+        });
+    }
 });
-export const guardProposalSchema = z.object({
+export const guardProposalSchema = z
+    .object({
     version: z.literal(1),
     generatedAt: z.string(),
     generatedBy: z.string().trim().min(1).optional(),
@@ -118,6 +140,21 @@ export const guardProposalSchema = z.object({
     contracts: z.array(guardContractSchema),
     questions: z.array(z.string()),
     decisions: z.array(guardProposalDecisionSchema).optional(),
+})
+    .superRefine((proposal, context) => {
+    const decisionIds = new Set();
+    for (const [index, decision] of (proposal.decisions ?? []).entries()) {
+        if (decision.decisionId === undefined)
+            continue;
+        if (decisionIds.has(decision.decisionId)) {
+            context.addIssue({
+                code: 'custom',
+                message: 'decisionId values must be unique.',
+                path: ['decisions', index, 'decisionId'],
+            });
+        }
+        decisionIds.add(decision.decisionId);
+    }
 });
 export const guardAgentConfigSchema = 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 { loadGuardPolicyAtRevision, loadGuardWorkingTreePolicy, scanGuard, classifyGuardOutcome, validateGuardPolicy, } from '../guard.js';
 import { analyzeProjectImpact } from '../analysis/impact.js';
 import { discoverProject } from '../discovery/discovery.js';
 import { finishGuardRun, recordGuardRunStage, startGuardRun, } from '../history/runs.js';
+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,9 +26,26 @@ export function runGuardVerification(root, options = {}) {
     const runtimeStartedAt = Date.now();
     const runtime = inspectProjectRuntime(root);
     recordGuardRunStage(runContext, 'runtime', 'ok', runtimeStartedAt);
-    let config;
+    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 workingTreeState;
     try {
-        config = loadGuardConfig(root);
+        workingTreeState = loadGuardWorkingTreePolicy(root);
     }
     catch (error) {
         const run = finishGuardRun(root, runContext, 'fail', 'configuration');
@@ -37,7 +64,7 @@ export function runGuardVerification(root, options = {}) {
             run,
         };
     }
-    if (!config) {
+    if (!workingTreeState) {
         const run = finishGuardRun(root, runContext, 'not-configured', 'configuration');
         return {
             status: 'not-configured',
@@ -53,7 +80,82 @@ export function runGuardVerification(root, options = {}) {
             run,
         };
     }
-    const agentConfig = loadGuardAgentConfig(root);
+    let policySnapshot;
+    let workingTreeSnapshot;
+    let policyChanged;
+    let policyDecisionIds = [];
+    try {
+        workingTreeSnapshot = workingTreeState.snapshot;
+        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 = (workingTreeState.proposals?.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';