@codapult/guard 0.10.0 → 0.11.0

package/README.md

@@ -6,6 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node.js >=20.19](https://img.shields.io/badge/node-%3E%3D20.19-339933.svg?logo=node.js&logoColor=white)](package.json)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-3178C6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Listed-4B6A88?style=flat-square)](https://registry.modelcontextprotocol.io/?q=io.github.codapult%2Fguard)
 
 ## Architecture guardrails for AI coding agents
 
@@ -388,6 +389,131 @@ review control when policy changes require a separate approval. For example, a r
 `.codapult/guard/* @architecture-owners` to `CODEOWNERS`. Guard reports the policy change; the
 hosting platform enforces reviewer authorization.
 
+Guard also reports changes to verification-sensitive files using built-in paths for CI workflows,
+package scripts and lockfiles, and common formatter, linter, typecheck, and test configurations.
+Projects can extend this list in the base revision's `.codapult/guard/rules.json`:
+
+```json
+{
+  "version": 1,
+  "rules": [],
+  "protectedPaths": [".husky/**", "config/security-checks/**"]
+}
+```
+
+For classified entries and warning-only paths, use the explicit `policySurface.paths` form in that
+same base policy:
+
+```json
+{
+  "version": 1,
+  "rules": [],
+  "policySurface": {
+    "paths": [
+      { "pattern": "config/security-checks/**", "kind": "custom", "severity": "error" },
+      { "pattern": "**/.custom-ignore", "kind": "ignore-config", "severity": "warning" }
+    ]
+  }
+}
+```
+
+Supported kinds are `ci-workflow`, `guard-policy`, `ownership`, `dependency-input`, `tool-config`, `ignore-config`,
+`suppression-source`, and `custom`. `error` entries fail when `--fail-on-protected-changes` is
+enabled; `warning` entries are reported without blocking. Built-in verification-sensitive paths
+remain blocking. Both forms are read from the base policy during PR verification, so the PR cannot
+remove its own path coverage.
+
+In pull request CI, add `--fail-on-protected-changes` alongside `--policy-base`. This fails the
+Guard invocation when a listed path changes without a matching CI integrity contract, or when a
+contracted workflow fails its checks. It emits all matched paths in JSON output. Protect
+the Guard workflow itself and require its status check in repository settings: a workflow edited
+or removed by a PR cannot independently enforce its own integrity. Guard reports workflow edits,
+but GitHub branch protection is what makes the check mandatory. The sample workflow rejects PR
+changes to package manifests, common npm/pnpm/Yarn/Bun lockfiles, package-manager config, and
+workspace install inputs before
+selecting pnpm or installing dependencies. Review those changes in a separate PR. This preflight is
+defense in depth: repository rules must still protect the workflow and require the Guard check.
+
+Guard reports added `eslint-disable`, `@ts-ignore`, `@ts-nocheck`, `@ts-expect-error`, and
+`biome-ignore`, and `prettier-ignore` markers in the PR diff. It reports the file and marker
+without interpreting the tool-specific reason or whether the suppression is justified. Other
+tools can be covered by protecting their configuration/source paths and running them in a trusted
+CI workflow. The matched paths, markers, and scan completeness are recorded in the verification
+result and receipt.
+
+### Required verification stages
+
+`agent.json` declares which stages must complete for verification to pass:
+
+```json
+{
+  "version": 1,
+  "tools": "auto",
+  "tooling": {},
+  "completionGate": {
+    "enabled": true,
+    "maxIterations": 3,
+    "projectChecks": true,
+    "checks": ["lint", "typecheck", "test", "build"],
+    "requiredStages": ["architecture-policy", "project-checks", "runtime"]
+  }
+}
+```
+
+Supported stages are `runtime`, `project-checks`, `adapters`, `architecture-policy`,
+`policy-surface`, `ci-integrity`, and `verification-scope`. The compatibility default requires `architecture-policy`;
+projects opt into additional requirements. If a required stage is skipped or cannot be confirmed,
+the result is `incomplete`, the CLI exits nonzero, and the receipt names the incomplete stages.
+When base policy is used, `policy-surface` is required automatically. A configured CI integrity
+contract makes `ci-integrity` required automatically. `verification-scope` is always required:
+Guard hashes its discovered project inputs before checks and confirms that the scope stayed stable
+through the run.
+
+### GitHub Actions integrity contract
+
+Declare the exact workflow and required job in the base revision's `rules.json`:
+
+```json
+{
+  "version": 1,
+  "rules": [],
+  "githubActions": {
+    "workflows": [
+      {
+        "path": ".github/workflows/guard.yml",
+        "job": "guard",
+        "requiredRunIncludes": [
+          "pnpm exec codapult-guard verify",
+          "--policy-base",
+          "--fail-on-policy-change",
+          "--fail-on-protected-changes"
+        ],
+        "maxPermissions": { "contents": "read", "security-events": "write" }
+      }
+    ]
+  }
+}
+```
+
+Guard parses the declared workflow and checks its pull request trigger, configured filters, required
+job, required command fragments in the Guard invocation, conditional execution, `continue-on-error`,
+declared job dependencies, explicit permission ceilings, and full commit SHA pins for external
+actions. Local actions cannot meet immutable SHA pinning; if a workflow uses one, set
+`requireFullShaActions` to `false` and list its source under `protectedPaths` in the base policy.
+Guard compares each action ref with the contracted workflow at the base revision; additions,
+removals, and SHA changes are reported as `policy-weakened` for separate review even when the new
+ref is itself SHA-pinned. Missing protections are reported as `policy-weakened`; malformed or
+unreadable workflow data is `incomplete`. The result and receipt include base/current workflow
+digests, action refs and their changes, and issues. Guard does not
+evaluate arbitrary GitHub expressions or prove that repository settings require the check; branch
+protection or rulesets must still require the expected check source.
+The audit rejects `pull_request_target` on a contracted verification workflow because Guard cannot
+prove that it never executes untrusted PR content with that event's elevated context.
+
+The receipt records the effective Guard invocation and each project check's command and arguments.
+Credential-like values are redacted from command evidence; treat receipts as review artifacts, not
+as a substitute for trusted CI logs.
+
 To make policy changes fail this invocation explicitly, add:
 
 ```bash
@@ -418,6 +544,13 @@ The package repository separately runs its own unit, typecheck, build, and packa
 [`.github/workflows/ci.yml`](.github/workflows/ci.yml), while the fixture workflow tests Guard on
 real project shapes.
 
+To add a separately signed Guard receipt, copy
+[`docs/guard-trusted-pr-attestation.yml`](docs/guard-trusted-pr-attestation.yml) to
+`.github/workflows/guard-trusted-pr-attestation.yml` and follow the
+[trusted-attestation setup guide](docs/guard.md#install-the-trusted-github-actions-workflow).
+This optional workflow re-runs Guard; it does not replace the required `Guard` check or attest
+project test/build results.
+
 ## CLI surface
 
 | Command                    | Purpose                                                                                     |
@@ -460,10 +593,17 @@ production tracing system or an identity/signature ledger.
 
 The manifest also contains a `verification-receipt` object. It is a compact, machine-readable
 record of the commit, policy base and fingerprint, decision IDs, check statuses, finding counts,
-contract issues, waiver state, and Guard version. It intentionally excludes command output and
-source code. The receipt describes what Guard decided; it is not a cryptographic signature or proof
-of CI identity. When a policy base is supplied, it separates the base diff from dirty working-tree
-files so local verification cannot silently present an incomplete change set.
+contract issues, waiver state, and Guard version. Its `verificationScope` contains SHA-256 hashes
+and paths for files discovered by Guard plus changed and deleted paths; the fingerprint binds that
+inventory to the effective policy and Guard version. The `verification-scope` stage is incomplete
+if Guard cannot hash the full scope or if the inputs changed during the run. The receipt excludes
+source contents and command output. It describes what Guard decided; it is not a cryptographic
+signature or proof of CI identity. When a policy base is supplied, it separates the base diff from
+dirty working-tree files so local verification cannot silently present an incomplete change set.
+For portable exchange, `verify --attestation-out <file>` exports a passing receipt as an unsigned
+in-toto Statement. The format is independent of the CI platform and signing mechanism; a trusted CI
+signer can sign it using the mechanism supported by that platform. The attestation guide includes a
+GitHub Actions example using Sigstore. See the [attestation guide](docs/guard.md#exporting-and-signing-a-verification-attestation).
 
 ## Security and data handling
 

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

@@ -1,4 +1,5 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { dirname, resolve } from 'node:path';
 export class GuardAgentInstallError extends Error {
     constructor(message) {
@@ -8,6 +9,21 @@ export class GuardAgentInstallError extends Error {
 }
 const START_MARKER = '<!-- codapult-guard:start -->';
 const END_MARKER = '<!-- codapult-guard:end -->';
+function writeInstructionFile(path, content) {
+    const temporaryPath = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    try {
+        writeFileSync(temporaryPath, content, { encoding: 'utf8', flag: 'wx' });
+        renameSync(temporaryPath, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // The temporary file was renamed or could not be created.
+        }
+    }
+}
 const instruction = `${START_MARKER}
 ## Codapult Guard completion gate
 
@@ -56,7 +72,14 @@ export function installGuardAgentInstructions(root, target) {
     assertNoSymlinkPath(root, relativePath);
     const path = resolve(root, relativePath);
     const nextBlock = instruction;
-    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    let existing = '';
+    try {
+        existing = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
     const start = existing.indexOf(START_MARKER);
     const end = existing.indexOf(END_MARKER);
     const content = start >= 0 && end >= start
@@ -65,7 +88,7 @@ export function installGuardAgentInstructions(root, target) {
             ? `${existing.trimEnd()}\n\n${renderContent(target)}`
             : renderContent(target);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, content, 'utf8');
+    writeInstructionFile(path, content);
     return { target, path: relativePath, action: existing ? 'updated' : 'created' };
 }
 export function installGuardAgentTargets(root, targetsToInstall) {

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

@@ -19,6 +19,8 @@ interface GuardVerifyOptions extends GuardOutputOptions {
     projectChecks?: boolean | undefined;
     policyBase?: string | undefined;
     failOnPolicyChange?: boolean | undefined;
+    failOnProtectedChanges?: boolean | undefined;
+    attestationOut?: string | undefined;
 }
 interface GuardGovernanceOptions extends GuardOutputOptions {
     strict?: boolean | undefined;

package/dist/cli/commands/guard.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } 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, GuardWaiverError, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, loadGuardWaivers, updateBaseline, updateGuardWaivers, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, getGuardPolicyMutationPolicy, validateGuardPolicy, writeProjectState, } from '../../core/guard.js';
 import { guardErrorPayload } from '../../core/errors.js';
@@ -12,6 +12,15 @@ 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';
+import { guardReceiptToInToto } from '../../core/output/attestation.js';
+function terminalSafe(value) {
+    let output = '';
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        output += code <= 0x1f || (code >= 0x7f && code <= 0x9f) ? ' ' : character;
+    }
+    return output;
+}
 function renderFindings(findings) {
     for (const finding of findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
@@ -49,7 +58,7 @@ function loadConfigSafely(root, options = {}) {
         if (options.json || options.machine)
             console.log(JSON.stringify(payload, null, 2));
         else
-            fail(`${payload.message} Run \`codapult-guard doctor\` for details.`);
+            fail(`${terminalSafe(payload.message)} Run \`codapult-guard doctor\` for details.`);
         process.exitCode = 1;
         return { invalid: true };
     }
@@ -217,7 +226,7 @@ export function guardRunsCommand(options = {}) {
         return;
     }
     heading('Codapult Guard Runs');
-    info(`${result.summary.total} run(s); ${result.summary.failed} failed, ${result.summary.warnings} warning, average ${result.summary.averageDurationMs} ms`);
+    info(`${result.summary.total} run(s); ${result.summary.failed} failed, ${result.summary.incomplete} incomplete, ${result.summary.policyWeakened} policy-weakened, ${result.summary.warnings} warning, average ${result.summary.averageDurationMs} ms`);
     for (const run of result.runs) {
         info(`${run.runId}: ${run.outcome}, gate=${run.gate}, ${run.durationMs} ms`);
     }
@@ -312,10 +321,26 @@ export function guardVerifyCommand(options = {}) {
         projectChecks: options.projectChecks,
         policyBase: options.policyBase,
         failOnPolicyChange: options.failOnPolicyChange,
+        failOnProtectedChanges: options.failOnProtectedChanges,
     });
+    let attestationFailed = false;
+    if (options.attestationOut) {
+        try {
+            if (!result.run.receipt)
+                throw new Error('Guard did not produce a verification receipt.');
+            const statement = guardReceiptToInToto(result.run.receipt);
+            writeFileSync(resolve(options.attestationOut), `${JSON.stringify(statement, null, 2)}\n`);
+            if (!options.json)
+                info(`in-toto verification statement written to ${options.attestationOut}`);
+        }
+        catch (error) {
+            attestationFailed = true;
+            fail(error instanceof Error ? error.message : 'Could not write the in-toto statement.');
+        }
+    }
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
-        process.exitCode = result.status === 'ok' ? 0 : 1;
+        process.exitCode = result.status === 'ok' && !attestationFailed ? 0 : 1;
         return;
     }
     heading('Codapult Guard Verify');
@@ -330,21 +355,62 @@ export function guardVerifyCommand(options = {}) {
             warn('The working-tree policy differs from the base policy; the base policy was used.');
         }
     }
