Enforce framework required_fields and add systemic drift guards (#6)

* Enforce framework field requirements and add drift guards

* Format schema sync test for CI

Author: davidahmann

README.md

@@ -37,7 +37,8 @@ An open-source Go module and verification CLI. Four operations:
 ## Quick Start
 
 ```bash
-go install github.com/Clyra-AI/proof/cmd/proof@v0.2.0
+PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/proof/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')"
+go install github.com/Clyra-AI/proof/cmd/proof@"${PROOF_VERSION}"
 
 proof types list          # 15 built-in record types
 proof frameworks list     # 8 compliance framework definitions
@@ -180,7 +181,16 @@ All digests carry `algo_id` (sha256 or hmac-sha256) and optional `salt_id` metad
 
 ## Compliance Framework Definitions
 
-YAML files that declare what regulatory controls require — which record types, what fields, what frequency. Zero evaluation logic. Configuration data consumed by downstream compliance tools.
+YAML files that declare what regulatory controls require — which record types, required fields, and evidence frequency. Zero evaluation logic. Configuration data consumed by downstream compliance tools.
+
+```yaml
+controls:
+  - id: article-12
+    title: Record-Keeping
+    required_record_types: [tool_invocation, decision, guardrail_activation, permission_check]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
+    minimum_frequency: continuous
+```
 
 8 frameworks ship with v1:
 
@@ -314,18 +324,21 @@ CI pipelines: main, PR, determinism (cross-platform), CodeQL, nightly (hardening
 ## Install
 
 ```bash
-# From source
-go install github.com/Clyra-AI/proof/cmd/proof@v0.2.0
+PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/proof/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')"
+
+# From module source at latest published release tag
+go install github.com/Clyra-AI/proof/cmd/proof@"${PROOF_VERSION}"
 
-# From release (after a tagged release is published)
-gh release download vX.Y.Z -R Clyra-AI/proof -D /tmp/proof-release
+# From release assets
+gh release download "${PROOF_VERSION}" -R Clyra-AI/proof -D /tmp/proof-release
 cd /tmp/proof-release && sha256sum -c checksums.txt
 ```
 
 Go module:
 
 ```bash
-go get github.com/Clyra-AI/proof@v0.2.0
+PROOF_VERSION="$(gh release view --repo Clyra-AI/proof --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/proof/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')"
+go get github.com/Clyra-AI/proof@"${PROOF_VERSION}"
 ```
 
 ## License

core/framework/colorado-ai-act.yaml

@@ -6,4 +6,5 @@ controls:
   - id: co-risk
     title: Risk Management
     required_record_types: [risk_assessment]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: quarterly

core/framework/eu-ai-act.yaml

@@ -6,12 +6,15 @@ controls:
   - id: article-9
     title: Risk Management
     required_record_types: [risk_assessment]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: quarterly
   - id: article-12
     title: Record-Keeping
     required_record_types: [tool_invocation, decision, guardrail_activation, permission_check]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: continuous
   - id: article-14
     title: Human Oversight
     required_record_types: [human_oversight, approval]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: per-event

core/framework/framework.go

@@ -81,9 +81,50 @@ func Load(idOrFile string) (*Framework, error) {
 	if f.Framework.ID == "" {
 		return nil, fmt.Errorf("framework %s missing id", idOrFile)
 	}
+	if len(f.Controls) == 0 {
+		return nil, fmt.Errorf("framework %s has no controls", idOrFile)
+	}
+	if err := validateControls(f.Controls, "controls"); err != nil {
+		return nil, fmt.Errorf("framework %s invalid: %w", idOrFile, err)
+	}
 	return &f, nil
 }
 
+func validateControls(controls []Control, path string) error {
+	for i, c := range controls {
+		controlPath := fmt.Sprintf("%s[%d]", path, i)
+		if strings.TrimSpace(c.ID) == "" {
+			return fmt.Errorf("%s missing id", controlPath)
+		}
+		if strings.TrimSpace(c.Title) == "" {
+			return fmt.Errorf("%s (%s) missing title", controlPath, c.ID)
+		}
+		if len(c.RequiredRecordTypes) == 0 {
+			return fmt.Errorf("%s (%s) missing required_record_types", controlPath, c.ID)
+		}
+		if strings.TrimSpace(c.MinimumFrequency) == "" {
+			return fmt.Errorf("%s (%s) missing minimum_frequency", controlPath, c.ID)
+		}
+		if len(c.RequiredFields) == 0 {
+			return fmt.Errorf("%s (%s) missing required_fields", controlPath, c.ID)
+		}
+		for _, t := range c.RequiredRecordTypes {
+			if strings.TrimSpace(t) == "" {
+				return fmt.Errorf("%s (%s) has blank required_record_types entry", controlPath, c.ID)
+			}
+		}
+		for _, field := range c.RequiredFields {
+			if strings.TrimSpace(field) == "" {
+				return fmt.Errorf("%s (%s) has blank required_fields entry", controlPath, c.ID)
+			}
+		}
+		if err := validateControls(c.Children, controlPath+".children"); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 func countControls(in []Control) int {
 	total := 0
 	for _, c := range in {

core/framework/framework_test.go

@@ -1,6 +1,8 @@
 package framework
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -27,3 +29,46 @@ func TestLoadMissingAndCountControls(t *testing.T) {
 	})
 	require.Equal(t, 4, total)
 }
+
+func TestValidateControls(t *testing.T) {
+	valid := []Control{
+		{
+			ID:                  "c1",
+			Title:               "Control 1",
+			RequiredRecordTypes: []string{"decision"},
+			MinimumFrequency:    "continuous",
+			RequiredFields:      []string{"record_id", "event"},
+		},
+	}
+	require.NoError(t, validateControls(valid, "controls"))
+
+	missingFields := []Control{
+		{
+			ID:                  "c2",
+			Title:               "Control 2",
+			RequiredRecordTypes: []string{"decision"},
+			MinimumFrequency:    "continuous",
+		},
+	}
+	require.ErrorContains(t, validateControls(missingFields, "controls"), "missing required_fields")
+}
+
+func TestFrameworkCopiesStayInSync(t *testing.T) {
+	entries, err := os.ReadDir(".")
+	require.NoError(t, err)
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		if filepath.Ext(entry.Name()) != ".yaml" {
+			continue
+		}
+		corePath := entry.Name()
+		repoPath := filepath.Join("..", "..", "frameworks", entry.Name())
+		coreRaw, err := os.ReadFile(corePath)
+		require.NoError(t, err)
+		repoRaw, err := os.ReadFile(repoPath)
+		require.NoError(t, err)
+		require.Equalf(t, string(repoRaw), string(coreRaw), "framework copy mismatch for %s", entry.Name())
+	}
+}

core/framework/iso-42001.yaml

@@ -6,4 +6,5 @@ controls:
   - id: aisms-risk
     title: AI Risk Assessment
     required_record_types: [risk_assessment, incident]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: quarterly

core/framework/nist-ai-600-1.yaml

@@ -6,4 +6,5 @@ controls:
   - id: nist-boundary
     title: Boundary Enforcement
     required_record_types: [policy_enforcement, permission_check]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: continuous

core/framework/pci-dss.yaml

@@ -6,4 +6,5 @@ controls:
   - id: req-10
     title: Logging and Monitoring
     required_record_types: [tool_invocation, permission_check, incident]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: continuous

core/framework/soc2.yaml

@@ -6,8 +6,10 @@ controls:
   - id: cc6
     title: Logical Access
     required_record_types: [permission_check, approval]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: continuous
   - id: cc7
     title: System Operations
     required_record_types: [incident, guardrail_activation]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: continuous

core/framework/sox.yaml

@@ -6,4 +6,5 @@ controls:
   - id: sox-cm
     title: Change Management
     required_record_types: [deployment, approval]
+    required_fields: [record_id, timestamp, source, source_product, record_type, event, integrity.record_hash]
     minimum_frequency: per-change