@codapult/guard 0.6.2 → 0.8.0

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

@@ -1,4 +1,51 @@
 import { z } from 'zod';
+export declare const guardWaiverSchema: z.ZodObject<{
+    id: z.ZodString;
+    fingerprint: z.ZodString;
+    ruleId: z.ZodString;
+    owner: z.ZodString;
+    reason: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    issue: z.ZodOptional<z.ZodURL>;
+    approvedBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const guardWaiverDecisionSchema: z.ZodObject<{
+    at: z.ZodISODateTime;
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+        renew: "renew";
+    }>;
+    waiverId: z.ZodString;
+    reason: z.ZodString;
+    actor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const guardWaiversFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    waivers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        fingerprint: z.ZodString;
+        ruleId: z.ZodString;
+        owner: z.ZodString;
+        reason: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        expiresAt: z.ZodISODateTime;
+        issue: z.ZodOptional<z.ZodURL>;
+        approvedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    decisions: z.ZodArray<z.ZodObject<{
+        at: z.ZodISODateTime;
+        action: z.ZodEnum<{
+            add: "add";
+            remove: "remove";
+            renew: "renew";
+        }>;
+        waiverId: z.ZodString;
+        reason: z.ZodString;
+        actor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const guardBudgetSchema: z.ZodObject<{
     id: z.ZodString;
     description: z.ZodString;
@@ -175,6 +222,10 @@ export declare const guardConfigSchema: z.ZodObject<{
         allowMcpApproval: z.ZodBoolean;
         requireDistinctActor: z.ZodBoolean;
     }, z.core.$strip>>;
+    waiverPolicy: z.ZodOptional<z.ZodObject<{
+        warningDays: z.ZodNumber;
+        maxDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const guardContractsFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -215,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";
@@ -233,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>;
@@ -306,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";
@@ -324,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

@@ -1,6 +1,29 @@
 import { z } from 'zod';
 const severity = z.enum(['error', 'warning', 'info']);
 const status = z.enum(['active', 'proposed']);
+export const guardWaiverSchema = z.object({
+    id: z.string().trim().min(1),
+    fingerprint: z.string().trim().min(1),
+    ruleId: z.string().trim().min(1),
+    owner: z.string().trim().min(1),
+    reason: z.string().trim().min(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    expiresAt: z.iso.datetime({ offset: true }),
+    issue: z.url().optional(),
+    approvedBy: z.string().trim().min(1).optional(),
+});
+export const guardWaiverDecisionSchema = z.object({
+    at: z.iso.datetime({ offset: true }),
+    action: z.enum(['add', 'renew', 'remove']),
+    waiverId: z.string().trim().min(1),
+    reason: z.string().trim().min(1),
+    actor: z.string().trim().min(1).optional(),
+});
+export const guardWaiversFileSchema = z.object({
+    version: z.literal(1),
+    waivers: z.array(guardWaiverSchema),
+    decisions: z.array(guardWaiverDecisionSchema),
+});
 export const guardBudgetSchema = z.object({
     id: z.string().trim().min(1),
     description: z.string().trim().min(1),
@@ -56,12 +79,23 @@ export const guardConfigSchema = z.object({
         requireDistinctActor: z.boolean(),
     })
         .optional(),
+    waiverPolicy: z
+        .object({
+        warningDays: z.number().int().min(0).max(3650),
+        maxDays: z.number().int().positive().max(3650).optional(),
+    })
+        .refine((policy) => policy.maxDays === undefined || policy.maxDays >= policy.warningDays, {
+        message: 'waiverPolicy.maxDays must be greater than or equal to warningDays',
+        path: ['maxDays'],
+    })
+        .optional(),
 });
 export const guardContractsFileSchema = z.object({
     version: z.literal(1),
     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']),
@@ -70,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'));
@@ -93,7 +196,8 @@ export function runGuardVerification(root, options = {}) {
     const missingRequiredTools = options.strict &&
         [...Object.values(results), ...Object.values(adapters)].some((result) => result.status === 'not-configured');
     const architectureFailed = architecture.findings.some((finding) => finding.severity === 'error');
-    const architectureWarnings = architecture.findings.some((finding) => finding.severity === 'warning');
+    const architectureWarnings = architecture.findings.some((finding) => finding.severity === 'warning') ||
+        (architecture.waiverWarnings ?? []).length > 0;
     const failed = (projectChecks && !runtime.compatible) ||
         commandFailed ||
         workspaceCommandFailed ||
@@ -132,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,
@@ -146,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/resources.js

@@ -1,4 +1,4 @@
-import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { buildArchitectureMemory, buildConventionsMemory, discoverProject, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadGuardAgentConfig, loadGuardArtifact, loadGuardConfig, loadGuardProposals, loadGuardWaivers, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
 import { guardErrorPayload } from '../core/errors.js';
 import { DiscoveryStaleError } from '../core/discovery/discovery.js';
 import { listGuardRuns, summarizeGuardRuns } from '../core/history/runs.js';
@@ -97,6 +97,23 @@ export function registerGuardResources(server) {
             return resourceError('codapult://guard/architecture', error);
         }
     });
+    server.registerResource('codapult_guard_waivers', 'codapult://guard/waivers', {
+        title: 'Guard Waivers',
+        description: 'Active and expired time-bounded exceptions to Guard findings.',
+        mimeType: 'application/json',
+    }, () => {
+        const root = findGuardRoot();
+        try {
+            return jsonResource('codapult://guard/waivers', {
+                version: 1,
+                root,
+                waivers: loadGuardWaivers(root),
+            });
+        }
+        catch (error) {
+            return resourceError('codapult://guard/waivers', error);
+        }
+    });
     server.registerResource('codapult_guard_proposals', 'codapult://guard/proposals', {
         title: 'Architecture Guard Proposals',
         description: 'Evidence-backed rules and contracts awaiting review.',

package/dist/mcp/tools/guard.js

@@ -1,8 +1,10 @@
-import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, GuardStateBusyError, GuardStateStaleError, applyGuardProposalDecision, validateGuardProposalApproval, writeProjectState, scanGuard, validateGuardPolicy, classifyGuardOutcome, } from '../../core/guard.js';
+import { randomUUID } from 'node:crypto';
+import { buildArchitectureMemory, buildConventionsMemory, buildGeneratedGuardConfig, buildGuardProposals, buildGuardReviewPacket, discoverProject, discoverProjectWithMetrics, fingerprintProjectModel, findGuardRoot, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, loadBaseline, loadGuardArtifact, loadGuardConfig, loadGuardAgentConfig, loadGuardProposals, loadGuardWaivers, getPendingGuardProposals, getGuardProposalFreshness, loadProjectModel, writeGuardProposals, initializeGuard, GuardAlreadyInitializedError, GuardStateBusyError, GuardStateStaleError, applyGuardProposalDecision, validateGuardProposalApproval, writeProjectState, scanGuard, updateGuardWaivers, validateGuardPolicy, classifyGuardOutcome, } from '../../core/guard.js';
 import { 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();
@@ -13,6 +15,12 @@ function jsonToolResult(value, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+function waiverToolError(error) {
+    return jsonToolResult({
+        status: 'invalid',
+        message: error instanceof Error ? error.message : 'Waiver update failed.',
+    }, true);
+}
 function notConfiguredToolResult() {
     return jsonToolResult({
         status: 'error',
@@ -443,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)
@@ -457,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({
@@ -468,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.',
@@ -563,6 +595,110 @@ export function registerGuardTools(server) {
             ...report,
         }, errors > 0 || contractIssues.length > 0);
     });
+    server.registerTool('codapult_guard_waivers', {
+        title: 'Guard Waivers',
+        description: 'List and manage time-bounded, project-approved exceptions to active Guard findings.',
+        inputSchema: {
+            root: rootSchema,
+            action: z.enum(['list', 'add', 'remove', 'renew']).default('list'),
+            fingerprint: z.string().trim().min(1).optional(),
+            id: z.string().trim().min(1).optional(),
+            owner: z.string().trim().min(1).optional(),
+            reason: z.string().trim().min(1).max(2000).optional(),
+            expires_at: z.iso.datetime({ offset: true }).optional(),
+            issue: z.url().optional(),
+            confirm: z.boolean().default(false),
+        },
+    }, ({ root: requestedRoot, action, fingerprint, id, owner, reason, expires_at, issue, confirm, }) => {
+        const root = getGuardRoot(requestedRoot);
+        let waivers;
+        try {
+            waivers = loadGuardWaivers(root);
+        }
+        catch (error) {
+            return waiverToolError(error);
+        }
+        if (action === 'list')
+            return jsonToolResult({ status: 'ok', waivers });
+        const loaded = loadConfigSafely(root);
+        if (loaded.error)
+            return loaded.error;
+        if (loaded.config?.approval?.mode === 'protected' &&
+            !loaded.config.approval.allowMcpApproval) {
+            return jsonToolResult({
+                status: 'approval-required',
+                message: 'Protected Guard policy requires waiver approval outside the MCP agent surface.',
+                action,
+            }, true);
+        }
+        if (loaded.config?.approval?.mode === 'protected' &&
+            loaded.config.approval.requireDistinctActor &&
+            !process.env.GUARD_APPROVER?.trim()) {
+            return jsonToolResult({
+                status: 'approval-required',
+                message: 'Protected Guard policy requires GUARD_APPROVER for waiver changes.',
+                action,
+            }, true);
+        }
+        if (!confirm)
+            return jsonToolResult({ status: 'needs-confirmation', action });
+        if (!reason)
+            return jsonToolResult({ status: 'invalid', message: 'reason is required.' }, true);
+        if (action === 'add') {
+            if (!fingerprint || !owner || !expires_at) {
+                return jsonToolResult({ status: 'invalid', message: 'fingerprint, owner, and expires_at are required.' }, true);
+            }
+            const finding = scanGuard(root, loaded.config ?? { version: 1, rules: [] }, {
+                waivers: [],
+                includeArchitectureInsights: true,
+            }).findings.find((candidate) => candidate.fingerprint === fingerprint);
+            if (!finding)
+                return jsonToolResult({ status: 'not-found', fingerprint }, true);
+            const waiver = {
+                id: `waiver-${randomUUID()}`,
+                fingerprint,
+                ruleId: finding.ruleId,
+                owner,
+                reason,
+                createdAt: new Date().toISOString(),
+                expiresAt: expires_at,
+                ...(issue ? { issue } : {}),
+                ...(process.env.GUARD_APPROVER?.trim()
+                    ? { approvedBy: process.env.GUARD_APPROVER.trim() }
+                    : {}),
+            };
+            try {
+                updateGuardWaivers(root, {
+                    action,
+                    waiverId: waiver.id,
+                    waiver,
+                    reason,
+                    actor: process.env.GUARD_APPROVER,
+                    maxLifetimeDays: loaded.config?.waiverPolicy?.maxDays,
+                });
+            }
+            catch (error) {
+                return waiverToolError(error);
+            }
+            return jsonToolResult({ status: 'ok', action, waiver });
+        }
+        if (!id)
+            return jsonToolResult({ status: 'invalid', message: 'id is required.' }, true);
+        try {
+            updateGuardWaivers(root, {
+                action,
+                waiverId: id,
+                ...(expires_at ? { expiresAt: expires_at } : {}),
+                reason,
+                actor: process.env.GUARD_APPROVER,
+                maxLifetimeDays: loaded.config?.waiverPolicy?.maxDays,
+            });
+        }
+        catch (error) {
+            return waiverToolError(error);
+        }
+        return jsonToolResult({ status: 'ok', action, id });
+    });
     server.registerTool('codapult_guard_impact', {
         title: 'Guard Impact Analysis',
         description: 'Explain the project impact of one or more changed files using the discovered dependency graph, routes, capabilities, and contracts.',

package/package.json

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