+    if (result.policySurface) {
+        dim(`protected paths changed: ${result.policySurface.changedPaths.length}`);
+        for (const path of result.policySurface.changedPaths)
+            warn(`verification-sensitive: ${terminalSafe(path)}`);
+        for (const change of result.policySurface.changes) {
+            dim(`policy surface: ${change.kind}/${change.severity} ${terminalSafe(change.path)} (${terminalSafe(change.pattern)})`);
+        }
+        for (const marker of result.policySurface.suppressionMarkers)
+            warn(`inline suppression added: ${terminalSafe(marker)}`);
+        if (result.policySurface.workflowChanged)
+            warn('Workflow changes require host-enforced required checks and protected review.');
+    }
+    if (result.ciIntegrity) {
+        if (result.ciIntegrity.status === 'ok')
+            success('CI integrity: passed');
+        else if (result.ciIntegrity.status === 'policy-weakened') {
+            fail('CI integrity: policy weakened');
+        }
+        else {
+            warn('CI integrity: incomplete');
+        }
+        for (const workflow of result.ciIntegrity.workflows) {
+            for (const change of workflow.actionChanges ?? []) {
+                warn(`[${terminalSafe(workflow.path)}] action refs changed for ${terminalSafe(change.name)}: ${terminalSafe(change.base.join(', ') || '(none)')} → ${terminalSafe(change.current.join(', ') || '(none)')}`);
+            }
+            for (const issue of workflow.issues)
+                fail(`[${terminalSafe(workflow.path)}] ${terminalSafe(issue.message)}`);
+        }
+    }
+    const receipt = result.run.receipt;
+    if (receipt?.effectiveInvocation) {
+        dim(`effective invocation: ${terminalSafe(receipt.effectiveInvocation.command)} ${terminalSafe(receipt.effectiveInvocation.args.join(' '))}`);
+    }
+    if (result.incompleteStages && result.incompleteStages.length > 0) {
+        warn(`Required stages incomplete: ${result.incompleteStages.join(', ')}`);
+    }
     for (const [name, check] of Object.entries(result.checks)) {
         if (check.status === 'passed')
-            success(`${name}: passed`);
+            success(`${terminalSafe(name)}: passed`);
         else if (check.status === 'not-configured')
-            dim(`${name}: not configured`);
+            dim(`${terminalSafe(name)}: not configured`);
         else
-            fail(`${name}: failed (exit ${check.exitCode})`);
+            fail(`${terminalSafe(name)}: failed (exit ${check.exitCode})`);
     }
     for (const [name, check] of Object.entries(result.adapters ?? {})) {
         if (check.status === 'passed')
-            success(`${name}: passed`);
+            success(`${terminalSafe(name)}: passed`);
         else if (check.status === 'not-configured')
-            dim(`${name}: not configured`);
+            dim(`${terminalSafe(name)}: not configured`);
         else
-            fail(`${name}: failed (exit ${check.exitCode})`);
+            fail(`${terminalSafe(name)}: failed (exit ${check.exitCode})`);
+    }
+    for (const [name, evidence] of Object.entries(receipt?.checks ?? {})) {
+        if (!evidence.command)
+            continue;
+        dim(`${terminalSafe(name)} command (${evidence.execution ?? 'unknown'}): ${terminalSafe(evidence.command)}${(evidence.args?.length ?? 0) > 0 ? ` ${terminalSafe(evidence.args?.join(' ') ?? '')}` : ''}`);
     }
     const findings = result.architecture?.findings ?? [];
     if (findings.length === 0)
