@codapult/guard 0.6.1 → 0.7.0

package/README.md

@@ -231,12 +231,46 @@ Guard state is stored in `.codapult/guard/`:
 ├── proposals.json     evidence and approval history
 ├── baseline.json      accepted pre-existing findings
 ├── agent.json         AI-host completion-gate configuration
+├── waivers.json       time-bounded exceptions to active findings
 └── history/           project snapshots and local verification run manifests
 ```
 
 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.
 
+### Temporary waivers
+
+Baseline records legacy findings that existed when Guard was introduced. A waiver is different: it
+temporarily suppresses one active finding and must have an owner, reason, and expiry date.
+
+```bash
+codapult-guard waiver add <fingerprint> \
+  --owner platform-team \
+  --reason "Migration in progress" \
+  --expires 2026-12-28
+codapult-guard waiver list
+codapult-guard waiver renew <id> --expires 2027-01-31 --reason "Migration continues"
+codapult-guard waiver remove <id> --reason "Migration completed"
+```
+
+Guard warns when a waiver is within the configured warning window (14 days by default). Once it
+expires, the original finding is active again. Protected policy can forbid waiver changes through
+MCP so an agent can propose a waiver but cannot approve it itself. Waivers are intentionally
+fingerprint-specific; changing the violating code invalidates the waiver.
+
+Teams can optionally cap each new waiver or renewal with `waiverPolicy.maxDays` in `rules.json`:
+
+```json
+"waiverPolicy": { "warningDays": 14, "maxDays": 90 }
+```
+
+The cap applies to the requested grant from the current operation; it does not silently delete or
+rewrite existing waivers. Boundary findings with severity `error` fail `check`; warning findings
+and waiver-expiry reminders remain advisory.
+
+Run `codapult-guard doctor` to detect an explicitly downgraded client or package boundary. Doctor
+reports it as a warning and leaves the project policy unchanged.
+
 ### Optional scoped budgets
 
 Budgets are policy, not a universal style rule. Add them only for a named risk boundary such as a
@@ -310,11 +344,11 @@ For Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, and generic hosts, s
 
 ### MCP Registry
 
-Guard is also prepared for discovery through the official [MCP Registry](https://registry.modelcontextprotocol.io/).
-The Registry entry points to the published `@codapult/guard` npm package and its stdio MCP server;
-it does not replace npm installation or the host-specific configuration above. Registry metadata is
-validated during CI and published after npm in the release workflow. The Registry is currently in
-preview, so the canonical installation path remains npm.
+Guard is published in the official [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.codapult%2Fguard)
+under the server name `io.github.codapult/guard`. The Registry is the discovery layer for the
+published `@codapult/guard` npm package and its stdio MCP server; it does not replace npm
+installation or the host-specific configuration above. For deterministic setup, install the npm
+package directly and use the MCP configuration shown below.
 
 For workflows where the authoring agent must not approve its own policy proposals, set Guard to
 protected mode in `rules.json`:

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

@@ -26,6 +26,12 @@ interface GuardBaselineOptions extends GuardOutputOptions {
     all?: boolean | undefined;
     reason?: string | undefined;
 }
+export interface GuardWaiverOptions extends GuardOutputOptions {
+    owner?: string | undefined;
+    reason?: string | undefined;
+    expires?: string | undefined;
+    issue?: string | undefined;
+}
 interface GuardApprovalOptions {
     all?: boolean | undefined;
 }
@@ -49,6 +55,7 @@ export declare function guardVerifyCommand(options?: GuardVerifyOptions): void;
 export declare function guardCheckCommand(options?: GuardCheckOptions): void;
 export declare function guardAuditCommand(options?: GuardOutputOptions): void;
 export declare function guardBaselineCommand(action: 'list' | 'accept' | 'remove', ids?: string, options?: GuardBaselineOptions): void;
+export declare function guardWaiverCommand(action: 'list' | 'add' | 'remove' | 'renew', value?: string, options?: GuardWaiverOptions): void;
 export declare function guardRulesApproveCommand(ids?: string, options?: GuardApprovalOptions): void;
 export declare function guardPolicyExplainCommand(id: string, options?: GuardOutputOptions): void;
 export declare function guardContractsApproveCommand(ids?: string, options?: GuardApprovalOptions): void;

package/dist/cli/commands/guard.js

@@ -1,6 +1,7 @@
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
-import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardPolicy, writeProjectState, } from '../../core/guard.js';
+import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, GuardWaiverError, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, loadGuardWaivers, updateBaseline, updateGuardWaivers, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardPolicy, writeProjectState, } from '../../core/guard.js';
 import { guardErrorPayload } from '../../core/errors.js';
 import { runGuardVerification, } from '../../core/verification/verify.js';
 import { diagnoseGuard } from '../../core/analysis/doctor.js';
@@ -19,6 +20,16 @@ function renderFindings(findings) {
             dim(`  resolved: ${finding.resolvedPath}`);
     }
 }
+function renderWaiverStatus(report) {
+    for (const waiver of report.waiverWarnings ?? []) {
+        warn(`Waiver ${waiver.id} expires soon: ${waiver.expiresAt} (${waiver.owner})`);
+        dim(`  ${waiver.fingerprint}: ${waiver.reason}`);
+    }
+    for (const waiver of report.expiredWaivers ?? []) {
+        warn(`Waiver ${waiver.id} expired: ${waiver.expiresAt} (${waiver.owner})`);
+        dim(`  The original finding is active again: ${waiver.fingerprint}`);
+    }
+}
 function getRoot() {
     return findGuardRoot();
 }
@@ -174,6 +185,8 @@ export function guardDoctorCommand(options = {}) {
                 success(`${item.path}: ok`);
             else if (item.status === 'missing')
                 warn(`${item.path}: missing`);
+            else if (item.status === 'warning')
+                warn(`${item.path}: ${item.message}`);
             else
                 fail(`${item.path}: invalid`);
         }
@@ -303,6 +316,8 @@ export function guardVerifyCommand(options = {}) {
         success('architecture: no new regressions');
     else
         renderFindings(findings);
+    if (result.architecture)
+        renderWaiverStatus(result.architecture);
     for (const issue of result.contractIssues)
         warn(`[${issue.contractId}] ${issue.message}`);
     if (result.contractIssues.length > 0)
@@ -340,7 +355,8 @@ export function guardCheckCommand(options = {}) {
     });
     const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
-    const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
+    const warnings = report.findings.filter((finding) => finding.severity === 'warning').length +
+        (report.waiverWarnings ?? []).length;
     const contractFindings = contractIssues.map((issue) => ({
         ruleId: `contract:${issue.contractId}`,
         severity: 'error',
@@ -351,7 +367,19 @@ export function guardCheckCommand(options = {}) {
         fingerprint: `contract-invalid|${issue.contractId}|${issue.field}|${issue.value}`,
     }));
     if (options.sarif) {
-        console.log(JSON.stringify(guardFindingsToSarif([...report.findings, ...contractFindings]), null, 2));
+        const waiverNotices = [
+            ...(report.waiverWarnings ?? []).map((waiver) => ({
+                ruleId: 'guard-waiver-expiring',
+                level: 'warning',
+                message: `Waiver ${waiver.id} for ${waiver.ruleId} expires at ${waiver.expiresAt}. Owner: ${waiver.owner}.`,
+            })),
+            ...(report.expiredWaivers ?? []).map((waiver) => ({
+                ruleId: 'guard-waiver-expired',
+                level: 'warning',
+                message: `Waiver ${waiver.id} for ${waiver.ruleId} expired at ${waiver.expiresAt}; the finding is active again.`,
+            })),
+        ];
+        console.log(JSON.stringify(guardFindingsToSarif([...report.findings, ...contractFindings], waiverNotices), null, 2));
         process.exitCode = errors > 0 || contractIssues.length > 0 ? 1 : 0;
         return;
     }
@@ -370,6 +398,7 @@ export function guardCheckCommand(options = {}) {
     heading(`Codapult Guard${options.changed ? ' (changed files)' : ''}`);
     dim(`Scanned ${report.scannedFiles} source file(s); suppressed ${report.suppressed} baseline finding(s).`);
     renderFindings(report.findings);
+    renderWaiverStatus(report);
     for (const issue of contractIssues)
         warn(`[${issue.contractId}] ${issue.message}`);
     if (errors > 0 || contractIssues.length > 0)
@@ -406,7 +435,8 @@ export function guardAuditCommand(options = {}) {
     const report = scanGuard(root, config, { includeArchitectureInsights: true });
     const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
-    const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
+    const warnings = report.findings.filter((finding) => finding.severity === 'warning').length +
+        (report.waiverWarnings ?? []).length;
     if (options.json) {
         console.log(JSON.stringify({
             status: errors > 0 || contractIssues.length > 0 ? 'fail' : warnings > 0 ? 'warning' : 'ok',
@@ -425,6 +455,7 @@ export function guardAuditCommand(options = {}) {
     heading('Codapult Guard Audit');
     dim(`Scanned ${report.scannedFiles} source file(s); baseline is ignored for this full audit.`);
     renderFindings(report.findings);
+    renderWaiverStatus(report);
     for (const issue of contractIssues)
         warn(`[${issue.contractId}] ${issue.message}`);
     if (errors > 0)
@@ -480,6 +511,99 @@ export function guardBaselineCommand(action, ids, options = {}) {
         success(`${action === 'accept' ? 'Accepted' : 'Removed'} ${selected.length} baseline fingerprint(s).`);
     process.exitCode = 0;
 }
+export function guardWaiverCommand(action, value, options = {}) {
+    const root = getRoot();
+    const waivers = loadGuardWaivers(root);
+    const reason = options.reason?.trim();
+    if (action === 'list') {
+        const result = { count: waivers.length, waivers };
+        if (options.json)
+            console.log(JSON.stringify(result, null, 2));
+        else {
+            heading('Codapult Guard Waivers');
+            for (const waiver of waivers) {
+                const status = Date.parse(waiver.expiresAt) <= Date.now() ? 'expired' : 'active';
+                info(`${waiver.id} [${status}] ${waiver.owner} → ${waiver.expiresAt}`);
+                dim(`  ${waiver.fingerprint}: ${waiver.reason}`);
+            }
+        }
+        process.exitCode = 0;
+        return;
+    }
+    if (!reason)
+        throw new GuardWaiverError('A reason is required for waiver changes.');
+    const config = loadGuardConfig(root);
+    if (!config)
+        throw new GuardWaiverError('Guard is not initialized.');
+    if (config.approval?.mode === 'protected' &&
+        config.approval.requireDistinctActor &&
+        !process.env.GUARD_APPROVER?.trim()) {
+        throw new GuardWaiverError('Protected Guard policy requires GUARD_APPROVER for waiver changes.');
+    }
+    if (action === 'add') {
+        const owner = options.owner?.trim();
+        if (!value || !owner || !options.expires) {
+            throw new GuardWaiverError('Add requires <fingerprint>, --owner, and --expires.');
+        }
+        const expires = new Date(options.expires);
+        if (!Number.isFinite(expires.getTime()))
+            throw new GuardWaiverError('Invalid waiver expiry date.');
+        const expiresAt = expires.toISOString();
+        const finding = scanGuard(root, config, {
+            waivers: [],
+            includeArchitectureInsights: true,
+        }).findings.find((candidate) => candidate.fingerprint === value);
+        if (!finding)
+            throw new GuardWaiverError(`Finding fingerprint not found: ${value}`);
+        const waiver = {
+            id: `waiver-${randomUUID()}`,
+            fingerprint: value,
+            ruleId: finding.ruleId,
+            owner,
+            reason,
+            createdAt: new Date().toISOString(),
+            expiresAt,
+            ...(options.issue ? { issue: options.issue } : {}),
+            ...(process.env.GUARD_APPROVER?.trim()
+                ? { approvedBy: process.env.GUARD_APPROVER.trim() }
+                : {}),
+        };
+        updateGuardWaivers(root, {
+            action,
+            waiverId: waiver.id,
+            waiver,
+            reason,
+            actor: process.env.GUARD_APPROVER,
+            maxLifetimeDays: config.waiverPolicy?.maxDays,
+        });
+        if (options.json)
+            console.log(JSON.stringify({ action, waiver }, null, 2));
+        else
+            success(`Added waiver ${waiver.id}; expires ${waiver.expiresAt}.`);
+    }
+    else {
+        if (!value)
+            throw new GuardWaiverError(`Waiver id is required to ${action}.`);
+        const expires = action === 'renew' ? new Date(options.expires ?? '') : undefined;
+        if (expires && !Number.isFinite(expires.getTime())) {
+            throw new GuardWaiverError('Invalid waiver expiry date.');
+        }
+        const expiresAt = expires?.toISOString();
+        updateGuardWaivers(root, {
+            action,
+            waiverId: value,
+            ...(expiresAt ? { expiresAt } : {}),
+            reason,
+            actor: process.env.GUARD_APPROVER,
+            maxLifetimeDays: config.waiverPolicy?.maxDays,
+        });
+        if (options.json)
+            console.log(JSON.stringify({ action, waiverId: value, expiresAt }, null, 2));
+        else
+            success(`${action === 'renew' ? 'Renewed' : 'Removed'} waiver ${value}.`);
+    }
+    process.exitCode = 0;
+}
 export function guardRulesApproveCommand(ids, options = {}) {
     const root = getRoot();
     const loaded = loadConfigSafely(root);

package/dist/cli/index.js

@@ -1,9 +1,9 @@
 #!/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, } from './commands/guard.js';
+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 { config } from '../core/config.js';
-import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, GuardWaiverError, } from '../core/guard.js';
 import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
@@ -72,6 +72,30 @@ baseline
     .option('--reason <text>')
     .option('--json')
     .action((ids, options) => guardBaselineCommand('remove', ids, options));
+const waivers = guard.command('waiver');
+waivers
+    .command('list')
+    .option('--json')
+    .action((options) => guardWaiverCommand('list', undefined, options));
+waivers
+    .command('add <fingerprint>')
+    .requiredOption('--owner <owner>')
+    .requiredOption('--reason <text>')
+    .requiredOption('--expires <date>')
+    .option('--issue <url>')
+    .option('--json')
+    .action((fingerprint, options) => guardWaiverCommand('add', fingerprint, options));
+waivers
+    .command('remove <id>')
+    .requiredOption('--reason <text>')
+    .option('--json')
+    .action((id, options) => guardWaiverCommand('remove', id, options));
+waivers
+    .command('renew <id>')
+    .requiredOption('--expires <date>')
+    .requiredOption('--reason <text>')
+    .option('--json')
+    .action((id, options) => guardWaiverCommand('renew', id, options));
 program
     .command('mcp-server')
     .description('start the Guard MCP server over stdio')
@@ -85,7 +109,8 @@ catch (error) {
     if (error instanceof GuardConfigError ||
         error instanceof GuardBaselineReasonError ||
         error instanceof GuardStateBusyError ||
-        error instanceof GuardStateStaleError) {
+        error instanceof GuardStateStaleError ||
+        error instanceof GuardWaiverError) {
         const isBusy = error instanceof GuardStateBusyError;
         const isStale = error instanceof GuardStateStaleError;
         const isInvalidInput = error instanceof GuardBaselineReasonError;

package/dist/core/analysis/doctor.d.ts

@@ -1,6 +1,6 @@
 export interface GuardDoctorItem {
     path: string;
-    status: 'ok' | 'missing' | 'invalid';
+    status: 'ok' | 'missing' | 'invalid' | 'warning';
     message: string;
 }
 export interface GuardDoctorReport {

package/dist/core/analysis/doctor.js

@@ -11,6 +11,33 @@ const requiredArtifacts = [
     GUARD_CONTRACTS_FILE,
     GUARD_PROPOSALS_FILE,
 ];
+function downgradedBoundaryItems(root) {
+    let guardConfig;
+    try {
+        guardConfig = loadGuardConfig(root);
+    }
+    catch {
+        return [];
+    }
+    if (!guardConfig)
+        return [];
+    const items = guardConfig.rules
+        .filter((rule) => rule.kind === 'client-forbidden-import' && rule.severity === 'warning')
+        .map((rule) => ({
+        path: GUARD_RULES_FILE,
+        status: 'warning',
+        message: `Boundary rule '${rule.id}' is warning-only and will not block changes.`,
+    }));
+    items.push(...(guardConfig.contracts ?? [])
+        .filter((contract) => (contract.kind === 'import-boundary' || contract.kind === 'package-boundary') &&
+        contract.severity === 'warning')
+        .map((contract) => ({
+        path: GUARD_CONTRACTS_FILE,
+        status: 'warning',
+        message: `Boundary contract '${contract.id}' is warning-only and will not block changes.`,
+    })));
+    return items;
+}
 function parseJson(root, path) {
     try {
         return JSON.parse(readFileSync(resolve(root, path), 'utf8'));
@@ -64,6 +91,7 @@ export function diagnoseGuard(root) {
         }
         return { path, status: 'ok', message: 'Artifact is present and readable.' };
     });
+    items.push(...downgradedBoundaryItems(root));
     if (initialized && existsSync(resolve(root, GUARD_BASELINE_META_FILE))) {
         const metadata = parseJson(root, GUARD_BASELINE_META_FILE);
         items.push({
@@ -79,10 +107,11 @@ export function diagnoseGuard(root) {
     }
     const missing = items.filter((item) => item.status === 'missing');
     const invalid = items.filter((item) => item.status === 'invalid');
+    const warnings = items.filter((item) => item.status === 'warning');
     return {
         status: invalid.length > 0 || (initialized && missing.length > 0)
             ? 'fail'
-            : missing.length > 0
+            : missing.length > 0 || warnings.length > 0
                 ? 'warning'
                 : 'ok',
         initialized,
@@ -93,6 +122,10 @@ export function diagnoseGuard(root) {
             }
             : missing.length > 0
                 ? { recommendation: 'Run `codapult-guard analyze` or reinitialize Guard intentionally.' }
-                : {}),
+                : warnings.length > 0
+                    ? {
+                        recommendation: 'Review downgraded boundary policy before relying on Guard as a hard gate.',
+                    }
+                    : {}),
     };
 }

package/dist/core/guard.d.ts

@@ -1,8 +1,8 @@
 import { type ProjectModel } from './discovery/discovery.js';
 import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
 import { type GuardImpactAnalysis } from './analysis/impact.js';
-import type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode } from './model/types.js';
-export type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, } from './model/types.js';
+import type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, GuardWaiver, GuardWaiverPolicy } from './model/types.js';
+export type { GuardAdapterName, GuardApprovalMode, GuardContractKind, GuardBudgetMetric, GuardRuleKind, GuardRuleStatus, GuardSeverity, GuardToolMode, GuardWaiver, GuardWaiverPolicy, GuardWaiverDecision, } from './model/types.js';
 export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
 export interface GuardOutcomeInput {
     configured?: boolean | undefined;
@@ -85,6 +85,7 @@ export interface GuardConfig {
     contracts?: GuardContract[] | undefined;
     budgets?: GuardBudget[] | undefined;
     approval?: GuardApprovalPolicy | undefined;
+    waiverPolicy?: GuardWaiverPolicy | undefined;
 }
 export interface GuardApprovalPolicy {
     mode: GuardApprovalMode;
@@ -157,12 +158,17 @@ export interface GuardReport {
     findings: GuardFinding[];
     suppressed: number;
     scannedFiles: number;
+    waived: number;
+    waiverWarnings: GuardWaiver[];
+    expiredWaivers: GuardWaiver[];
 }
 interface ScanGuardOptions {
     changedOnly?: boolean | undefined;
     changedFiles?: Set<string> | undefined;
     baseline?: Set<string> | undefined;
     includeArchitectureInsights?: boolean | undefined;
+    waivers?: GuardWaiver[] | undefined;
+    now?: string | undefined;
 }
 export interface GuardReviewPacket {
     version: 1;
@@ -178,6 +184,9 @@ export interface GuardReviewPacket {
     contracts: GuardContract[];
     requirement?: string | undefined;
     deterministicFindings: GuardFinding[];
+    waived: number;
+    waiverWarnings: GuardWaiver[];
+    expiredWaivers: GuardWaiver[];
     impact: GuardImpactAnalysis;
     reviewInstructions: string[];
 }
@@ -185,6 +194,7 @@ export declare const GUARD_DIR: string;
 export declare const GUARD_RULES_FILE: string;
 export declare const GUARD_BASELINE_FILE: string;
 export declare const GUARD_BASELINE_META_FILE: string;
+export declare const GUARD_WAIVERS_FILE: string;
 export declare const GUARD_PROJECT_FILE: string;
 export declare const GUARD_HISTORY_DIR: string;
 export declare const GUARD_ARCHITECTURE_FILE: string;
@@ -212,6 +222,9 @@ export declare class GuardStateStaleError extends Error {
 export declare class GuardBaselineReasonError extends Error {
     constructor();
 }
+export declare class GuardWaiverError extends Error {
+    constructor(message: string);
+}
 export declare function withGuardStateLock<T>(root: string, callback: () => T, options?: GuardStateLockOptions): T;
 export declare function isGuardContractsFile(value: unknown): value is {
     version: 1;
@@ -227,6 +240,18 @@ export declare function isGuardAgentConfig(value: unknown): value is GuardAgentC
 export declare function loadGuardAgentConfig(root: string): GuardAgentConfig;
 export declare function writeGuardAgentConfig(root: string, agentConfig?: GuardAgentConfig): void;
 export declare function loadBaseline(root: string): Set<string>;
+export interface GuardWaiverUpdateOptions {
+    action: 'add' | 'renew' | 'remove';
+    waiver?: GuardWaiver | undefined;
+    waiverId: string;
+    reason: string;
+    expiresAt?: string | undefined;
+    actor?: string | undefined;
+    maxLifetimeDays?: number | undefined;
+}
+export declare function loadGuardWaivers(root: string): GuardWaiver[];
+export declare function writeGuardWaivers(root: string): void;
+export declare function updateGuardWaivers(root: string, options: GuardWaiverUpdateOptions): GuardWaiver[];
 export declare function updateBaseline(root: string, options?: GuardBaselineUpdateOptions): Set<string>;
 export declare function writeGuardConfig(root: string, guardConfig: GuardConfig, options?: GuardConfigWriteOptions): void;
 export declare function writeGuardProposals(root: string, proposals: GuardProposalFile): void;

package/dist/core/guard.js

@@ -9,7 +9,7 @@ import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findG
 import { config } from './config.js';
 import { assessGuardPacks, detectGuardPacks } from './analysis/packs.js';
 import { analyzeProjectImpact } from './analysis/impact.js';
-import { guardAgentConfigSchema, guardConfigSchema, guardContractsFileSchema, guardProposalSchema, } from './policy/schemas.js';
+import { guardAgentConfigSchema, guardConfigSchema, guardContractsFileSchema, guardProposalSchema, guardWaiversFileSchema, } from './policy/schemas.js';
 export function classifyGuardOutcome(input) {
     if (input.configured === false)
         return 'not-configured';
@@ -23,6 +23,7 @@ export const GUARD_DIR = `.${config.appName}/guard`;
 export const GUARD_RULES_FILE = `${GUARD_DIR}/rules.json`;
 export const GUARD_BASELINE_FILE = `${GUARD_DIR}/baseline.json`;
 export const GUARD_BASELINE_META_FILE = `${GUARD_DIR}/baseline-meta.json`;
+export const GUARD_WAIVERS_FILE = `${GUARD_DIR}/waivers.json`;
 export const GUARD_PROJECT_FILE = `${GUARD_DIR}/project.json`;
 export const GUARD_HISTORY_DIR = `${GUARD_DIR}/history`;
 export const GUARD_ARCHITECTURE_FILE = `${GUARD_DIR}/architecture.json`;
@@ -44,6 +45,7 @@ export const defaultGuardConfig = {
         allowMcpApproval: true,
         requireDistinctActor: false,
     },
+    waiverPolicy: { warningDays: 14 },
 };
 export const defaultGuardAgentConfig = {
     version: 1,
@@ -86,6 +88,12 @@ export class GuardBaselineReasonError extends Error {
         this.name = 'GuardBaselineReasonError';
     }
 }
+export class GuardWaiverError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GuardWaiverError';
+    }
+}
 const activeStateLocks = new Map();
 function processIsAlive(pid) {
     try {
@@ -429,6 +437,119 @@ export function loadBaseline(root) {
         throw new GuardConfigError(GUARD_BASELINE_FILE);
     return new Set(value.filter((item) => typeof item === 'string'));
 }
+function validateGuardWaiversFile(value) {
+    const ids = new Set();
+    const fingerprints = new Set();
+    for (const waiver of value.waivers) {
+        if (ids.has(waiver.id))
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        if (fingerprints.has(waiver.fingerprint))
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        if (Date.parse(waiver.expiresAt) <= Date.parse(waiver.createdAt)) {
+            throw new GuardConfigError(GUARD_WAIVERS_FILE);
+        }
+        ids.add(waiver.id);
+        fingerprints.add(waiver.fingerprint);
+    }
+}
+function assertWaiverLifetime(expiresAt, maxLifetimeDays) {
+    if (maxLifetimeDays === undefined)
+        return;
+    const lifetime = Date.parse(expiresAt) - Date.now();
+    if (lifetime > maxLifetimeDays * 24 * 60 * 60 * 1000) {
+        throw new GuardWaiverError(`A waiver may not exceed the configured maximum lifetime of ${maxLifetimeDays} day(s).`);
+    }
+}
+function readGuardWaiversUnlocked(root) {
+    const path = resolve(root, GUARD_WAIVERS_FILE);
+    if (!existsSync(path))
+        return { version: 1, waivers: [], decisions: [] };
+    const parsed = guardWaiversFileSchema.safeParse(readJson(path));
+    if (!parsed.success)
+        throw new GuardConfigError(GUARD_WAIVERS_FILE);
+    validateGuardWaiversFile(parsed.data);
+    return parsed.data;
+}
+export function loadGuardWaivers(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return readGuardWaiversUnlocked(root).waivers;
+    return withGuardStateLock(root, () => readGuardWaiversUnlocked(root).waivers);
+}
+export function writeGuardWaivers(root) {
+    withGuardStateLock(root, () => {
+        const file = { version: 1, waivers: [], decisions: [] };
+        atomicWriteFile(resolve(root, GUARD_WAIVERS_FILE), `${JSON.stringify(file, null, 2)}\n`);
+    });
+}
+export function updateGuardWaivers(root, options) {
+    if (!options.reason.trim())
+        throw new GuardWaiverError('A reason is required for waiver changes.');
+    return withGuardStateLock(root, () => {
+        const current = readGuardWaiversUnlocked(root);
+        const index = current.waivers.findIndex((waiver) => waiver.id === options.waiverId);
+        if (options.action === 'add') {
+            if (!options.waiver)
+                throw new GuardWaiverError('A waiver is required when adding one.');
+            if (index >= 0 ||
+                current.waivers.some((waiver) => waiver.fingerprint === options.waiver?.fingerprint)) {
+                throw new GuardWaiverError('A waiver already exists for this id or fingerprint.');
+            }
+            if (Date.parse(options.waiver.expiresAt) <= Date.now()) {
+                throw new GuardWaiverError('A waiver must expire in the future.');
+            }
+            if (Date.parse(options.waiver.expiresAt) <= Date.parse(options.waiver.createdAt)) {
+                throw new GuardWaiverError('A waiver must expire after it is created.');
+            }
+            assertWaiverLifetime(options.waiver.expiresAt, options.maxLifetimeDays);
+            const candidate = guardWaiversFileSchema.safeParse({
+                version: 1,
+                waivers: [...current.waivers, options.waiver],
+                decisions: current.decisions,
+            });
+            if (!candidate.success)
+                throw new GuardWaiverError('The waiver data is invalid.');
+            try {
+                validateGuardWaiversFile(candidate.data);
+            }
+            catch {
+                throw new GuardWaiverError('The waiver data is invalid.');
+            }
+            current.waivers.push(options.waiver);
+        }
+        else {
+            if (index < 0)
+                throw new GuardWaiverError(`Waiver not found: ${options.waiverId}`);
+            if (options.action === 'remove')
+                current.waivers.splice(index, 1);
+            else {
+                if (!options.expiresAt || Date.parse(options.expiresAt) <= Date.now()) {
+                    throw new GuardWaiverError('A renewed waiver must expire in the future.');
+                }
+                assertWaiverLifetime(options.expiresAt, options.maxLifetimeDays);
+                current.waivers[index] = { ...current.waivers[index], expiresAt: options.expiresAt };
+            }
+        }
+        const decision = {
+            at: new Date().toISOString(),
+            action: options.action,
+            waiverId: options.waiverId,
+            reason: options.reason.trim(),
+            ...(options.actor?.trim() ? { actor: options.actor.trim() } : {}),
+        };
+        current.decisions = [...current.decisions, decision].slice(-500);
+        const validated = guardWaiversFileSchema.safeParse(current);
+        if (!validated.success)
+            throw new GuardWaiverError('The waiver data is invalid.');
+        try {
+            validateGuardWaiversFile(validated.data);
+        }
+        catch {
+            throw new GuardWaiverError('The waiver data is invalid.');
+        }
+        atomicWriteFile(resolve(root, GUARD_WAIVERS_FILE), `${JSON.stringify(current, null, 2)}\n`);
+        return current.waivers;
+    });
+}
 export function updateBaseline(root, options = {}) {
     if ((options.add?.length ?? 0) > 0 || (options.remove?.length ?? 0) > 0) {
         if (!options.reason?.trim())
@@ -1538,12 +1659,45 @@ export function scanGuard(root, guardConfig, options = {}) {
         ...(options.includeArchitectureInsights ? architectureInsightFindings(root, scope) : []),
     ];
     const baseline = options.baseline ?? new Set();
-    const findings = allFindings.filter((finding) => !baseline.has(finding.fingerprint));
+    const waivers = options.waivers ?? loadGuardWaivers(root);
+    if (options.waivers) {
+        const parsedWaivers = guardWaiversFileSchema.safeParse({
+            version: 1,
+            waivers,
+            decisions: [],
+        });
+        if (!parsedWaivers.success)
+            throw new GuardWaiverError('The waiver data is invalid.');
+        try {
+            validateGuardWaiversFile(parsedWaivers.data);
+        }
+        catch {
+            throw new GuardWaiverError('The waiver data is invalid.');
+        }
+    }
+    const nowValue = options.now ?? new Date().toISOString();
+    const now = Date.parse(nowValue);
+    if (!Number.isFinite(now))
+        throw new GuardWaiverError(`Invalid Guard time: ${nowValue}`);
+    const activeWaivers = new Map(waivers
+        .filter((waiver) => Date.parse(waiver.expiresAt) > now)
+        .map((waiver) => [waiver.fingerprint, waiver]));
+    const warningDays = guardConfig.waiverPolicy?.warningDays ?? 14;
+    const warningLimit = now + warningDays * 24 * 60 * 60 * 1000;
+    const currentFingerprints = new Set(allFindings.map((finding) => finding.fingerprint));
+    const relevantWaivers = waivers.filter((waiver) => currentFingerprints.has(waiver.fingerprint));
+    const waiverWarnings = relevantWaivers.filter((waiver) => Date.parse(waiver.expiresAt) > now && Date.parse(waiver.expiresAt) <= warningLimit);
+    const expiredWaivers = relevantWaivers.filter((waiver) => Date.parse(waiver.expiresAt) <= now);
+    const baselineFindings = allFindings.filter((finding) => !baseline.has(finding.fingerprint));
+    const findings = baselineFindings.filter((finding) => !activeWaivers.has(finding.fingerprint));
     return {
         configured: true,
         findings,
         suppressed: allFindings.length - findings.length,
         scannedFiles: files.length,
+        waived: baselineFindings.length - findings.length,
+        waiverWarnings,
+        expiredWaivers,
     };
 }
 export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(), maxDiffChars = 120_000, changedOnly = true, requirement, base) {
@@ -1570,6 +1724,9 @@ export function buildGuardReviewPacket(root, guardConfig, baseline = new Set(),
         contracts: guardConfig.contracts ?? [],
         ...(requirement ? { requirement } : {}),
         deterministicFindings: report.findings,
+        waived: report.waived,
+        waiverWarnings: report.waiverWarnings,
+        expiredWaivers: report.expiredWaivers,
         impact,
         reviewInstructions: [
             ...(requirement
@@ -1595,6 +1752,9 @@ export function initializeGuard(root, options = {}) {
         const guardConfig = loadGuardConfig(root) ?? buildGeneratedGuardConfig(projectModel);
         ensureGeneratedStateIgnored(root, projectModel);
         writeGuardConfig(root, guardConfig);
+        if (options.force || !existsSync(resolve(root, GUARD_WAIVERS_FILE))) {
+            writeGuardWaivers(root);
+        }
         if (options.force || !existsSync(resolve(root, GUARD_AGENT_FILE))) {
             writeGuardAgentConfig(root);
         }

package/dist/core/model/types.d.ts

@@ -5,6 +5,28 @@ export type GuardRuleStatus = 'active' | 'proposed';
 export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call' | 'package-boundary';
 export type GuardBudgetMetric = 'lines' | 'bytes' | 'imports';
 export type GuardToolMode = 'auto' | 'on' | 'off';
+export interface GuardWaiver {
+    id: string;
+    fingerprint: string;
+    ruleId: string;
+    owner: string;
+    reason: string;
+    createdAt: string;
+    expiresAt: string;
+    issue?: string | undefined;
+    approvedBy?: string | undefined;
+}
+export interface GuardWaiverPolicy {
+    warningDays: number;
+    maxDays?: number | undefined;
+}
+export interface GuardWaiverDecision {
+    at: string;
+    action: 'add' | 'renew' | 'remove';
+    waiverId: string;
+    reason: string;
+    actor?: string | undefined;
+}
 export type GuardApprovalMode = 'local' | 'protected';
 export type GuardAdapterName = 'dependency-graph' | 'security' | 'dependency-hygiene' | 'sast' | 'secret-scanning' | 'dependency-audit';
 export type ProjectCheck = 'lint' | 'typecheck' | 'test' | 'build';

package/dist/core/output/sarif.d.ts

@@ -1,11 +1,16 @@
 import type { GuardFinding } from '../guard.js';
+export interface GuardSarifNotice {
+    ruleId: string;
+    level: 'error' | 'warning' | 'note';
+    message: string;
+}
 interface SarifResult {
     ruleId: string;
     level: 'error' | 'warning' | 'note';
     message: {
         text: string;
     };
-    locations: [
+    locations?: [
         {
             physicalLocation: {
                 artifactLocation: {
@@ -31,5 +36,5 @@ export interface SarifLog {
         results: SarifResult[];
     }];
 }
-export declare function guardFindingsToSarif(findings: GuardFinding[]): SarifLog;
+export declare function guardFindingsToSarif(findings: GuardFinding[], notices?: GuardSarifNotice[]): SarifLog;
 export {};

package/dist/core/output/sarif.js

@@ -1,4 +1,25 @@
-export function guardFindingsToSarif(findings) {
+export function guardFindingsToSarif(findings, notices = []) {
+    const findingResults = findings.map((finding) => ({
+        ruleId: finding.ruleId,
+        level: finding.severity === 'info' ? 'note' : finding.severity,
+        message: { text: finding.message },
+        locations: [
+            {
+                physicalLocation: {
+                    artifactLocation: { uri: finding.file },
+                    region: { startLine: finding.line },
+                },
+            },
+        ],
+    }));
+    const results = [
+        ...findingResults,
+        ...notices.map((notice) => ({
+            ruleId: notice.ruleId,
+            level: notice.level,
+            message: { text: notice.message },
+        })),
+    ];
     return {
         version: '2.1.0',
         $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
@@ -10,19 +31,7 @@ export function guardFindingsToSarif(findings) {
                         informationUri: 'https://codapult.dev/docs/developer-tools/guard',
                     },
                 },
-                results: findings.map((finding) => ({
-                    ruleId: finding.ruleId,
-                    level: finding.severity === 'info' ? 'note' : finding.severity,
-                    message: { text: finding.message },
-                    locations: [
-                        {
-                            physicalLocation: {
-                                artifactLocation: { uri: finding.file },
-                                region: { startLine: finding.line },
-                            },
-                        },
-                    ],
-                })),
+                results,
             },
         ],
     };

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>;

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,6 +79,16 @@ 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),

package/dist/core/verification/verify.js

@@ -93,7 +93,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 ||

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,4 +1,5 @@
-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';
@@ -13,6 +14,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',
@@ -563,6 +570,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.1",
+  "version": "0.7.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",
@@ -57,6 +57,7 @@
     "release:check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test && pnpm build && npm pack --dry-run && pnpm mcp:validate",
     "mcp:validate": "node scripts/mcp-registry.mjs validate",
     "mcp:sync": "node scripts/mcp-registry.mjs sync",
+    "mcp:wait": "node scripts/mcp-registry.mjs wait",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:guard:coverage": "vitest run src/core src/adapters/project-checks.test.ts --coverage --coverage.include='src/core/**/*.ts' --coverage.include='src/adapters/project-checks.ts'",