@codapult/guard 0.9.0 → 0.11.0

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

@@ -13,6 +13,108 @@ export interface GuardRunPolicy {
     changedFromBase?: boolean | undefined;
     decisionIds?: string[] | undefined;
 }
+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;
+    kind: 'verification-receipt';
+    runId: string;
+    generatedAt: string;
+    outcome: GuardRunManifest['outcome'];
+    gate: string;
+    subject: {
+        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: {
+        total: number;
+        errors: number;
+        warnings: number;
+        waived: number;
+        waiverWarnings: number;
+        expiredWaivers: number;
+        fingerprints: string[];
+        ruleIds: string[];
+    };
+    contractIssues: string[];
+    decisionIds: string[];
+    tool: {
+        name: string;
+        version: string;
+    };
+}
 export interface GuardRunManifest {
     version: 1;
     runId: string;
@@ -20,11 +122,12 @@ 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;
     policy?: GuardRunPolicy | undefined;
+    receipt?: GuardVerificationReceipt | undefined;
 }
 export interface GuardRunContext {
     runId: string;
@@ -36,6 +139,8 @@ export interface GuardRunSummary {
     total: number;
     passed: number;
     failed: number;
+    incomplete: number;
+    policyWeakened: number;
     warnings: number;
     averageDurationMs: number;
     last?: GuardRunManifest | undefined;
@@ -49,4 +154,4 @@ export declare function writeGuardRun(root: string, manifest: GuardRunManifest):
 /** Reads locally persisted run manifests without reaching a remote service. */
 export declare function listGuardRuns(root: string, limit?: number): GuardRunManifest[];
 export declare function summarizeGuardRuns(root: string, limit?: number): GuardRunSummary;
-export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy): GuardRunManifest;
+export declare function finishGuardRun(root: string, context: GuardRunContext, outcome: GuardRunManifest['outcome'], gate: string, command?: string, policy?: GuardRunPolicy, receipt?: Omit<GuardVerificationReceipt, 'runId' | 'generatedAt' | 'outcome' | 'gate' | 'subject'> & Pick<GuardVerificationReceipt, 'subject'>): GuardRunManifest;

package/dist/core/history/runs.js

@@ -12,11 +12,208 @@ export class GuardRunManifestError extends Error {
         this.name = 'GuardRunManifestError';
     }
 }
