Merge pull request #153 from LAA-Software-Engineering/feat/118-policy-snapshot

feat(policy): compile immutable digest-checked policy snapshots (#118)

Author: leo-aa88

internal/cli/apply.go

@@ -97,7 +97,7 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 		if err := writeApplyEmptyOutput(cmd, env, dsn, pl, rc, g); err != nil {
 			return err
 		}
-		return config.WriteSnapshot(rc)
+		return persistSnapshots(rc)
 	}
 
 	if g.Output != render.FormatTable {
@@ -137,7 +137,7 @@ func runApply(cmd *cobra.Command, flagAutoApprove bool) error {
 	if err := writeApplySuccessOutput(cmd, env, dsn, pl, rc, g, at); err != nil {
 		return err
 	}
-	return config.WriteSnapshot(rc)
+	return persistSnapshots(rc)
 }
 
 func readApplyConfirmation(r io.Reader) (bool, error) {

internal/cli/golden_test.go

@@ -101,6 +101,23 @@ func TestGolden_plan_first_table(t *testing.T) {
 	assertGoldenOutput(t, "plan_first.table.golden.txt", out.String())
 }
 
+func TestGolden_plan_policy_compile_table(t *testing.T) {
+	root := t.TempDir()
+	copyPolicyCompileFixture(t, root)
+	db := filepath.Join(t.TempDir(), "golden-policy-compile.db")
+
+	ResetGlobalsForTest()
+	cmd := NewRootCmd()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"plan", "--project", root, "--state", db})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	assertGoldenOutput(t, "plan_policy_compile.table.golden.txt", out.String())
+}
+
 func TestGolden_plan_noop_after_apply_table(t *testing.T) {
 	ctx := context.Background()
 	root := t.TempDir()

internal/cli/load_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/config"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/policy"
 )
 
 func writeFile(t *testing.T, path, content string) {
@@ -150,3 +151,61 @@ spec:
 		t.Fatalf("exit code = %d, want %d", code, ExitPlanApplyConflict)
 	}
 }
