@codapult/guard 0.6.2 → 0.8.0

package/README.md

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

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

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

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

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

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

@@ -17,6 +17,11 @@ interface GuardVerifyOptions extends GuardOutputOptions {
     tools?: GuardToolMode | undefined;
     strict?: boolean | undefined;
     projectChecks?: boolean | undefined;
+    policyBase?: string | undefined;
+    failOnPolicyChange?: boolean | undefined;
+}
+interface GuardGovernanceOptions extends GuardOutputOptions {
+    strict?: boolean | undefined;
 }
 interface GuardCheckOptions extends GuardOutputOptions {
     changed?: boolean | undefined;
@@ -26,6 +31,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;
 }
@@ -43,12 +54,14 @@ export declare function guardDoctorCommand(options?: GuardOutputOptions & {
 }): void;
 export declare function guardHistoryCommand(): void;
 export declare function guardRunsCommand(options?: GuardOutputOptions): void;
+export declare function guardGovernanceCommand(options?: GuardGovernanceOptions): void;
 export declare function guardImpactCommand(files: string[], options?: GuardOutputOptions): void;
 export declare function guardHistoryDiffCommand(from: string, to: string, options?: GuardOutputOptions): void;
 export declare function guardVerifyCommand(options?: GuardVerifyOptions): void;
 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';
@@ -10,6 +11,7 @@ import { dim, fail, heading, info, success, warn } from '../ui.js';
 import { guardFindingsToSarif } from '../../core/output/sarif.js';
 import { analyzeProjectImpact } from '../../core/analysis/impact.js';
 import { listGuardRuns, summarizeGuardRuns } from '../../core/history/runs.js';
+import { auditGuardGovernance } from '../../core/audit/governance.js';
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -19,6 +21,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 +186,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`);
         }
@@ -208,6 +222,32 @@ export function guardRunsCommand(options = {}) {
         info(`${run.runId}: ${run.outcome}, gate=${run.gate}, ${run.durationMs} ms`);
     }
 }
+export function guardGovernanceCommand(options = {}) {
+    const root = getRoot();
+    let result;
+    try {
+        result = auditGuardGovernance(root);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        heading('Codapult Guard Governance');
+        info(`Approvals: ${result.approvals.approved} approved, ${result.approvals.actors.length} declared actor(s), ${result.approvals.missingActors} missing actor(s).`);
+        info(`Declared actor/proposal-author overlap: ${result.approvals.actorAuthorOverlap.length}.`);
+        info(`Policy-linked approvals: ${result.reachability.approvedLinkedToRun}/${result.reachability.approvedWithPolicyFingerprint} linked to a retained verification run.`);
+        for (const warning of result.warnings)
+            warn(warning);
+        if (result.warnings.length === 0)
+            success('No governance completeness warnings.');
+    }
+    process.exitCode = options.strict && result.warnings.length > 0 ? 1 : 0;
+}
 export function guardImpactCommand(files, options = {}) {
     const root = getRoot();
     if (files.length === 0) {
@@ -270,6 +310,8 @@ export function guardVerifyCommand(options = {}) {
         tools: options.tools,
         strict: options.strict,
         projectChecks: options.projectChecks,
+        policyBase: options.policyBase,
+        failOnPolicyChange: options.failOnPolicyChange,
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -282,6 +324,12 @@ export function guardVerifyCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
+    if (result.policy?.source === 'git-ref') {
+        dim(`policy: ${result.policy.ref ?? 'Git ref'} (${result.policy.fingerprint})`);
+        if (result.policyChanged) {
+            warn('The working-tree policy differs from the base policy; the base policy was used.');
+        }
+    }
     for (const [name, check] of Object.entries(result.checks)) {
         if (check.status === 'passed')
             success(`${name}: passed`);
@@ -303,6 +351,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 +390,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 +402,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 +433,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 +470,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 +490,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 +546,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,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardGovernanceCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRunsCommand, guardRulesApproveCommand, guardVerifyCommand, guardWaiverCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
-import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, GuardWaiverError, } from '../core/guard.js';
+import { GuardAgentInstallError } from '../adapters/agents/agent-integration.js';
 import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
@@ -23,6 +24,7 @@ guard.command('install-agent [target]').option('--json').action(guardInstallAgen
 guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('runs').option('--json').action(guardRunsCommand);
+guard.command('governance').option('--json').option('--strict').action(guardGovernanceCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
 guard
@@ -40,6 +42,8 @@ guard
     .option('--no-project-checks')
     .option('--requirement <file>')
     .option('--changed')
+    .option('--policy-base <ref>', 'read policy artifacts from this Git ref')
+    .option('--fail-on-policy-change', 'fail when the working-tree policy differs from the base ref')
     .option('--json')
     .action(guardVerifyCommand);
 guard
@@ -72,6 +76,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,10 +113,13 @@ catch (error) {
     if (error instanceof GuardConfigError ||
         error instanceof GuardBaselineReasonError ||
         error instanceof GuardStateBusyError ||
-        error instanceof GuardStateStaleError) {
+        error instanceof GuardStateStaleError ||
+        error instanceof GuardWaiverError ||
+        error instanceof GuardAgentInstallError) {
         const isBusy = error instanceof GuardStateBusyError;
         const isStale = error instanceof GuardStateStaleError;
         const isInvalidInput = error instanceof GuardBaselineReasonError;
+        const isInstallError = error instanceof GuardAgentInstallError;
         console.error(JSON.stringify(guardErrorPayload(isBusy
             ? 'GUARD_STATE_BUSY'
             : isStale
@@ -103,7 +134,9 @@ catch (error) {
                 ? 'Re-read Guard state and retry the operation.'
                 : isInvalidInput
                     ? 'Provide a written reason for the baseline decision.'
-                    : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+                    : isInstallError
+                        ? 'Remove the symbolic link or choose a regular project path, then retry.'
+                        : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
         }), null, 2));
         process.exitCode = 1;
     }

package/dist/core/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 {