devrites 3.0.6 → 3.1.0

package/engine/internal/lib/session_test.go

@@ -2,30 +2,32 @@ package lib
 
 import (
 	"bytes"
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/devrites/devrites/internal/reason"
 )
 
-func TestTimelineLogAndList(t *testing.T) {
+func TestTimelineLegacyWritesRejectedAndReadsPreserved(t *testing.T) {
 	t.Setenv("DEVRITES_NOW", "2026-07-09T10:11:12Z")
 	root := t.TempDir()
 	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
-
-	code := Timeline(root, []string{"log", "completed", "--skill", "rite-review", "--slug", "auth", "--outcome", "ok", "--decision", "ship"}, stdout, stderr)
-	if code != 0 {
-		t.Fatalf("timeline log failed: code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
-	}
-	data, err := os.ReadFile(filepath.Join(root, "timeline.jsonl"))
-	if err != nil {
+	legacy := []byte(`{"ts":"2026-07-09T10:11:12Z","event":"completed","decision":"ship"}` + "\n")
+	path := filepath.Join(root, "timeline.jsonl")
+	if err := os.WriteFile(path, legacy, 0o644); err != nil {
 		t.Fatal(err)
 	}
-	got := string(data)
-	for _, want := range []string{`"ts":"2026-07-09T10:11:12Z"`, `"event":"completed"`, `"skill":"rite-review"`, `"slug":"auth"`, `"decision":"ship"`} {
-		if !strings.Contains(got, want) {
-			t.Fatalf("timeline entry missing %s: %s", want, got)
-		}
+
+	code := Timeline(root, []string{"log", "completed", "--skill", "rite-review", "--slug", "auth", "--outcome", "ok", "--decision", "PRIVATE_RESULT"}, stdout, stderr)
+	if code != 2 || !strings.Contains(stderr.String(), "legacy free-text writes are disabled") {
+		t.Fatalf("legacy timeline write code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	data, err := os.ReadFile(path)
+	if err != nil || !bytes.Equal(data, legacy) {
+		t.Fatalf("legacy write changed timeline: data=%q err=%v", data, err)
 	}
 
 	stdout.Reset()
@@ -44,6 +46,71 @@ func TestTimelineLogAndList(t *testing.T) {
 	}
 }
 
+func TestTimelineTypedFactsAreValidatedAndVersioned(t *testing.T) {
+	t.Setenv("DEVRITES_NOW", "2026-07-09T10:11:12Z")
+	t.Setenv("DEVRITES_RUN_ID", testRunID)
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	workspace := filepath.Join(root, "work", "auth")
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | build |\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_ROOT", root)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := Timeline(root, []string{
+		"log", "review-dispatch", "--slug", "auth",
+		"--execution-mode", "generic",
+		"--guard-strength", "observed",
+		"--reason-id", string(reason.AgentGenericFallback),
+		"--host", "codex",
+		"--evidence", ".devrites/work/auth/plan.md",
+	}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("timeline log code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	raw, err := os.ReadFile(filepath.Join(root, "timeline.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got EventV1
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Schema != EventSchemaV1 || got.ExecutionMode != ExecutionGeneric ||
+		got.GuardStrength != GuardObserved || got.ReasonID != reason.AgentGenericFallback ||
+		got.Host != HostCodex || got.Workspace != ".devrites/work/auth" {
+		t.Fatalf("typed event = %+v", got)
+	}
+
+	stderr.Reset()
+	if code := Timeline(root, []string{
+		"log", "bad", "--execution-mode", "named", "--guard-strength", "enforced",
+		"--reason-id", "DRV-UNKNOWN",
+	}, &bytes.Buffer{}, stderr); code != 2 {
+		t.Fatalf("unknown reason code=%d stderr=%q", code, stderr.String())
+	}
+}
+
+func TestTimelineListPreservesAndDistinguishesLegacyAndCorruptRows(t *testing.T) {
+	root := t.TempDir()
+	legacy := `{"ts":"2026-01-01T00:00:00Z","event":"legacy"}`
+	corrupt := `{not-json}`
+	if err := os.WriteFile(filepath.Join(root, "timeline.jsonl"), []byte(legacy+"\n"+corrupt+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Timeline(root, []string{"list"}, stdout, stderr); code != 0 {
+		t.Fatalf("timeline list code=%d stderr=%q", code, stderr.String())
+	}
+	if got := stdout.String(); !strings.Contains(got, legacy) || !strings.Contains(got, corrupt) ||
+		strings.Contains(legacy, `"schema":"`+EventSchemaV1+`"`) {
+		t.Fatalf("legacy/corrupt history changed: %q", got)
+	}
+}
+
 func TestHealthRecordValidatesScore(t *testing.T) {
 	t.Setenv("DEVRITES_NOW", "2026-07-09")
 	root := t.TempDir()

package/engine/internal/lib/testintegrity.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"os/exec"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -18,14 +17,13 @@ var (
 	assertMarkers = regexp.MustCompile(`assert|expect\(|\.should\b|\brequire\.|EXPECT_|ASSERT_|XCTAssert|t\.Error|t\.Fatal`)
 )
 
-// TestIntegrity guards against reaching green by weakening tests instead of fixing
-// code. It diffs the test files against the slice's base tree (the reconcile
-// snapshot if present, else HEAD) and flags any test file that was deleted, gained
-// a skip/focus marker, or lost assertions. Read-only; the workspace is
-// <root>/features/<slug>.
+// TestIntegrity detects tests that were weakened instead of fixing the code. It
+// compares test files in the retained reconcile tree with the current tree, or
+// uses HEAD as the base outside a slice lifecycle. It does not modify the
+// workspace at <root>/features/<slug>.
 //
 //	0  clean, or skipped because this is not a git repo
-//	2  no active workspace / bad args
+//	2  no active workspace, bad args, or missing/corrupt baseline state
 //	3  WEAKENED: a test was deleted, skipped, or de-asserted since the base
 func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	// Accept both `test-integrity [slug]` and the `check [slug]` alias; a leading
@@ -56,23 +54,26 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	cwd, _ := os.Getwd()
 	gitRoot := gitToplevel(cwd)
 	if gitRoot == "" {
-		fmt.Fprintln(stderr, "test-integrity: not a git repo: gate skipped, eyeball the test diff by hand.")
+		fmt.Fprintln(stderr, "test-integrity: not a git repo: gate skipped; inspect the test diff manually.")
 		return 0
 	}
 
-	baseTree := ""
-	if b, err := os.ReadFile(filepath.Join(d, ".reconcile-base")); err == nil {
-		baseTree = strings.TrimSpace(string(b))
+	trees, err := captureSliceTreeRange(gitRoot, root, d)
+	if err != nil {
+		fmt.Fprintf(stderr, "test-integrity: cannot capture slice range: %v\n", err)
+		return 2
 	}
-	ref := baseTree
-	if ref == "" {
-		ref = "HEAD"
+	defer trees.cleanup()
+	changedPaths, err := changedTreePaths(gitRoot, trees.env, trees.base, trees.current)
+	if err != nil {
+		fmt.Fprintf(stderr, "test-integrity: cannot compare slice trees: %v\n", err)
+		return 2
 	}
 
 	weak := 0
 	srcChanged, testChanged := 0, 0
 	var report strings.Builder
-	for _, f := range gitDiffNames(gitRoot, ref) {
+	for _, f := range changedPaths {
 		if f == "" {
 			continue
 		}
@@ -83,19 +84,25 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 			continue
 		}
 		testChanged++
-		old, ok := gitShow(gitRoot, ref+":"+f)
-		if !ok || old == "" {
+		oldBytes, oldExists, err := treeFileContent(gitRoot, trees.env, trees.base, f)
+		if err != nil {
+			fmt.Fprintf(stderr, "test-integrity: cannot read baseline %s: %v\n", f, err)
+			return 2
+		}
+		if !oldExists || len(oldBytes) == 0 {
 			continue // new test file: adding tests is never a weakening
 		}
-		if !isFile(filepath.Join(gitRoot, f)) {
+		newBytes, newExists, err := treeFileContent(gitRoot, trees.env, trees.current, f)
+		if err != nil {
+			fmt.Fprintf(stderr, "test-integrity: cannot read current %s: %v\n", f, err)
+			return 2
+		}
+		if !newExists {
 			weak++
 			fmt.Fprintf(&report, "  - %s: test file DELETED\n", f)
 			continue
 		}
-		newBytes, err := os.ReadFile(filepath.Join(gitRoot, f))
-		if err != nil {
-			continue
-		}
+		old := string(oldBytes)
 		now := string(newBytes)
 		oldSkips, newSkips := countMatches(skipMarkers, old), countMatches(skipMarkers, now)
 		oldAsserts, newAsserts := countMatches(assertMarkers, old), countMatches(assertMarkers, now)
@@ -109,10 +116,9 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 		}
 	}
 
-	// Verification-gap advisory: source changed but no test file did. Not a
-	// weakening and never a verdict on its own: a pointer to run the
-	// verification-gap trace (testing.md), since a green suite can pass identically
-	// with the change reverted. Printed on both the clean and weakened paths.
+	// When source changes without a test change, print the verification-gap
+	// advisory from testing.md. This is not a weakening verdict and appears on
+	// both clean and weakened paths.
 	gapAdvisory := ""
 	if srcChanged > 0 && testChanged == 0 {
 		gapAdvisory = fmt.Sprintf("test-integrity: advisory: %d source file(s) changed, 0 test file(s) touched; "+
@@ -122,7 +128,7 @@ func TestIntegrity(root string, args []string, stdout, stderr io.Writer) int {
 	if weak > 0 {
 		fmt.Fprintf(stderr, "test-integrity: WEAKENED: %d test file(s) lost coverage since the slice base:\n", weak)
 		fmt.Fprint(stderr, report.String())
-		fmt.Fprintln(stderr, "A test weakened to pass a gate is a Critical finding. Revert it; fix the code or raise a blocking question.")
+		fmt.Fprintln(stderr, "Weakening a test to pass the gate is a Critical finding. Restore the test, then fix the code or raise a blocking question.")
 		if gapAdvisory != "" {
 			fmt.Fprintln(stderr, gapAdvisory)
 		}
@@ -191,13 +197,3 @@ func isTestFile(f string) bool {
 func countMatches(re *regexp.Regexp, text string) int {
 	return len(re.FindAllStringIndex(text, -1))
 }
-
-// gitShow returns the content of an object (e.g. "HEAD:path"), and false when it
-// does not exist at that ref.
-func gitShow(gitRoot, spec string) (string, bool) {
-	out, err := exec.Command("git", "-C", gitRoot, "show", spec).Output()
-	if err != nil {
-		return "", false
-	}
-	return string(out), true
-}

package/engine/internal/lib/testintegrity_test.go

@@ -1,6 +1,12 @@
 package lib
 
-import "testing"
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
 
 func TestIsTestFileClassifiesTests(t *testing.T) {
 	cases := []struct {
@@ -70,3 +76,59 @@ func TestIsSourceFileRecognisesCode(t *testing.T) {
 		}
 	}
 }
+
+func TestIntegrityDetectsDeletionFromDirtySliceBaseline(t *testing.T) {
+	gitRoot := newGitRepo(t)
+	root := workspace(t, "feat")
+	testPath := "tests/preexisting_test.go"
+	writeFile(t, filepath.Join(gitRoot, testPath), "package tests\n\nfunc TestBaseline(t *testing.T) { t.Fatal(\"assert\") }\n")
+	writeWrightAllowlist(t, root, "feat", testPath)
+	if code, out := runReconcile(t, root, "snapshot", "feat"); code != 0 {
+		t.Fatalf("snapshot = %d, want 0\n%s", code, out)
+	}
+	if err := os.Remove(filepath.Join(gitRoot, testPath)); err != nil {
+		t.Fatal(err)
+	}
+	if code, out := runReconcile(t, root, "check", "feat"); code != 0 {
+		t.Fatalf("reconcile check = %d, want 0\n%s", code, out)
+	}
+
+	var stdout, stderr bytes.Buffer
+	code := TestIntegrity(root, []string{"feat"}, &stdout, &stderr)
+	if code != 3 {
+		t.Fatalf("test-integrity = %d, want 3\nstdout: %s\nstderr: %s", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), testPath+": test file DELETED") {
+		t.Fatalf("deleted dirty-baseline test missing from finding:\n%s", stderr.String())
+	}
+}
+
+func TestIntegrityFailsClosedOnPartialReconcileBaseline(t *testing.T) {
+	newGitRepo(t)
+	root := workspace(t, "feat")
+	writeFile(t, filepath.Join(featureDir(root, "feat"), reconcileBaseName), "deadbeef\n")
+
+	var stdout, stderr bytes.Buffer
+	code := TestIntegrity(root, []string{"feat"}, &stdout, &stderr)
+	if code != 2 {
+		t.Fatalf("test-integrity = %d, want 2\nstdout: %s\nstderr: %s", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "partial lifecycle") {
+		t.Fatalf("missing fail-closed lifecycle diagnostic:\n%s", stderr.String())
+	}
+}
+
+func TestIntegrityAdvisesWhenSourceChangesWithoutTests(t *testing.T) {
+	gitRoot := newGitRepo(t)
+	root := workspace(t, "feat")
+	writeFile(t, filepath.Join(gitRoot, "src", "feature.go"), "package src\n")
+
+	var stdout, stderr bytes.Buffer
+	code := TestIntegrity(root, []string{"feat"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("test-integrity = %d, want 0\nstdout: %s\nstderr: %s", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "source file(s) changed, 0 test file(s) touched") {
+		t.Fatalf("missing verification-gap advisory:\n%s", stdout.String())
+	}
+}

package/engine/internal/migrate/migrate.go

@@ -11,6 +11,7 @@ import (
 	"path/filepath"
 	"slices"
 	"sort"
+	"strconv"
 	"strings"
 	"time"
 
@@ -93,6 +94,9 @@ func needsNormalizeFeature(dir string) bool {
 	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		return true
 	}
+	if version := declaredSchemaVersion(dir); version < state.SchemaVersion {
+		return true
+	}
 	return regularFileExists(filepath.Join(dir, "proof.md")) && !regularFileExists(filepath.Join(dir, state.EvidenceFile)) ||
 		regularFileExists(filepath.Join(dir, "status.md")) && !regularFileExists(filepath.Join(dir, state.LedgerFile))
 }
@@ -114,12 +118,88 @@ func normalizeFeatureDir(dir, slug string) error {
 			return fmt.Errorf("write workspace index: %w", err)
 		}
 	}
+	phase := derivePhase(filepath.Join(dir, state.LedgerFile))
+	if err := upgradeWorkspaceMapSchema(filepath.Join(dir, state.WorkspaceMapFile), slug, phase); err != nil {
+		return fmt.Errorf("upgrade workspace schema: %w", err)
+	}
 	if err := copyAliasFile(dir, "proof.md", state.EvidenceFile); err != nil {
 		return fmt.Errorf("copy proof.md to evidence.md: %w", err)
 	}
 	return copyAliasFile(dir, "status.md", state.LedgerFile)
 }
 
+func declaredSchemaVersion(dir string) int {
+	for _, name := range state.WorkspaceMapFiles() {
+		raw, err := os.ReadFile(filepath.Join(dir, name))
+		if err != nil {
+			continue
+		}
+		lines := strings.Split(string(raw), "\n")
+		if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
+			return 0
+		}
+		for _, line := range lines[1:] {
+			if strings.TrimSpace(line) == "---" {
+				break
+			}
+			key, value, ok := strings.Cut(line, ":")
+			if ok && strings.TrimSpace(key) == "schemaVersion" {
+				version, _ := strconv.Atoi(strings.TrimSpace(value))
+				return version
+			}
+		}
+		return 0
+	}
+	return 0
+}
+
+// upgradeWorkspaceMapSchema advances only the compatibility declaration. It
+// never creates decision coverage, readiness, or proof artifacts: those must be
+// earned by their owning phases.
+func upgradeWorkspaceMapSchema(path, slug string, phase state.Phase) error {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+	version := declaredSchemaVersion(filepath.Dir(path))
+	if version > state.SchemaVersion {
+		return fmt.Errorf("schemaVersion %d is newer than this engine supports (%d)", version, state.SchemaVersion)
+	}
+	if version == state.SchemaVersion {
+		return nil
+	}
+
+	text := string(raw)
+	if !strings.HasPrefix(text, "---\n") {
+		prefix := fmt.Sprintf("---\nslug: %s\nphase: %s\nschemaVersion: %d\n---\n\n", slug, phase, state.SchemaVersion)
+		return state.AtomicWrite(path, []byte(prefix+text), 0o644)
+	}
+
+	lines := strings.Split(text, "\n")
+	end := -1
+	schemaLine := -1
+	for i := 1; i < len(lines); i++ {
+		if strings.TrimSpace(lines[i]) == "---" {
+			end = i
+			break
+		}
+		key, _, ok := strings.Cut(lines[i], ":")
+		if ok && strings.TrimSpace(key) == "schemaVersion" {
+			schemaLine = i
+		}
+	}
+	if end < 0 {
+		return fmt.Errorf("workspace map has an unclosed frontmatter block")
+	}
+	value := fmt.Sprintf("schemaVersion: %d", state.SchemaVersion)
+	if schemaLine >= 0 {
+		lines[schemaLine] = value
+	} else {
+		lines = append(lines[:end], append([]string{value}, lines[end:]...)...)
+	}
+	return state.AtomicWrite(path, []byte(strings.Join(lines, "\n")), 0o644)
+}
+
 func copyAliasFile(dir, alias, canonical string) error {
 	src := filepath.Join(dir, alias)
 	dst := filepath.Join(dir, canonical)
@@ -133,7 +213,7 @@ func copyAliasFile(dir, alias, canonical string) error {
 	return state.AtomicWrite(dst, data, 0o644)
 }
 
-// workspaceIndex renders the compact map added to a normalized workspace.
+// workspaceIndex renders the compact map used by a normalized workspace.
 func workspaceIndex(slug string, phase state.Phase) string {
 	return fmt.Sprintf(`---
 slug: %s

package/engine/internal/migrate/migrate_test.go

@@ -37,6 +37,7 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 	assertFile(t, root, "work/alpha/evidence.md", "proof\n")
 	assertFile(t, root, "work/alpha/state.md", "status: done - shipped\n")
 	assertFileContains(t, root, "work/alpha/README.md", "phase: done")
+	assertFileContains(t, root, "work/alpha/README.md", "schemaVersion: 2")
 	assertMissing(t, root, "work/alpha/proof.md")
 	assertMissing(t, root, "work/alpha/status.md")
 	assertFile(t, root, "work/alpha/review.md", "review\n")
@@ -72,7 +73,8 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	if got := strings.Join(res.Migrated, ","); got != "beta" {
 		t.Fatalf("Run normalized=%q, want beta", got)
 	}
-	assertFile(t, root, "features/beta/README.md", "# Beta\n")
+	assertFileContains(t, root, "features/beta/README.md", "schemaVersion: 2")
+	assertFileContains(t, root, "features/beta/README.md", "# Beta")
 	assertFile(t, root, "features/beta/state.md", "- Phase: prove\n")
 	assertFile(t, root, "features/beta/evidence.md", "evidence\n")
 	assertFile(t, root, "features/beta/status.md", "- Phase: prove\n")
@@ -87,6 +89,24 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	}
 }
 
+func TestRunUpgradesV1DeclarationWithoutFabricatingReadiness(t *testing.T) {
+	root := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(root, "work/old/README.md"), "---\nphase: vet\nschemaVersion: 1\n---\n\nOld workspace.\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/old/state.md"), "| phase | vet |\n")
+
+	result, err := Run(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Skipped || strings.Join(result.Migrated, ",") != "old" {
+		t.Fatalf("result=%+v, want old migrated", result)
+	}
+	assertFileContains(t, root, "work/old/README.md", "schemaVersion: 2")
+	for _, name := range []string{"decision-coverage.md", "eng-review.md", "test-plan.md"} {
+		assertMissing(t, root, filepath.Join("work/old", name))
+	}
+}
+
 func TestMapLegacyPhase(t *testing.T) {
 	for _, phase := range state.LifecyclePhases() {
 		got, ok := mapLegacyPhase(string(phase))
@@ -101,6 +121,7 @@ func TestMapLegacyPhase(t *testing.T) {
 		ok   bool
 	}{
 		{word: "specced", want: state.PhaseSpec, ok: true},
+		{word: "clarified", want: state.PhaseClarify, ok: true},
 		{word: "in-progress", want: state.PhaseBuild, ok: true},
 		{word: "reviewing", want: state.PhaseReview, ok: true},
 		{word: "done - shipped", want: state.PhaseDone, ok: true},

package/engine/internal/reason/reason.go

@@ -0,0 +1,180 @@
+// Package reason owns stable machine-readable decision identifiers.
+package reason
+
+import (
+	"fmt"
+	"sort"
+)
+
+// ID identifies one rule outcome independently of its human wording.
+type ID string
+
+const (
+	RootSelected ID = "DRV-ROOT-SELECTED"
+
+	GateReadinessPassed  ID = "DRV-GATE-READINESS-PASSED" // #nosec G101 -- stable decision ID, not a credential
+	GateReadinessMissing ID = "DRV-GATE-READINESS-MISSING"
+	GateSealPassed       ID = "DRV-GATE-SEAL-PASSED" // #nosec G101 -- stable decision ID, not a credential
+	GateSealMissing      ID = "DRV-GATE-SEAL-MISSING"
+
+	HookDisabled                 ID = "DRV-HOOK-DISABLED"
+	HookAllowApproved            ID = "DRV-HOOK-ALLOW-APPROVED"
+	HookStopClear                ID = "DRV-HOOK-STOP-CLEAR"
+	HookStopInputInvalid         ID = "DRV-HOOK-STOP-INPUT-INVALID"
+	HookStopReentry              ID = "DRV-HOOK-STOP-REENTRY"
+	HookStopWorkspaceUnavailable ID = "DRV-HOOK-STOP-WORKSPACE-UNAVAILABLE" // #nosec G101 -- stable decision ID, not a credential
+	HookStopRed                  ID = "DRV-HOOK-STOP-RED"
+	HookStopUnsurfacedHumanGate  ID = "DRV-HOOK-STOP-UNSURFACED-HUMAN-GATE"
+	HookStopMissingProof         ID = "DRV-HOOK-STOP-MISSING-PROOF"
+	HookReviewerReadonlyDenied   ID = "DRV-HOOK-REVIEWER-READONLY-DENIED"
+	HookReviewerReadonlyObserved ID = "DRV-HOOK-REVIEWER-READONLY-OBSERVED"
+	HookA1Denied                 ID = "DRV-HOOK-A1-DENIED"
+	HookA1Observed               ID = "DRV-HOOK-A1-OBSERVED"
+	HookWrightScopeDenied        ID = "DRV-HOOK-WRIGHT-SCOPE-DENIED"
+	HookWrightScopeObserved      ID = "DRV-HOOK-WRIGHT-SCOPE-OBSERVED"
+	HookWrightForbiddenDenied    ID = "DRV-HOOK-WRIGHT-FORBIDDEN-DENIED"
+	HookForgeBindingDenied       ID = "DRV-HOOK-FORGE-BINDING-DENIED"
+	HookIngestWarning            ID = "DRV-HOOK-INGEST-WARNING"
+
+	GitAuthorityPending     ID = "DRV-GIT-AUTHORITY-PENDING"
+	GitAuthorityGranted     ID = "DRV-GIT-AUTHORITY-GRANTED"
+	GitAuthorityExpired     ID = "DRV-GIT-AUTHORITY-EXPIRED"
+	GitAuthorityRefused     ID = "DRV-GIT-AUTHORITY-REFUSED"
+	GitAuthorityReplayed    ID = "DRV-GIT-AUTHORITY-REPLAYED"
+	GitAuthorityCorrupt     ID = "DRV-GIT-AUTHORITY-CORRUPT"
+	GitAuthorityUnavailable ID = "DRV-GIT-AUTHORITY-UNAVAILABLE"
+	GitWorkspaceUnavailable ID = "DRV-GIT-WORKSPACE-UNAVAILABLE"
+
+	GitInputTooLarge          ID = "DRV-GIT-INPUT-TOO-LARGE"
+	GitAmbiguousSyntax        ID = "DRV-GIT-AMBIGUOUS-SYNTAX"
+	GitAmbiguousDynamic       ID = "DRV-GIT-AMBIGUOUS-DYNAMIC"
+	GitAmbiguousAlias         ID = "DRV-GIT-AMBIGUOUS-ALIAS"
+	GitAmbiguousGlobalOption  ID = "DRV-GIT-AMBIGUOUS-GLOBAL-OPTION"
+	GitAmbiguousStdin         ID = "DRV-GIT-AMBIGUOUS-STDIN"
+	GitDestructiveReset       ID = "DRV-GIT-DESTRUCTIVE-RESET"
+	GitDestructiveClean       ID = "DRV-GIT-DESTRUCTIVE-CLEAN"
+	GitDestructiveCheckout    ID = "DRV-GIT-DESTRUCTIVE-CHECKOUT"
+	GitDestructiveRestore     ID = "DRV-GIT-DESTRUCTIVE-RESTORE"
+	GitDestructiveSwitch      ID = "DRV-GIT-DESTRUCTIVE-SWITCH"
+	GitDestructiveRemove      ID = "DRV-GIT-DESTRUCTIVE-RM"
+	GitDestructiveBranch      ID = "DRV-GIT-DESTRUCTIVE-BRANCH"
+	GitDestructiveTag         ID = "DRV-GIT-DESTRUCTIVE-TAG"
+	GitDestructiveUpdateRef   ID = "DRV-GIT-DESTRUCTIVE-UPDATE-REF"
+	GitDestructiveStash       ID = "DRV-GIT-DESTRUCTIVE-STASH"
+	GitDestructiveReflog      ID = "DRV-GIT-DESTRUCTIVE-REFLOG"
+	GitDestructivePrune       ID = "DRV-GIT-DESTRUCTIVE-PRUNE"
+	GitDestructiveHistory     ID = "DRV-GIT-DESTRUCTIVE-HISTORY"
+	GitDestructivePushForce   ID = "DRV-GIT-DESTRUCTIVE-PUSH-FORCE"
+	GitDestructivePushDelete  ID = "DRV-GIT-DESTRUCTIVE-PUSH-DELETE"
+	GitDestructiveWorktree    ID = "DRV-GIT-DESTRUCTIVE-WORKTREE"
+	GitDestructiveRefDeletion ID = "DRV-GIT-DESTRUCTIVE-REF-DELETE"
+
+	AgentNamed                  ID = "DRV-AGENT-NAMED"
+	AgentGenericFallback        ID = "DRV-AGENT-GENERIC-FALLBACK"
+	AgentInlineFallback         ID = "DRV-AGENT-INLINE-FALLBACK"
+	AgentUnavailable            ID = "DRV-AGENT-UNAVAILABLE"
+	AgentResultAccepted         ID = "DRV-AGENT-RESULT-ACCEPTED"
+	AgentResultMalformed        ID = "DRV-AGENT-RESULT-MALFORMED"
+	AgentResultStale            ID = "DRV-AGENT-RESULT-STALE"
+	AgentResultIdentityMismatch ID = "DRV-AGENT-RESULT-IDENTITY-MISMATCH"
+	AgentResultOutOfScope       ID = "DRV-AGENT-RESULT-OUT-OF-SCOPE"
+)
+
+var catalog = []ID{
+	RootSelected,
+	GateReadinessPassed,
+	GateReadinessMissing,
+	GateSealPassed,
+	GateSealMissing,
+	HookDisabled,
+	HookAllowApproved,
+	HookStopClear,
+	HookStopInputInvalid,
+	HookStopReentry,
+	HookStopWorkspaceUnavailable,
+	HookStopRed,
+	HookStopUnsurfacedHumanGate,
+	HookStopMissingProof,
+	HookReviewerReadonlyDenied,
+	HookReviewerReadonlyObserved,
+	HookA1Denied,
+	HookA1Observed,
+	HookWrightScopeDenied,
+	HookWrightScopeObserved,
+	HookWrightForbiddenDenied,
+	HookForgeBindingDenied,
+	HookIngestWarning,
+	GitAuthorityPending,
+	GitAuthorityGranted,
+	GitAuthorityExpired,
+	GitAuthorityRefused,
+	GitAuthorityReplayed,
+	GitAuthorityCorrupt,
+	GitAuthorityUnavailable,
+	GitWorkspaceUnavailable,
+	GitInputTooLarge,
+	GitAmbiguousSyntax,
+	GitAmbiguousDynamic,
+	GitAmbiguousAlias,
+	GitAmbiguousGlobalOption,
+	GitAmbiguousStdin,
+	GitDestructiveReset,
+	GitDestructiveClean,
+	GitDestructiveCheckout,
+	GitDestructiveRestore,
+	GitDestructiveSwitch,
+	GitDestructiveRemove,
+	GitDestructiveBranch,
+	GitDestructiveTag,
+	GitDestructiveUpdateRef,
+	GitDestructiveStash,
+	GitDestructiveReflog,
+	GitDestructivePrune,
+	GitDestructiveHistory,
+	GitDestructivePushForce,
+	GitDestructivePushDelete,
+	GitDestructiveWorktree,
+	GitDestructiveRefDeletion,
+	AgentNamed,
+	AgentGenericFallback,
+	AgentInlineFallback,
+	AgentUnavailable,
+	AgentResultAccepted,
+	AgentResultMalformed,
+	AgentResultStale,
+	AgentResultIdentityMismatch,
+	AgentResultOutOfScope,
+}
+
+var known = func() map[ID]struct{} {
+	out := make(map[ID]struct{}, len(catalog))
+	for _, id := range catalog {
+		if _, duplicate := out[id]; duplicate {
+			panic("duplicate reason id " + id)
+		}
+		out[id] = struct{}{}
+	}
+	return out
+}()
+
+// Parse accepts only identifiers in the frozen catalog.
+func Parse(value string) (ID, error) {
+	id := ID(value)
+	if _, ok := known[id]; !ok {
+		return "", fmt.Errorf("unknown reason id %q", value)
+	}
+	return id, nil
+}
+
+// Known reports whether id belongs to the frozen catalog.
+func Known(id ID) bool {
+	_, ok := known[id]
+	return ok
+}
+
+// All returns the catalog in lexical order for generators and tests.
+func All() []ID {
+	out := append([]ID(nil), catalog...)
+	sort.Slice(out, func(i, j int) bool { return out[i] < out[j] })
+	return out
+}