+
+func TestRun_policySnapshotDrift_exit3(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, filepath.Join(root, "project.yaml"), `apiVersion: agentic.dev/v0
+kind: Project
+metadata:
+  name: demo
+spec:
+  imports:
+    - ./policy.yaml
+  state:
+    backend: sqlite
+    dsn: .agentic/state.db
+`)
+	writeFile(t, filepath.Join(root, "policy.yaml"), `apiVersion: agentic.dev/v0
+kind: Policy
+metadata:
+  name: default
+spec:
+  execution:
+    maxTotalCostUsd: 3
+`)
+
+	ResetGlobalsForTest()
+	global = Global{ProjectRoot: root}
+	rc, err := prepareResolvedConfig(&global)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := persistSnapshots(rc); err != nil {
+		t.Fatal(err)
+	}
+
+	policyPath := filepath.Join(root, "policy.yaml")
+	b, err := os.ReadFile(policyPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	updated := strings.Replace(string(b), "maxTotalCostUsd: 3", "maxTotalCostUsd: 10", 1)
+	if err := os.WriteFile(policyPath, []byte(updated), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	rc2, err := prepareResolvedConfig(&global)
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = assertPolicySnapshotMatches(rc2)
+	if err == nil {
+		t.Fatal("expected policy drift")
+	}
+	if !errors.Is(err, policy.ErrPolicySnapshotDrift) {
+		t.Fatalf("want ErrPolicySnapshotDrift, got %v", err)
+	}
+	if code := ExitCodeOf(NewExitError(ExitPlanApplyConflict, err)); code != ExitPlanApplyConflict {
+		t.Fatalf("exit code = %d, want %d", code, ExitPlanApplyConflict)
+	}
+}

internal/cli/plan.go

@@ -10,6 +10,7 @@ import (
 
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/config"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/plan"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/policy"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/render"
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
 	"github.com/spf13/cobra"
@@ -28,8 +29,10 @@ unless overridden by global --state.
 
 Environment for stored rows is taken from -e / --env when set, otherwise "local".
 
-Writes .agentic/resolved-config.json (digest of resolved graph + env + state path) for plan→run
-contract checks. JSON/YAML output includes resolvedConfigDigest alongside deploymentBaseline.
+Writes .agentic/resolved-config.json (digest of resolved graph + env + state path) and
+.agentic/policy-snapshot.json (compiled effective policy digest) for plan→run contract checks.
+JSON/YAML output includes resolvedConfigDigest, policyDigest, and effectivePolicy (project
+default policy only; workflows/agents may bind other policy names) alongside deploymentBaseline.
 
 Exit codes (section 11.2):
   0 — success
@@ -80,8 +83,8 @@ func runPlan(cmd *cobra.Command, args []string) error {
 	if err := writePlanOutput(cmd, env, dsn, pl, rc, g); err != nil {
 		return err
 	}
-	if err := config.WriteSnapshot(rc); err != nil {
-		return fmt.Errorf("plan: write resolved config snapshot: %w", err)
+	if err := persistSnapshots(rc); err != nil {
+		return fmt.Errorf("plan: %w", err)
 	}
 	return nil
 }
@@ -97,8 +100,18 @@ func writePlanOutput(cmd *cobra.Command, env, dsn string, p *plan.Plan, rc *conf
 		if _, err := fmt.Fprintf(out, "Environment: %s\nState: %s\n\n", env, dsn); err != nil {
 			return err
 		}
-		_, err := fmt.Fprintf(out, "%s\n", plan.FormatPlan(p))
-		return err
+		if _, err := fmt.Fprintf(out, "%s", plan.FormatPlan(p)); err != nil {
+			return err
+		}
+		if section := compiledPolicyPlanSection(rc); section != "" {
+			if _, err := fmt.Fprintf(out, "%s\n", section); err != nil {
+				return err
+			}
+		} else {
+			_, err := fmt.Fprintln(out)
+			return err
+		}
+		return nil
 	}
 }
 
@@ -158,9 +171,52 @@ func planJSONModel(env, dsn string, p *plan.Plan, rc *config.ResolvedConfig) map
 	if rc != nil && rc.Digest() != "" {
 		m["resolvedConfigDigest"] = rc.Digest()
 	}
+	if rc != nil {
+		if cp, digest, err := compiledPolicySummary(rc); err == nil && cp != nil {
+			m["policyDigest"] = digest
+			m["effectivePolicy"] = effectivePolicyJSON(cp)
+		}
+	}
 	return m
 }
 
+// compiledPolicySummary returns the snapshot-set digest and the compiled project-default policy.
+// Workflows and agents may reference other policy names; only the default is shown in plan output.
+func compiledPolicySummary(rc *config.ResolvedConfig) (*policy.CompiledPolicy, string, error) {
+	graph := rc.Graph()
+	policies, err := policy.CompileReferenced(graph)
+	if err != nil {
+		return nil, "", err
+	}
+	digest, err := policy.SnapshotSetDigest(policies)
+	if err != nil {
+		return nil, "", err
+	}
+	name := policy.DefaultPolicyName(graph)
+	return policies[name], digest, nil
+}
+
+func compiledPolicyPlanSection(rc *config.ResolvedConfig) string {
+	cp, _, err := compiledPolicySummary(rc)
+	if err != nil || cp == nil {
+		return ""
+	}
+	return plan.FormatEffectivePolicy(policy.DefaultPolicyName(rc.Graph()), cp)
+}
+
+func effectivePolicyJSON(cp *policy.CompiledPolicy) []map[string]string {
+	entries := cp.EffectivePolicyEntries()
+	out := make([]map[string]string, len(entries))
+	for i, e := range entries {
+		out[i] = map[string]string{
+			"tool":     e.Tool,
+			"decision": string(e.Decision),
+			"source":   string(e.Source),
+		}
+	}
+	return out
+}
+
 func riskStrings(p *plan.Plan) []string {
 	if p == nil || len(p.Risk.Messages) == 0 {
 		return []string{}

internal/cli/plan_test.go

@@ -15,9 +15,9 @@ import (
 	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/state/sqlite"
 )
 
-func copyPlanFixture(t *testing.T, dstDir string) {
+func copyFixtureDir(t *testing.T, dstDir, fixtureName string) {
 	t.Helper()
-	src := filepath.Join("testdata", "plan_project")
+	src := filepath.Join("testdata", fixtureName)
 	entries, err := os.ReadDir(src)
 	if err != nil {
 		t.Fatal(err)
@@ -36,6 +36,16 @@ func copyPlanFixture(t *testing.T, dstDir string) {
 	}
 }
 
+func copyPlanFixture(t *testing.T, dstDir string) {
+	t.Helper()
+	copyFixtureDir(t, dstDir, "plan_project")
+}
+
+func copyPolicyCompileFixture(t *testing.T, dstDir string) {
+	t.Helper()
+	copyFixtureDir(t, dstDir, "plan_policy_compile")
+}
+
 func TestPlan_json_includesResolvedConfigDigest(t *testing.T) {
 	root := t.TempDir()
 	copyPlanFixture(t, root)
@@ -60,6 +70,34 @@ func TestPlan_json_includesResolvedConfigDigest(t *testing.T) {
 	}
 }
 
+func TestPlan_json_includesPolicyDigest(t *testing.T) {
+	root := t.TempDir()
+	copyPolicyCompileFixture(t, root)
+	db := filepath.Join(t.TempDir(), "plan-policy-json.db")
+
+	ResetGlobalsForTest()
+	var out bytes.Buffer
+	cmd := NewRootCmd()
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"plan", "--project", root, "--state", db, "-o", "json"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(out.Bytes(), &payload); err != nil {
+		t.Fatalf("json: %v\nbody=%s", err, out.String())
+	}
+	d, ok := payload["policyDigest"].(string)
+	if !ok || strings.TrimSpace(d) == "" {
+		t.Fatalf("policyDigest missing or empty: %#v", payload["policyDigest"])
+	}
+	effective, ok := payload["effectivePolicy"].([]any)
+	if !ok || len(effective) < 3 {
+		t.Fatalf("effectivePolicy missing entries: %#v", payload["effectivePolicy"])
+	}
+}
+
 func TestPlan_firstPlan_allCreates(t *testing.T) {
 	root := t.TempDir()
 	copyPlanFixture(t, root)

internal/cli/policy_snapshot.go

@@ -0,0 +1,41 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/config"
+	"github.com/LAA-Software-Engineering/agentic-control-plane/internal/policy"
+)
+
+// persistSnapshots writes resolved-config and compiled policy snapshots for plan→run checks.
+func persistSnapshots(rc *config.ResolvedConfig) error {
+	if err := config.WriteSnapshot(rc); err != nil {
+		return fmt.Errorf("write resolved config snapshot: %w", err)
+	}
+	if err := writePolicySnapshot(rc); err != nil {
+		return err
+	}
+	return nil
+}
+
+func writePolicySnapshot(rc *config.ResolvedConfig) error {
+	if rc == nil {
+		return fmt.Errorf("policy snapshot: nil resolved config")
+	}
+	graph := rc.Graph()
+	policies, err := policy.CompileReferenced(graph)
+	if err != nil {
+		return fmt.Errorf("policy snapshot: compile: %w", err)
+	}
+	if err := policy.WriteSnapshotSet(rc.ProjectRoot(), rc.Digest(), policies); err != nil {
+		return fmt.Errorf("policy snapshot: %w", err)
+	}
+	return nil
+}
+
+func assertPolicySnapshotMatches(rc *config.ResolvedConfig) error {
+	if rc == nil {
+		return fmt.Errorf("policy snapshot: nil resolved config")
+	}
+	return policy.AssertSnapshotMatchesCompiled(rc.ProjectRoot(), rc.Graph(), rc.Digest())
+}

internal/cli/run.go

@@ -67,15 +67,16 @@ Examples:
   agentctl run workflow/demo --input-file input.json
   agentctl run --resume run-abc123
 
-When .agentic/resolved-config.json exists (from a prior validate/plan/apply), run compares
-the resolved-config digest and fails with exit 3 if inputs changed (e.g. user-local overlay,
---state, or project YAML). Re-run validate or plan after changing config.
+When .agentic/resolved-config.json or .agentic/policy-snapshot.json exists (from a prior
+validate/plan/apply), run compares those digests and fails with exit 3 if inputs changed
+(e.g. user-local overlay, --state, project YAML, or policy YAML). Re-run validate or plan
+after changing config or policy.
 
 Exit codes (section 11.2):
   0 — success (including interrupted runs awaiting resume)
   1 — generic failure (e.g. cannot open SQLite, start run, trace)
   2 — validation failure (project, workflow ref, input, input-file)
-  3 — resolved-config drift (config changed since last validate/plan/apply; issue #112)
+  3 — resolved-config or policy snapshot drift (changed since last validate/plan/apply; issues #112, #118)
   4 — execution failure (step/engine error after the run row exists)
   5 — policy denial`,
 		Args: func(cmd *cobra.Command, args []string) error {
@@ -235,6 +236,12 @@ func runRun(cmd *cobra.Command, wfName, resumeRunID, inputFile string, inputPair
 		}
 		return fmt.Errorf("run: resolved config snapshot: %w", err)
 	}
+	if err := assertPolicySnapshotMatches(rc); err != nil {
+		if errors.Is(err, policy.ErrPolicySnapshotDrift) {
+			return NewExitError(ExitPlanApplyConflict, err)
+		}
+		return fmt.Errorf("run: policy snapshot: %w", err)
+	}
 	env := rc.Environment()
 	dsn := rc.StatePath()