+function isGuardRunPolicy(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const policy = value;
+    return (typeof policy.fingerprint === 'string' &&
+        policy.fingerprint.length > 0 &&
+        (policy.source === 'working-tree' || policy.source === 'git-ref') &&
+        (policy.revision === undefined ||
+            (Number.isInteger(policy.revision) && policy.revision >= 0)) &&
+        (policy.ref === undefined || typeof policy.ref === 'string') &&
+        (policy.changedFromBase === undefined || typeof policy.changedFromBase === 'boolean') &&
+        (policy.decisionIds === undefined ||
+            (Array.isArray(policy.decisionIds) &&
+                new Set(policy.decisionIds).size === policy.decisionIds.length &&
+                policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0) &&
+                (policy.source === 'working-tree' || policy.decisionIds.length === 0))));
+}
 function isGuardRunManifest(value) {
     if (value === null || typeof value !== 'object')
         return false;
     const manifest = value;
     const stages = manifest.stages;
+    const receipt = manifest.receipt;
+    const validReceipt = receipt === undefined ||
+        (receipt !== null &&
+            typeof receipt === 'object' &&
+            receipt.version === 1 &&
+            receipt.kind === 'verification-receipt' &&
+            typeof receipt.runId === 'string' &&
+            receipt.runId === manifest.runId &&
+            typeof receipt.generatedAt === 'string' &&
+            Number.isFinite(Date.parse(receipt.generatedAt)) &&
+            (receipt.outcome === 'pass' ||
+                receipt.outcome === 'fail' ||
+                receipt.outcome === 'incomplete' ||
+                receipt.outcome === 'policy-weakened' ||
+                receipt.outcome === 'warning' ||
+                receipt.outcome === 'needs-review' ||
+                receipt.outcome === 'not-configured') &&
+            typeof receipt.gate === 'string' &&
+            receipt.subject !== null &&
+            typeof receipt.subject === 'object' &&
+            Array.isArray(receipt.subject.changedFiles) &&
+            receipt.subject.changedFiles.every((file) => typeof file === 'string') &&
+            (receipt.subject.baseChangedFiles === undefined ||
+                (Array.isArray(receipt.subject.baseChangedFiles) &&
+                    receipt.subject.baseChangedFiles.every((file) => typeof file === 'string'))) &&
+            (receipt.subject.workingTreeFiles === undefined ||
+                (Array.isArray(receipt.subject.workingTreeFiles) &&
+                    receipt.subject.workingTreeFiles.every((file) => typeof file === 'string'))) &&
+            typeof receipt.subject.workingTreeDirty === 'boolean' &&
+            (receipt.subject.commit === undefined || typeof receipt.subject.commit === 'string') &&
+            (receipt.subject.baseRef === undefined || typeof receipt.subject.baseRef === 'string') &&
+            (receipt.subject.baseCommit === undefined ||
+                typeof receipt.subject.baseCommit === 'string') &&
+            (receipt.subject.headSha === undefined || /^[a-f0-9]{40}$/i.test(receipt.subject.headSha)) &&
+            (receipt.subject.baseSha === undefined || /^[a-f0-9]{40}$/i.test(receipt.subject.baseSha)) &&
+            (receipt.subject.mergeSha === undefined ||
+                /^[a-f0-9]{40}$/i.test(receipt.subject.mergeSha)) &&
+            (receipt.subject.githubEvent === undefined ||
+                typeof receipt.subject.githubEvent === 'string') &&
+            (receipt.policy === undefined || isGuardRunPolicy(receipt.policy)) &&
+            (receipt.verificationScope === undefined ||
+                (receipt.verificationScope !== null &&
+                    typeof receipt.verificationScope === 'object' &&
+                    receipt.verificationScope.algorithm === 'sha256' &&
+                    /^[a-f0-9]{64}$/.test(receipt.verificationScope.fingerprint) &&
+                    typeof receipt.verificationScope.complete === 'boolean' &&
+                    typeof receipt.verificationScope.stable === 'boolean' &&
+                    Array.isArray(receipt.verificationScope.files) &&
+                    receipt.verificationScope.files.every((file) => file !== null &&
+                        typeof file === 'object' &&
+                        typeof file.path === 'string' &&
+                        (file.status === 'present' ||
+                            file.status === 'deleted' ||
+                            file.status === 'unavailable') &&
+                        (file.status === 'unavailable'
+                            ? file.sha256 === undefined
+                            : typeof file.sha256 === 'string' && /^[a-f0-9]{64}$/.test(file.sha256))))) &&
+            (receipt.policySurface === undefined ||
+                (receipt.policySurface !== null &&
+                    typeof receipt.policySurface === 'object' &&
+                    Array.isArray(receipt.policySurface.protectedPaths) &&
+                    receipt.policySurface.protectedPaths.every((path) => typeof path === 'string') &&
+                    Array.isArray(receipt.policySurface.changedPaths) &&
+                    receipt.policySurface.changedPaths.every((path) => typeof path === 'string') &&
+                    (receipt.policySurface.changes === undefined ||
+                        (Array.isArray(receipt.policySurface.changes) &&
+                            receipt.policySurface.changes.every((change) => change !== null &&
+                                typeof change === 'object' &&
+                                typeof change.path === 'string' &&
+                                typeof change.pattern === 'string' &&
+                                typeof change.kind === 'string' &&
+                                (change.severity === 'warning' || change.severity === 'error')))) &&
+                    Array.isArray(receipt.policySurface.suppressionMarkers) &&
+                    receipt.policySurface.suppressionMarkers.every((marker) => typeof marker === 'string') &&
+                    typeof receipt.policySurface.workflowChanged === 'boolean' &&
+                    typeof receipt.policySurface.complete === 'boolean')) &&
+            (receipt.ciIntegrity === undefined ||
+                (receipt.ciIntegrity !== null &&
+                    typeof receipt.ciIntegrity === 'object' &&
+                    (receipt.ciIntegrity.status === 'ok' ||
+                        receipt.ciIntegrity.status === 'policy-weakened' ||
+                        receipt.ciIntegrity.status === 'incomplete') &&
+                    Array.isArray(receipt.ciIntegrity.workflows) &&
+                    receipt.ciIntegrity.workflows.every((workflow) => workflow !== null &&
+                        typeof workflow === 'object' &&
+                        typeof workflow.path === 'string' &&
+                        typeof workflow.job === 'string' &&
+                        (workflow.digest === undefined || typeof workflow.digest === 'string') &&
+                        (workflow.baseDigest === undefined || typeof workflow.baseDigest === 'string') &&
+                        Array.isArray(workflow.actions) &&
+                        workflow.actions.every((action) => typeof action === 'string') &&
+                        (workflow.baseActions === undefined ||
+                            (Array.isArray(workflow.baseActions) &&
+                                workflow.baseActions.every((action) => typeof action === 'string'))) &&
+                        (workflow.actionChanges === undefined ||
+                            (Array.isArray(workflow.actionChanges) &&
+                                workflow.actionChanges.every((change) => change !== null &&
+                                    typeof change === 'object' &&
+                                    typeof change.name === 'string' &&
+                                    Array.isArray(change.base) &&
+                                    change.base.every((action) => typeof action === 'string') &&
+                                    Array.isArray(change.current) &&
+                                    change.current.every((action) => typeof action === 'string')))) &&
+                        (workflow.status === 'ok' ||
+                            workflow.status === 'policy-weakened' ||
+                            workflow.status === 'incomplete') &&
+                        Array.isArray(workflow.issues) &&
+                        workflow.issues.every((issue) => issue !== null &&
+                            typeof issue === 'object' &&
+                            typeof issue.code === 'string' &&
+                            typeof issue.message === 'string')))) &&
+            (receipt.requiredStages === undefined ||
+                (Array.isArray(receipt.requiredStages) &&
+                    receipt.requiredStages.every((stage) => typeof stage === 'string'))) &&
+            (receipt.incompleteStages === undefined ||
+                (Array.isArray(receipt.incompleteStages) &&
+                    receipt.incompleteStages.every((stage) => typeof stage === 'string'))) &&
+            (receipt.effectiveInvocation === undefined ||
+                (receipt.effectiveInvocation !== null &&
+                    typeof receipt.effectiveInvocation === 'object' &&
+                    typeof receipt.effectiveInvocation.command === 'string' &&
+                    Array.isArray(receipt.effectiveInvocation.args) &&
+                    receipt.effectiveInvocation.args.every((argument) => typeof argument === 'string'))) &&
+            receipt.stages !== null &&
+            typeof receipt.stages === 'object' &&
+            !Array.isArray(receipt.stages) &&
+            Object.values(receipt.stages).every((status) => status === 'ok' || status === 'fail' || status === 'skipped') &&
+            receipt.checks !== null &&
+            typeof receipt.checks === 'object' &&
+            !Array.isArray(receipt.checks) &&
+            Object.values(receipt.checks).every((check) => {
+                if (check === null || typeof check !== 'object')
+                    return false;
+                const candidate = check;
+                return ((candidate.status === 'passed' ||
+                    candidate.status === 'failed' ||
+                    candidate.status === 'not-configured') &&
+                    (candidate.command === undefined || typeof candidate.command === 'string') &&
+                    (candidate.args === undefined ||
+                        (Array.isArray(candidate.args) &&
+                            candidate.args.every((argument) => typeof argument === 'string'))) &&
+                    (candidate.execution === undefined ||
+                        candidate.execution === 'attempted' ||
+                        candidate.execution === 'rejected' ||
+                        candidate.execution === 'not-configured') &&
+                    Number.isInteger(candidate.exitCode) &&
+                    typeof candidate.durationMs === 'number' &&
+                    Number.isFinite(candidate.durationMs) &&
+                    candidate.durationMs >= 0);
+            }) &&
+            receipt.findings !== null &&
+            typeof receipt.findings === 'object' &&
+            ['total', 'errors', 'warnings', 'waived', 'waiverWarnings', 'expiredWaivers'].every((key) => {
+                const countValue = receipt.findings[key];
+                return typeof countValue === 'number' && Number.isInteger(countValue) && countValue >= 0;
+            }) &&
+            Array.isArray(receipt.findings.fingerprints) &&
+            receipt.findings.fingerprints.every((fingerprint) => typeof fingerprint === 'string') &&
+            Array.isArray(receipt.findings.ruleIds) &&
+            receipt.findings.ruleIds.every((ruleId) => typeof ruleId === 'string') &&
+            Array.isArray(receipt.contractIssues) &&
+            receipt.contractIssues.every((issue) => typeof issue === 'string') &&
+            Array.isArray(receipt.decisionIds) &&
+            new Set(receipt.decisionIds).size === receipt.decisionIds.length &&
+            receipt.decisionIds.every((decisionId) => typeof decisionId === 'string') &&
+            receipt.tool !== null &&
+            typeof receipt.tool === 'object' &&
+            typeof receipt.tool.name === 'string' &&
+            typeof receipt.tool.version === 'string');
+    const receiptMatchesManifest = receipt === undefined ||
+        (receipt.outcome === manifest.outcome &&
+            receipt.gate === manifest.gate &&
+            (manifest.commit === undefined
+                ? receipt.subject.commit === undefined
+                : receipt.subject.commit === manifest.commit) &&
+            (manifest.policy === undefined
+                ? receipt.policy === undefined
+                : receipt.policy?.fingerprint === manifest.policy.fingerprint &&
+                    receipt.policy.source === manifest.policy.source &&
+                    receipt.policy.revision === manifest.policy.revision));
     const validStages = stages !== null &&
         typeof stages === 'object' &&
         !Array.isArray(stages) &&
@@ -46,27 +243,16 @@ function isGuardRunManifest(value) {
         manifest.durationMs >= 0 &&
         (manifest.outcome === 'pass' ||
             manifest.outcome === 'fail' ||
+            manifest.outcome === 'incomplete' ||
+            manifest.outcome === 'policy-weakened' ||
             manifest.outcome === 'warning' ||
             manifest.outcome === 'needs-review' ||
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
         validStages &&
-        (manifest.policy === undefined ||
-            (manifest.policy !== null &&
-                typeof manifest.policy === 'object' &&
-                typeof manifest.policy.fingerprint === 'string' &&
-                manifest.policy.fingerprint.length > 0 &&
-                (manifest.policy.source === 'working-tree' || manifest.policy.source === 'git-ref') &&
-                (manifest.policy.revision === undefined ||
-                    (Number.isInteger(manifest.policy.revision) && manifest.policy.revision >= 0)) &&
-                (manifest.policy.ref === undefined || typeof manifest.policy.ref === 'string') &&
-                (manifest.policy.changedFromBase === undefined ||
-                    typeof manifest.policy.changedFromBase === 'boolean') &&
-                (manifest.policy.decisionIds === undefined ||
-                    (manifest.policy.source === 'working-tree' &&
-                        Array.isArray(manifest.policy.decisionIds) &&
-                        new Set(manifest.policy.decisionIds).size === manifest.policy.decisionIds.length &&
-                        manifest.policy.decisionIds.every((decisionId) => typeof decisionId === 'string' && decisionId.trim().length > 0))))));
+        validReceipt &&
+        receiptMatchesManifest &&
+        (manifest.policy === undefined || isGuardRunPolicy(manifest.policy)));
 }
 export function startGuardRun() {
     return {
@@ -172,12 +358,14 @@ export function summarizeGuardRuns(root, limit = 100) {
         total,
         passed: runs.filter((run) => run.outcome === 'pass').length,
         failed: runs.filter((run) => run.outcome === 'fail').length,
+        incomplete: runs.filter((run) => run.outcome === 'incomplete').length,
+        policyWeakened: runs.filter((run) => run.outcome === 'policy-weakened').length,
         warnings: runs.filter((run) => run.outcome === 'warning').length,
         averageDurationMs: total === 0 ? 0 : Math.round(runs.reduce((sum, run) => sum + run.durationMs, 0) / total),
         ...(total > 0 ? { last: runs[0] } : {}),
     };
 }
-export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy) {
+export function finishGuardRun(root, context, outcome, gate, command = 'verify', policy, receipt) {
     let commit;
     try {
         commit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: root, stdio: 'pipe' })
@@ -187,18 +375,56 @@ export function finishGuardRun(root, context, outcome, gate, command = 'verify',
     catch {
         commit = undefined;
     }
+    const completedAt = new Date().toISOString();
+    const completedReceipt = {
+        version: 1,
+        kind: 'verification-receipt',
+        runId: context.runId,
+        generatedAt: completedAt,
+        outcome,
+        gate,
+        subject: {
+            ...receipt?.subject,
+            ...(commit ? { commit } : {}),
+            changedFiles: receipt?.subject.changedFiles ?? [],
+            workingTreeDirty: receipt?.subject.workingTreeDirty ?? false,
+        },
+        ...(policy ? { policy } : {}),
+        ...(receipt?.verificationScope ? { verificationScope: receipt.verificationScope } : {}),
+        ...(receipt?.policySurface ? { policySurface: receipt.policySurface } : {}),
+        ...(receipt?.ciIntegrity ? { ciIntegrity: receipt.ciIntegrity } : {}),
+        requiredStages: receipt?.requiredStages ?? [],
+        incompleteStages: receipt?.incompleteStages ?? [],
+        ...(receipt?.effectiveInvocation ? { effectiveInvocation: receipt.effectiveInvocation } : {}),
+        stages: receipt?.stages ?? {},
+        checks: receipt?.checks ?? {},
+        findings: receipt?.findings ?? {
+            total: 0,
+            errors: 0,
+            warnings: 0,
+            waived: 0,
+            waiverWarnings: 0,
+            expiredWaivers: 0,
+            fingerprints: [],
+            ruleIds: [],
+        },
+        contractIssues: receipt?.contractIssues ?? [],
+        decisionIds: receipt?.decisionIds ?? policy?.decisionIds ?? [],
+        tool: receipt?.tool ?? { name: '@codapult/guard', version: 'unknown' },
+    };
     const manifest = {
         version: 1,
         runId: context.runId,
         command,
         startedAt: context.startedAt,
-        completedAt: new Date().toISOString(),
+        completedAt,
         durationMs: Math.max(0, Date.now() - context.startedAtMs),
         outcome,
         gate,
         stages: context.stages,
         ...(commit ? { commit } : {}),
         ...(policy ? { policy } : {}),
+        receipt: completedReceipt,
     };
     try {
         writeGuardRun(root, manifest);

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

@@ -0,0 +1,17 @@
+import type { GuardVerificationReceipt } from '../history/runs.js';
+export declare const GUARD_VERIFICATION_PREDICATE_TYPE = "https://codapult.dev/attestations/guard-verification/v1";
+export interface GuardVerificationInTotoStatement {
+    _type: 'https://in-toto.io/Statement/v1';
+    subject: {
+        name: 'codapult-guard:verification-context';
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: typeof GUARD_VERIFICATION_PREDICATE_TYPE;
+    predicate: {
+        receipt: GuardVerificationReceipt;
+    };
+}
+/** Bind a successful Guard receipt to the exact policy and file scope it verified. */
+export declare function guardReceiptToInToto(receipt: GuardVerificationReceipt): GuardVerificationInTotoStatement;

package/dist/core/output/attestation.js

@@ -0,0 +1,22 @@
+export const GUARD_VERIFICATION_PREDICATE_TYPE = 'https://codapult.dev/attestations/guard-verification/v1';
+/** Bind a successful Guard receipt to the exact policy and file scope it verified. */
+export function guardReceiptToInToto(receipt) {
+    const scope = receipt.verificationScope;
+    if (receipt.outcome !== 'pass' ||
+        !scope?.complete ||
+        !scope.stable ||
+        !/^[a-f0-9]{64}$/.test(scope.fingerprint)) {
+        throw new Error('Only a passing receipt with a complete, stable verification scope can be attested.');
+    }
+    return {
+        _type: 'https://in-toto.io/Statement/v1',
+        subject: [
+            {
+                name: 'codapult-guard:verification-context',
+                digest: { sha256: scope.fingerprint },
+            },
+        ],
+        predicateType: GUARD_VERIFICATION_PREDICATE_TYPE,
+        predicate: { receipt },
+    };
+}

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

@@ -226,6 +226,44 @@ export declare const guardConfigSchema: z.ZodObject<{
         warningDays: z.ZodNumber;
         maxDays: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    protectedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    policySurface: z.ZodOptional<z.ZodObject<{
+        paths: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodString;
+            kind: z.ZodEnum<{
+                "ci-workflow": "ci-workflow";
+                custom: "custom";
+                "dependency-input": "dependency-input";
+                "guard-policy": "guard-policy";
+                "ignore-config": "ignore-config";
+                ownership: "ownership";
+                "suppression-source": "suppression-source";
+                "tool-config": "tool-config";
+            }>;
+            severity: z.ZodDefault<z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    githubActions: z.ZodOptional<z.ZodObject<{
+        workflows: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            job: z.ZodString;
+            requiredRunIncludes: z.ZodArray<z.ZodString>;
+            requiredNeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requirePullRequest: z.ZodDefault<z.ZodBoolean>;
+            requireUnfilteredPullRequest: z.ZodDefault<z.ZodBoolean>;
+            requireUnconditionalJob: z.ZodDefault<z.ZodBoolean>;
+            requireFullShaActions: z.ZodDefault<z.ZodBoolean>;
+            disallowContinueOnError: z.ZodDefault<z.ZodBoolean>;
+            maxPermissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                none: "none";
+                read: "read";
+                write: "write";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const guardContractsFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -408,5 +446,14 @@ export declare const guardAgentConfigSchema: z.ZodObject<{
             test: "test";
             typecheck: "typecheck";
         }>>;
+        requiredStages: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            adapters: "adapters";
+            "architecture-policy": "architecture-policy";
+            "ci-integrity": "ci-integrity";
+            "policy-surface": "policy-surface";
+            "project-checks": "project-checks";
+            runtime: "runtime";
+            "verification-scope": "verification-scope";
+        }>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;

package/dist/core/policy/schemas.js

@@ -89,6 +89,61 @@ export const guardConfigSchema = z.object({
         path: ['maxDays'],
     })
         .optional(),
+    protectedPaths: z
+        .array(z
+        .string()
+        .trim()
+        .min(1)
+        .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'protectedPaths entries must be repository-relative paths without parent traversal'))
+        .optional(),
+    policySurface: z
+        .object({
+        paths: z
+            .array(z.object({
+            pattern: z
+                .string()
+                .trim()
+                .min(1)
+                .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'policySurface paths must be repository-relative without parent traversal'),
+            kind: z.enum([
+                'ci-workflow',
+                'guard-policy',
+                'ownership',
+                'dependency-input',
+                'tool-config',
+                'ignore-config',
+                'suppression-source',
+                'custom',
+            ]),
+            severity: z.enum(['warning', 'error']).default('error'),
+        }))
+            .default([]),
+    })
+        .optional(),
+    githubActions: z
+        .object({
+        workflows: z
+            .array(z.object({
+            path: z
+                .string()
+                .trim()
+                .min(1)
+                .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'GitHub Actions workflow paths must be repository-relative without parent traversal'),
+            job: z.string().trim().min(1),
+            requiredRunIncludes: z.array(z.string().trim().min(1)).min(1),
+            requiredNeeds: z.array(z.string().trim().min(1)).optional(),
+            requirePullRequest: z.boolean().default(true),
+            requireUnfilteredPullRequest: z.boolean().default(true),
+            requireUnconditionalJob: z.boolean().default(true),
+            requireFullShaActions: z.boolean().default(true),
+            disallowContinueOnError: z.boolean().default(true),
+            maxPermissions: z
+                .record(z.string().trim().min(1), z.enum(['none', 'read', 'write']))
+                .optional(),
+        }))
+            .min(1),
+    })
+        .optional(),
 });
 export const guardContractsFileSchema = z.object({
     version: z.literal(1),
@@ -167,5 +222,17 @@ export const guardAgentConfigSchema = z.object({
         maxIterations: z.number().int().min(1).max(10),
         projectChecks: z.boolean(),
         checks: z.array(z.enum(['lint', 'typecheck', 'test', 'build'])),
+        requiredStages: z
+            .array(z.enum([
+            'runtime',
+            'project-checks',
+            'adapters',
+            'architecture-policy',
+            'policy-surface',
+            'ci-integrity',
+            'verification-scope',
+        ]))
+            .min(1)
+            .default(['architecture-policy']),
     }),
 });

package/dist/core/verification/github-actions.d.ts

@@ -0,0 +1,25 @@
+import type { GuardGitHubActionsPolicy } from '../guard.js';
+export interface GuardCiIntegrityIssue {
+    code: 'workflow-unreadable' | 'workflow-invalid' | 'pull-request-trigger-missing' | 'pull-request-filtered' | 'pull-request-target-present' | 'job-missing' | 'job-conditional' | 'command-missing' | 'step-conditional' | 'continue-on-error' | 'dependency-missing' | 'dependency-conditional' | 'dependency-continue-on-error' | 'action-not-sha-pinned' | 'action-reference-changed' | 'base-workflow-unavailable' | 'permission-expansion';
+    message: string;
+}
+export interface GuardCiIntegrityWorkflowResult {
+    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: GuardCiIntegrityIssue[];
+}
+export interface GuardCiIntegrityResult {
+    status: 'ok' | 'policy-weakened' | 'incomplete';
+    workflows: GuardCiIntegrityWorkflowResult[];
+}
+export declare function auditGitHubActions(root: string, policy: GuardGitHubActionsPolicy | undefined, baseRef?: string): GuardCiIntegrityResult | undefined;