@codapult/guard 0.8.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
@@ -519,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/core/audit/governance.js

@@ -152,7 +152,7 @@ function auditGuardGovernanceUnlocked(root) {
         reachability: {
             approvedWithPolicyFingerprint,
             approvedLinkedToRun,
-            approvedWithoutRun: approvedWithPolicyFingerprint - approvedLinkedToRun,
+            approvedWithoutRun: approved.length - approvedLinkedToRun,
             runsWithPolicy: runs.filter((run) => run.policy !== undefined).length,
             runsWithoutPolicy: runs.filter((run) => run.policy === undefined).length,
         },

package/dist/core/guard.d.ts

@@ -247,6 +247,11 @@ export interface GuardPolicySnapshot {
     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.
  *
@@ -278,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>;

package/dist/core/guard.js

@@ -597,6 +597,25 @@ export function loadGuardWaivers(root) {
         return readGuardWaiversUnlocked(root).waivers;
     return withGuardStateLock(root, () => readGuardWaiversUnlocked(root).waivers);
 }
+function readGuardWorkingTreePolicyUnlocked(root) {
+    recoverGuardPolicyTransaction(root);
+    const guardConfig = readGuardConfigFilesUnlocked(root);
+    if (!guardConfig)
+        return undefined;
+    const baseline = loadBaseline(root);
+    const waivers = readGuardWaiversUnlocked(root).waivers;
+    const agentConfig = loadGuardAgentConfig(root);
+    return {
+        config: guardConfig,
+        snapshot: createGuardPolicySnapshot(guardConfig, baseline, waivers, 'working-tree', undefined, agentConfig),
+        proposals: loadGuardProposalsUnlocked(root),
+    };
+}
+export function loadGuardWorkingTreePolicy(root) {
+    if (!existsSync(resolve(root, GUARD_DIR)))
+        return readGuardWorkingTreePolicyUnlocked(root);
+    return withGuardStateLock(root, () => readGuardWorkingTreePolicyUnlocked(root));
+}
 export function writeGuardWaivers(root) {
     withGuardStateLock(root, () => {
         const file = { version: 1, waivers: [], decisions: [] };

package/dist/core/history/runs.js

@@ -15,6 +15,22 @@ function isGuardRunManifest(value) {
     if (value === null || typeof value !== 'object')
         return false;
     const manifest = value;
+    const stages = manifest.stages;
+    const validStages = stages !== null &&
+        typeof stages === 'object' &&
+        !Array.isArray(stages) &&
+        Object.values(stages).every((stage) => {
+            if (stage === null || typeof stage !== 'object')
+                return false;
+            const candidate = stage;
+            return (typeof candidate.durationMs === 'number' &&
+                Number.isFinite(candidate.durationMs) &&
+                candidate.durationMs >= 0 &&
+                (candidate.status === 'ok' ||
+                    candidate.status === 'fail' ||
+                    candidate.status === 'skipped') &&
+                (candidate.detail === undefined || typeof candidate.detail === 'string'));
+        });
     return (manifest.version === 1 &&
         typeof manifest.runId === 'string' &&
         /^guard-[A-Za-z0-9-]+$/.test(manifest.runId) &&
@@ -23,6 +39,7 @@ function isGuardRunManifest(value) {
         Number.isFinite(Date.parse(manifest.startedAt)) &&
         typeof manifest.completedAt === 'string' &&
         Number.isFinite(Date.parse(manifest.completedAt)) &&
+        Date.parse(manifest.completedAt) >= Date.parse(manifest.startedAt) &&
         typeof manifest.durationMs === 'number' &&
         Number.isFinite(manifest.durationMs) &&
         manifest.durationMs >= 0 &&
@@ -32,8 +49,7 @@ function isGuardRunManifest(value) {
             manifest.outcome === 'needs-review' ||
             manifest.outcome === 'not-configured') &&
         typeof manifest.gate === 'string' &&
-        manifest.stages !== null &&
-        typeof manifest.stages === 'object' &&
+        validStages &&
         (manifest.policy === undefined ||
             (manifest.policy !== null &&
                 typeof manifest.policy === 'object' &&
@@ -46,7 +62,8 @@ function isGuardRunManifest(value) {
                 (manifest.policy.changedFromBase === undefined ||
                     typeof manifest.policy.changedFromBase === 'boolean') &&
                 (manifest.policy.decisionIds === undefined ||
-                    (Array.isArray(manifest.policy.decisionIds) &&
+                    (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))))));
 }

package/dist/core/policy/schemas.js

@@ -94,7 +94,8 @@ export const guardContractsFileSchema = z.object({
     version: z.literal(1),
     contracts: z.array(guardContractSchema),
 });
-export const guardProposalDecisionSchema = z.object({
+export const guardProposalDecisionSchema = z
+    .object({
     decisionId: z.string().trim().min(1).optional(),
     id: z.string().trim().min(1),
     type: z.enum(['rule', 'contract']),
@@ -105,12 +106,29 @@ export const guardProposalDecisionSchema = z.object({
     revision: z.number().optional(),
     source: z.enum(['cli', 'mcp', 'external']).optional(),
     proposalAuthor: z.string().trim().min(1).optional(),
-    actor: z.string().optional(),
-    commit: z.string().optional(),
+    actor: z.string().trim().min(1).optional(),
+    commit: z.string().trim().min(1).optional(),
     policyFingerprint: z.string().trim().min(1).optional(),
     policyRevision: z.number().int().nonnegative().optional(),
+})
+    .superRefine((decision, context) => {
+    if (decision.policyFingerprint !== undefined && decision.decision !== 'approved') {
+        context.addIssue({
+            code: 'custom',
+            message: 'policyFingerprint is only valid for approved decisions.',
+            path: ['policyFingerprint'],
+        });
+    }
+    if (decision.policyRevision !== undefined && decision.policyFingerprint === undefined) {
+        context.addIssue({
+            code: 'custom',
+            message: 'policyRevision requires policyFingerprint.',
+            path: ['policyRevision'],
+        });
+    }
 });
-export const guardProposalSchema = z.object({
+export const guardProposalSchema = z
+    .object({
     version: z.literal(1),
     generatedAt: z.string(),
     generatedBy: z.string().trim().min(1).optional(),
@@ -122,6 +140,21 @@ export const guardProposalSchema = z.object({
     contracts: z.array(guardContractSchema),
     questions: z.array(z.string()),
     decisions: z.array(guardProposalDecisionSchema).optional(),
+})
+    .superRefine((proposal, context) => {
+    const decisionIds = new Set();
+    for (const [index, decision] of (proposal.decisions ?? []).entries()) {
+        if (decision.decisionId === undefined)
+            continue;
+        if (decisionIds.has(decision.decisionId)) {
+            context.addIssue({
+                code: 'custom',
+                message: 'decisionId values must be unique.',
+                path: ['decisions', index, 'decisionId'],
+            });
+        }
+        decisionIds.add(decision.decisionId);
+    }
 });
 export const guardAgentConfigSchema = z.object({
     version: z.literal(1),

package/dist/core/verification/verify.js

@@ -1,6 +1,6 @@
 import {} from '../../adapters/command.js';
 import { runProjectAdapters, runProjectChecks, runWorkspaceProjectChecks, inspectProjectRuntime, } from '../../adapters/project-checks.js';
-import { loadBaseline, loadGuardPolicyAtRevision, createGuardPolicySnapshot, loadGuardWaivers, loadGuardAgentConfig, loadGuardConfig, loadGuardProposals, scanGuard, classifyGuardOutcome, validateGuardPolicy, } from '../guard.js';
+import { loadGuardPolicyAtRevision, loadGuardWorkingTreePolicy, scanGuard, classifyGuardOutcome, validateGuardPolicy, } from '../guard.js';
 import { analyzeProjectImpact } from '../analysis/impact.js';
 import { discoverProject } from '../discovery/discovery.js';
 import { finishGuardRun, recordGuardRunStage, startGuardRun, } from '../history/runs.js';
@@ -43,9 +43,9 @@ export function runGuardVerification(root, options = {}) {
             run,
         };
     }
-    let config;
+    let workingTreeState;
     try {
-        config = loadGuardConfig(root);
+        workingTreeState = loadGuardWorkingTreePolicy(root);
     }
     catch (error) {
         const run = finishGuardRun(root, runContext, 'fail', 'configuration');
@@ -64,7 +64,7 @@ export function runGuardVerification(root, options = {}) {
             run,
         };
     }
-    if (!config) {
+    if (!workingTreeState) {
         const run = finishGuardRun(root, runContext, 'not-configured', 'configuration');
         return {
             status: 'not-configured',
@@ -85,7 +85,7 @@ export function runGuardVerification(root, options = {}) {
     let policyChanged;
     let policyDecisionIds = [];
     try {
-        workingTreeSnapshot = createGuardPolicySnapshot(config, loadBaseline(root), loadGuardWaivers(root), 'working-tree', undefined, loadGuardAgentConfig(root));
+        workingTreeSnapshot = workingTreeState.snapshot;
         const baseSnapshot = options.policyBase
             ? loadGuardPolicyAtRevision(root, options.policyBase)
             : undefined;
@@ -110,7 +110,7 @@ export function runGuardVerification(root, options = {}) {
         policyChanged =
             baseSnapshot !== undefined && baseSnapshot.fingerprint !== workingTreeSnapshot.fingerprint;
         if (policySnapshot.source === 'working-tree') {
-            policyDecisionIds = (loadGuardProposals(root)?.decisions ?? [])
+            policyDecisionIds = (workingTreeState.proposals?.decisions ?? [])
                 .filter((decision) => decision.policyFingerprint === policySnapshot.fingerprint)
                 .map((decision) => decision.decisionId ??
                 `${decision.proposalId ?? 'unknown'}:${decision.type}:${decision.id}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codapult/guard",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "mcpName": "io.github.codapult/guard",
   "description": "Local-first architecture guardrails for JavaScript and TypeScript projects, with first-class support for Next.js SaaS and AI-assisted development",
   "license": "MIT",