@codapult/guard 0.7.0 → 0.8.1

package/README.md

@@ -57,43 +57,6 @@ The core is universal. The strongest first-class scenarios are Next.js SaaS and
 development, including server/client boundaries, routes, persistence, authentication, billing,
 background jobs, environment configuration, and AI integrations.
 
-## Part of the Codapult ecosystem
-
-Guard is an independent open-source project from [Codapult](https://codapult.dev). It does not
-require Codapult and can be installed in any JavaScript or TypeScript repository.
-
-The relationship is complementary:
-
-| Project               | Role                                                                                     |
-| --------------------- | ---------------------------------------------------------------------------------------- |
-| **`@codapult/guard`** | Universal architecture guardrails, project memory, contracts, MCP, and AI-agent context. |
-| **`@codapult/cli`**   | Codapult SaaS project CLI that includes Guard through a thin adapter.                    |
-| **Codapult**          | Full-source Next.js SaaS foundation with conventions Guard can discover and protect.     |
-
-Use standalone Guard for any compatible project. Use the Codapult CLI when working on a Codapult
-SaaS project and you want project management, database, plugins, deployment, MCP, and Guard in one
-CLI.
-
-```text
-        Existing project
-              │
-              ▼
-       deterministic discovery
-     AST · files · imports · Git
-              │
-              ▼
-        project architecture
-  capabilities · graph · impact paths
-              │
-              ▼
-       approved project policy
-  rules · contracts · conventions · baseline
-              │
-              ▼
-          change verification
-   check · review packet · verify · CI
-```
-
 ## Why Guard exists
 
 AI agents can produce syntactically valid code that still violates the architecture of a real
@@ -172,6 +135,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 +187,7 @@ init once → edit → check --changed → review → verify → commit / merge
 ```
 
 1. `init` builds project memory and establishes the initial baseline.
-2. `check --changed` is the fast deterministic architecture gate.
+2. `check` scans the current project; `check --changed` is the fast change-scoped architecture gate.
 3. `review` prepares a bounded and redacted diff packet for an AI host; it does not call an LLM.
 4. `verify` runs Guard policy, configured project checks, adapters, runtime diagnostics, and
    contract validation.
@@ -238,6 +218,11 @@ Guard state is stored in `.codapult/guard/`:
 Commit policy and baseline files when the team wants shared guardrails. Treat cache artifacts as
 disposable according to the project’s policy, and never commit secrets.
 
+Baseline fingerprints do not include line numbers, so formatting and line movement do not recreate
+the same finding. They do include the rule and affected file/import identity, so a rename or module
+move can produce a new fingerprint and should be reviewed explicitly before accepting it into the
+baseline.
+
 ### Temporary waivers
 
 Baseline records legacy findings that existed when Guard was introduced. A waiver is different: it
@@ -315,9 +300,10 @@ Register that command in the MCP client from the project root. For example, Curs
 {
   "mcpServers": {
     "codapult-guard": {
+      "type": "stdio",
       "command": "pnpm",
       "args": ["exec", "codapult-guard", "mcp-server"],
-      "cwd": "."
+      "cwd": "${workspaceFolder}"
     }
   }
 }
@@ -369,6 +355,37 @@ and Guard rejects the same declared actor when a proposal was generated with `GU
 These variables provide declared provenance only; external branch protection or signed identity
 remains responsible for proving who approved the change.
 
+### Verifying against protected policy
+
+In CI, verify pull requests against the policy from the protected base commit rather than the
+copy carried by the branch:
+
+```bash
+codapult-guard verify --policy-base "$BASE_SHA" --json
+```
+
+Guard then evaluates the changed source with the base commit's rules, contracts, baseline, waivers,
+and completion-gate configuration. The result reports `policy.source`, `policy.ref`,
+`policy.revision`, `policy.fingerprint`, and whether the checked-out policy differs from that
+base. A branch cannot relax its policy or disable the gate and use that relaxed copy for the same
+verification run.
+
+The supplied [`docs/guard-ci.yml`](docs/guard-ci.yml) fetches the full Git history and passes the
+pull request base SHA automatically. Protect `.codapult/guard/` with CODEOWNERS or the equivalent
+review control when policy changes require a separate approval. For example, a repository can add
+`.codapult/guard/* @architecture-owners` to `CODEOWNERS`. Guard reports the policy change; the
+hosting platform enforces reviewer authorization.
+
+To make policy changes fail this invocation explicitly, add:
+
+```bash
+codapult-guard verify --policy-base "$BASE_SHA" --fail-on-policy-change
+```
+
+This is useful for a dedicated policy-review gate. It is intentionally separate from using the
+base policy for source verification, so teams can choose how their protected review workflow
+handles an approved policy update.
+
 See [the extension map](docs/extensions.md) for the supported AI-host, CI/PR, policy-pack, tool
 adapter, approval-governance, and observability integrations.
 
@@ -394,16 +411,18 @@ real project shapes.
 | `init`                     | Create project memory and the initial baseline.                                             |
 | `analyze`                  | Refresh facts without changing policy or baseline.                                          |
 | `propose`                  | Generate evidence-based rule and contract proposals.                                        |
-| `check --changed`          | Enforce active policy on changed and untracked files.                                       |
+| `check [--changed]`        | Enforce active policy; `--changed` limits findings to changed and untracked files.          |
 | `audit`                    | Scan the complete current project, including baseline findings.                             |
 | `review`                   | Create a bounded semantic-review packet for an AI host.                                     |
 | `verify`                   | Run the configured completion gate.                                                         |
+| `governance`               | Audit declared proposal/approval provenance and decision-to-run reachability.               |
 | `doctor`                   | Diagnose invalid or missing Guard artifacts.                                                |
 | `history` / `history-diff` | Inspect project model, module graph, and architecture-edge evolution.                       |
 | `impact <files...>`        | Explain dependencies, transitive dependents, capabilities, and contracts affected by files. |
 | `policy explain <id>`      | Explain a policy item, its evidence, and approval history.                                  |
 | `rules` / `contracts`      | Approve or reject proposed policy.                                                          |
 | `baseline`                 | Review or intentionally accept existing findings.                                           |
+| `waiver`                   | Manage owner-attributed, time-bounded exceptions to exact findings.                         |
 
 Use `analyze --refresh` after a structural change. `doctor --fix-cache` removes only the disposable
 discovery cache; it does not change rules, contracts, baseline, or source files.
@@ -417,8 +436,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
 
@@ -458,6 +482,12 @@ pnpm release:check
 - [Fixture matrix](docs/guard-fixtures.md)
 - [Release process](docs/releasing.md)
 
+## More from Codapult
+
+Starting a SaaS from scratch? [Codapult](https://codapult.dev) is a production-ready Next.js SaaS
+foundation built for AI-assisted development — with MCP context, built-in AI, modular
+architecture, and the source code under your control.
+
 ## Project status
 
 `@codapult/guard` starts at `0.1.0` as a public alpha. The deterministic core is usable, tested,

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

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

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

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

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

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

package/dist/cli/commands/guard.js

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

package/dist/cli/index.js

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

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

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

package/dist/core/audit/governance.js

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

package/dist/core/errors.d.ts

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

package/dist/core/guard.d.ts

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