@@ -358,7 +424,7 @@ export function guardVerifyCommand(options = {}) {
     if (result.contractIssues.length > 0)
         fail(`contracts: ${result.contractIssues.length} invalid`);
     dim(`requirements: ${result.requirement.message}`);
-    process.exitCode = result.status === 'ok' ? 0 : 1;
+    process.exitCode = result.status === 'ok' && !attestationFailed ? 0 : 1;
 }
 export function guardCheckCommand(options = {}) {
     const root = getRoot();

package/dist/cli/index.js

@@ -44,6 +44,8 @@ guard
     .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('--fail-on-protected-changes', 'fail when protected verification paths change relative to base')
+    .option('--attestation-out <file>', 'write a passing verification as an in-toto statement')
     .option('--json')
     .action(guardVerifyCommand);
 guard

package/dist/core/guard.d.ts

@@ -3,12 +3,13 @@ import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findG
 import { type GuardImpactAnalysis } from './analysis/impact.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 type GuardOutcomeStatus = 'pass' | 'fail' | 'incomplete' | 'policy-weakened' | 'warning' | 'needs-review' | 'not-configured';
 export interface GuardOutcomeInput {
     configured?: boolean | undefined;
     errors?: number | undefined;
     warnings?: number | undefined;
     needsReview?: boolean | undefined;
+    incomplete?: boolean | undefined;
 }
 interface GuardStateLockOptions {
     waitMs?: number | undefined;
@@ -86,6 +87,30 @@ export interface GuardConfig {
     budgets?: GuardBudget[] | undefined;
     approval?: GuardApprovalPolicy | undefined;
     waiverPolicy?: GuardWaiverPolicy | undefined;
+    protectedPaths?: string[] | undefined;
+    policySurface?: GuardPolicySurfacePolicy | undefined;
+    githubActions?: GuardGitHubActionsPolicy | undefined;
+}
+export interface GuardPolicySurfacePolicy {
+    paths: {
+        pattern: string;
+        kind: 'ci-workflow' | 'guard-policy' | 'ownership' | 'dependency-input' | 'tool-config' | 'ignore-config' | 'suppression-source' | 'custom';
+        severity: 'warning' | 'error';
+    }[];
+}
+export interface GuardGitHubActionsPolicy {
+    workflows: {
+        path: string;
+        job: string;
+        requiredRunIncludes: string[];
+        requiredNeeds?: string[] | undefined;
+        requirePullRequest?: boolean | undefined;
+        requireUnfilteredPullRequest?: boolean | undefined;
+        requireUnconditionalJob?: boolean | undefined;
+        requireFullShaActions?: boolean | undefined;
+        disallowContinueOnError?: boolean | undefined;
+        maxPermissions?: Record<string, 'none' | 'read' | 'write'> | undefined;
+    }[];
 }
 export declare function getGuardPolicyMutationPolicy(guardConfig: GuardConfig | undefined): GuardPolicyMutationPolicy;
 export interface GuardApprovalPolicy {
@@ -155,8 +180,10 @@ export interface GuardAgentConfig {
         maxIterations: number;
         projectChecks: boolean;
         checks: ('lint' | 'typecheck' | 'test' | 'build')[];
+        requiredStages?: GuardRequiredStage[] | undefined;
     };
 }
+export type GuardRequiredStage = 'runtime' | 'project-checks' | 'adapters' | 'architecture-policy' | 'policy-surface' | 'ci-integrity' | 'verification-scope';
 export interface GuardFinding {
     ruleId: string;
     severity: GuardSeverity;

package/dist/core/guard.js

@@ -17,6 +17,8 @@ export function classifyGuardOutcome(input) {
         return 'fail';
     if (input.needsReview)
         return 'needs-review';
+    if (input.incomplete)
+        return 'incomplete';
     return (input.warnings ?? 0) > 0 ? 'warning' : 'pass';
 }
 export function getGuardPolicyMutationPolicy(guardConfig) {
@@ -129,6 +131,7 @@ export const defaultGuardAgentConfig = {
         maxIterations: 3,
         projectChecks: true,
         checks: ['lint', 'typecheck', 'test', 'build'],
+        requiredStages: ['architecture-policy'],
     },
 };
 export class GuardAlreadyInitializedError extends Error {
@@ -428,6 +431,40 @@ export function fingerprintGuardConfig(guardConfig) {
         contracts: [...(guardConfig.contracts ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
         budgets: [...(guardConfig.budgets ?? [])].sort((left, right) => left.id.localeCompare(right.id)),
         approval: guardConfig.approval ?? defaultGuardConfig.approval,
+        ...(guardConfig.protectedPaths !== undefined && guardConfig.protectedPaths.length > 0
+            ? { protectedPaths: [...guardConfig.protectedPaths].sort() }
+            : {}),
+        ...(guardConfig.policySurface
+            ? {
+                policySurface: {
+                    paths: [...guardConfig.policySurface.paths]
+                        .map((entry) => ({ ...entry, severity: entry.severity ?? 'error' }))
+                        .sort((left, right) => `${left.pattern}:${left.kind}:${left.severity}`.localeCompare(`${right.pattern}:${right.kind}:${right.severity}`)),
+                },
+            }
+            : {}),
+        ...(guardConfig.githubActions
+            ? {
+                githubActions: {
+                    workflows: guardConfig.githubActions.workflows
+                        .map((workflow) => ({
+                        ...workflow,
+                        requiredNeeds: workflow.requiredNeeds
+                            ? [...workflow.requiredNeeds].sort()
+                            : undefined,
+                        requirePullRequest: workflow.requirePullRequest ?? true,
+                        requireUnfilteredPullRequest: workflow.requireUnfilteredPullRequest ?? true,
+                        requireUnconditionalJob: workflow.requireUnconditionalJob ?? true,
+                        requireFullShaActions: workflow.requireFullShaActions ?? true,
+                        disallowContinueOnError: workflow.disallowContinueOnError ?? true,
+                        maxPermissions: workflow.maxPermissions
+                            ? Object.fromEntries(Object.entries(workflow.maxPermissions).sort(([left], [right]) => left.localeCompare(right)))
+                            : undefined,
+                    }))
+                        .sort((left, right) => `${left.path}:${left.job}`.localeCompare(`${right.path}:${right.job}`)),
+                },
+            }
+            : {}),
     }))
         .digest('hex');
 }

package/dist/core/history/runs.d.ts

@@ -17,6 +17,54 @@ export interface GuardVerificationReceiptCheck {
     status: 'passed' | 'failed' | 'not-configured';
     exitCode: number;
     durationMs: number;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    execution?: 'attempted' | 'rejected' | 'not-configured' | undefined;
+}
+export interface GuardVerificationReceiptPolicySurface {
+    protectedPaths: string[];
+    changedPaths: string[];
+    changes?: {
+        path: string;
+        pattern: string;
+        kind: string;
+        severity: 'warning' | 'error';
+    }[];
+    suppressionMarkers: string[];
+    workflowChanged: boolean;
+    complete: boolean;
+}
+export interface GuardVerificationScope {
+    algorithm: 'sha256';
+    fingerprint: string;
+    complete: boolean;
+    stable: boolean;
+    files: {
+        path: string;
+        status: 'present' | 'deleted' | 'unavailable';
+        sha256?: string | undefined;
+    }[];
+}
+export interface GuardVerificationCiIntegrity {
+    status: 'ok' | 'policy-weakened' | 'incomplete';
+    workflows: {
+        path: string;
+        job: string;
+        digest?: string | undefined;
+        baseDigest?: string | undefined;
+        actions: string[];
+        baseActions?: string[] | undefined;
+        actionChanges?: {
+            name: string;
+            base: string[];
+            current: string[];
+        }[] | undefined;
+        status: 'ok' | 'policy-weakened' | 'incomplete';
+        issues: {
+            code: string;
+            message: string;
+        }[];
+    }[];
 }
 export interface GuardVerificationReceipt {
     version: 1;
@@ -29,12 +77,25 @@ export interface GuardVerificationReceipt {
         commit?: string | undefined;
         baseRef?: string | undefined;
         baseCommit?: string | undefined;
+        headSha?: string | undefined;
+        baseSha?: string | undefined;
+        mergeSha?: string | undefined;
+        githubEvent?: string | undefined;
         changedFiles: string[];
         baseChangedFiles?: string[] | undefined;
         workingTreeFiles?: string[] | undefined;
         workingTreeDirty: boolean;
     };
     policy?: GuardRunPolicy | undefined;
+    verificationScope?: GuardVerificationScope | undefined;
+    policySurface?: GuardVerificationReceiptPolicySurface | undefined;
+    ciIntegrity?: GuardVerificationCiIntegrity | undefined;
+    requiredStages?: string[] | undefined;
+    incompleteStages?: string[] | undefined;
+    effectiveInvocation?: {
+        command: string;
+        args: string[];
+    } | undefined;
     stages: Record<string, 'ok' | 'fail' | 'skipped'>;
     checks: Record<string, GuardVerificationReceiptCheck>;
     findings: {
@@ -61,7 +122,7 @@ export interface GuardRunManifest {
     startedAt: string;
     completedAt: string;
     durationMs: number;
-    outcome: 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
+    outcome: 'pass' | 'fail' | 'incomplete' | 'policy-weakened' | 'warning' | 'needs-review' | 'not-configured';
     gate: string;
     stages: Record<string, GuardRunStage>;
     commit?: string | undefined;
@@ -78,6 +139,8 @@ export interface GuardRunSummary {
     total: number;
     passed: number;
     failed: number;
+    incomplete: number;
+    policyWeakened: number;
     warnings: number;
     averageDurationMs: number;
     last?: GuardRunManifest | undefined;