devrites 5.11.0 → 5.12.0

package/engine/internal/acceptance/run.go

@@ -0,0 +1,207 @@
+package acceptance
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/markdowntext"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// MaxLedgerBytes bounds one ledger read; the artifact budget keeps real
+// ledgers far below it.
+const MaxLedgerBytes = 8 << 20
+
+// ErrOracleMoved marks a discarded result: the gate's bound oracle changed
+// between execution and writeback, so the run must not certify it.
+var ErrOracleMoved = errors.New("gate oracle changed during the run")
+
+// GateResult is one executed gate's outcome line for the report.
+type GateResult struct {
+	ID        string
+	Ran       bool
+	Passed    bool
+	Detail    string // exit/match/timeout/approval diagnostic
+	Discarded bool   // result dropped: ledger changed under the run
+	WriteErr  error  // evidence writeback failed for a reason other than drift
+}
+
+var (
+	uncheckedRE = regexp.MustCompile(`^(\s*)- \[ \] `)
+	checkedRE   = regexp.MustCompile(`^(\s*)- \[[xX]\] `)
+)
+
+// ReadLedgerFile reads a ledger within the size bound. Caller-resolved path.
+func ReadLedgerFile(ledgerPath string) (string, error) {
+	info, err := os.Lstat(ledgerPath)
+	if err != nil {
+		return "", err
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("gate ledger is not a regular file: %s", ledgerPath)
+	}
+	if info.Size() > MaxLedgerBytes {
+		return "", fmt.Errorf("gate ledger exceeds %d bytes: %s", MaxLedgerBytes, ledgerPath)
+	}
+	// #nosec G304 -- ledger path resolved inside the operator workspace
+	raw, err := os.ReadFile(ledgerPath)
+	if err != nil {
+		return "", err
+	}
+	return string(raw), nil
+}
+
+// RunGates executes the runnable gates of ledgerPath. reverify re-runs every
+// runnable gate including already-met ones; the normal mode runs only unmet
+// runnable gates. approved is the vetted command set from test-plan.md; a
+// CHECK outside it never executes. Each pass writes definition-bound evidence;
+// each failure clears the box and restores EVIDENCE: pending.
+//
+// The caller holds the feature lock across this call.
+func RunGates(ctx context.Context, root, ledgerPath string, doc *Document, approved []ApprovedCommand, reverify bool, timeout time.Duration) []GateResult {
+	var results []GateResult
+	for _, gate := range doc.Gates {
+		if _, abandoned := doc.Abandoned[gate.ID]; abandoned {
+			results = append(results, GateResult{ID: gate.ID, Detail: "abandoned; handoff required"})
+			continue
+		}
+		if gate.Check == "" {
+			results = append(results, GateResult{ID: gate.ID, Detail: "manual gate; evidence is judged, not executed"})
+			continue
+		}
+		if GateState(gate, doc) == StateMet && !reverify {
+			results = append(results, GateResult{ID: gate.ID, Passed: true, Detail: "already met"})
+			continue
+		}
+		if approved != nil && !Approved(gate.Check, gate.Cwd, approved) {
+			results = append(results, GateResult{ID: gate.ID, Detail: "CHECK/CWD is not an approved test-plan.md preflight row; not executed"})
+			continue
+		}
+		expectation, err := CompileExpect(gate.Expect)
+		if err != nil {
+			results = append(results, GateResult{ID: gate.ID, Detail: err.Error()})
+			continue
+		}
+		cwd := root
+		if gate.Cwd != "" {
+			cwd = filepath.Join(root, filepath.FromSlash(gate.Cwd))
+		}
+		outcome := Execute(ctx, gate.Check, cwd, timeout)
+		if outcome.Err == nil && outcome.ExitCode == 0 && expectation.Matches(outcome.Output) {
+			evidence := FormatEvidence(gate, OutputDigest(outcome.Output), outcome.OutputBytes, time.Now().UTC().Format(time.RFC3339))
+			writeErr := writeResult(ledgerPath, gate, evidence, true)
+			results = append(results, GateResult{
+				ID: gate.ID, Ran: true, Passed: true,
+				Discarded: errors.Is(writeErr, ErrOracleMoved), WriteErr: writeErr,
+				Detail: resultDetail(writeErr, "pass"),
+			})
+		} else {
+			writeErr := writeResult(ledgerPath, gate, "pending", false)
+			results = append(results, GateResult{
+				ID: gate.ID, Ran: true,
+				Discarded: errors.Is(writeErr, ErrOracleMoved), WriteErr: writeErr,
+				Detail: resultDetail(writeErr, failDetail(outcome, expectation)),
+			})
+		}
+	}
+	return results
+}
+
+func resultDetail(writeErr error, ok string) string {
+	if writeErr == nil {
+		return ok
+	}
+	if errors.Is(writeErr, ErrOracleMoved) {
+		return ok + "; evidence discarded: " + writeErr.Error()
+	}
+	return ok + "; evidence write failed: " + writeErr.Error()
+}
+
+func failDetail(outcome RunOutcome, expectation Expectation) string {
+	if outcome.Err != nil {
+		return outcome.Err.Error()
+	}
+	if outcome.ExitCode != 0 {
+		return fmt.Sprintf("exit %d", outcome.ExitCode)
+	}
+	return fmt.Sprintf("EXPECT %q did not match output", expectation.Literal)
+}
+
+// writeResult re-reads the ledger, verifies the gate's bound oracle is
+// unchanged since it ran, then flips the checkbox and writes the evidence
+// line atomically. A definition that moved in flight discards the result
+// instead of certifying a different oracle.
+func writeResult(ledgerPath string, ran *Gate, evidence string, checked bool) error {
+	text, err := ReadLedgerFile(ledgerPath)
+	if err != nil {
+		return err
+	}
+	doc := ParseLedger(text)
+	var current *Gate
+	for _, gate := range doc.Gates {
+		if gate.ID == ran.ID {
+			current = gate
+			break
+		}
+	}
+	if current == nil {
+		return fmt.Errorf("%w: gate %s disappeared", ErrOracleMoved, ran.ID)
+	}
+	if current.Check != ran.Check || current.Expect != ran.Expect || current.Cwd != ran.Cwd {
+		return fmt.Errorf("%w: gate %s definition edited", ErrOracleMoved, ran.ID)
+	}
+
+	lines := strings.Split(strings.ReplaceAll(text, "\r\n", "\n"), "\n")
+	masked, err := markdowntext.Structural([]byte(text))
+	if err != nil {
+		return err
+	}
+	maskedLines := strings.Split(strings.ReplaceAll(string(masked), "\r\n", "\n"), "\n")
+	row := current.Line - 1
+	if checked {
+		lines[row] = uncheckedRE.ReplaceAllString(lines[row], "${1}- [x] ")
+	} else {
+		lines[row] = checkedRE.ReplaceAllString(lines[row], "${1}- [ ] ")
+	}
+
+	// Attribute-block boundaries come from the masked text so a fenced
+	// EVIDENCE example can never be mistaken for this gate's attribute.
+	evidenceLine := "  EVIDENCE: " + evidence
+	end := row + 1
+	evidenceRow := -1
+	for end < len(maskedLines) {
+		line := maskedLines[end]
+		if attrMatch := attrLineRE.FindStringSubmatch(line); attrMatch != nil {
+			if attrMatch[2] == "EVIDENCE" {
+				evidenceRow = end
+			}
+			end++
+			continue
+		}
+		if strings.TrimSpace(line) == "" {
+			end++
+			continue
+		}
+		break
+	}
+	if evidenceRow >= 0 {
+		lines[evidenceRow] = evidenceLine
+	} else {
+		insertAt := row + 1
+		for insertAt < len(maskedLines) && attrLineRE.MatchString(maskedLines[insertAt]) {
+			insertAt++
+		}
+		lines = append(lines[:insertAt], append([]string{evidenceLine}, lines[insertAt:]...)...)
+	}
+	out := strings.Join(lines, "\n")
+	if doc.Newline() == "\r\n" {
+		out = strings.ReplaceAll(out, "\n", "\r\n")
+	}
+	return state.AtomicWrite(ledgerPath, []byte(out), 0o644)
+}

package/engine/internal/acceptance/scaffold.go

@@ -0,0 +1,55 @@
+package acceptance
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// ScaffoldLedger emits a template ledger: one pending gate per canonical
+// AC-### id found in spec.md, or a single placeholder when the spec names
+// none. It writes nothing; the caller decides whether the file may be
+// created (only when absent).
+func ScaffoldLedger(slug string, spec []byte) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "# Gates: %s\n\n", slug)
+	b.WriteString("Acceptance ledger: one gate per required outcome. Runnable gates pair a\n")
+	b.WriteString("CHECK (an exact command declared in test-plan.md) with an EXPECT oracle;\n")
+	b.WriteString("manual gates carry EVIDENCE only. See devrites-lib standards/gates.md.\n\n")
+	ids := specACIDs(spec)
+	if len(ids) == 0 {
+		b.WriteString("- [ ] G1: <observable outcome>\n")
+		b.WriteString("  CHECK: <exact approved command>\n")
+		b.WriteString("  EXPECT: <success-only marker>\n")
+		b.WriteString("  EVIDENCE: pending\n")
+		return b.String()
+	}
+	for i, id := range ids {
+		if i > 0 {
+			b.WriteString("\n")
+		}
+		fmt.Fprintf(&b, "- [ ] %s: <observable outcome for %s>\n", id, id)
+		b.WriteString("  CHECK: <exact approved command>\n")
+		b.WriteString("  EXPECT: <success-only marker>\n")
+		b.WriteString("  EVIDENCE: pending\n")
+	}
+	return b.String()
+}
+
+var scaffoldACRE = regexp.MustCompile(`\bAC-\d{3}\b`)
+
+// specACIDs returns the unique AC-### ids declared anywhere in the spec; the
+// scaffold does not restrict to one section because the gate contract is the
+// same set the acceptance map already enforces onto tasks.md/test-plan.md.
+func specACIDs(spec []byte) []string {
+	found := scaffoldACRE.FindAllString(string(spec), -1)
+	seen := map[string]bool{}
+	var ids []string
+	for _, id := range found {
+		if !seen[id] {
+			seen[id] = true
+			ids = append(ids, id)
+		}
+	}
+	return ids
+}

package/engine/internal/gate/gate.go

@@ -138,6 +138,12 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			blocked = true
 		}
 	}
+	if len(missingFiles) == 0 {
+		for _, problem := range gateLedgerProblems(observation, policy) {
+			stateProblems = append(stateProblems, "gates: "+problem)
+			blocked = true
+		}
+	}
 	if len(missingFiles) == 0 {
 		for _, problem := range artifactBudgetProblems(observation, policy) {
 			stateProblems = append(stateProblems, "budget: "+problem)
@@ -377,7 +383,7 @@ func retainedHumanGates(observation *state.WorkspaceObservation) ([]string, bool
 	if !ok || (questions.State() != state.ArtifactPresent && questions.State() != state.ArtifactEmpty) {
 		return nil, false
 	}
-	gates := openBlockingQuestionGates(questions.Bytes())
+	gates := OpenBlockingQuestionGates(questions.Bytes())
 	if len(gates) == 0 {
 		return nil, false
 	}
@@ -385,7 +391,11 @@ func retainedHumanGates(observation *state.WorkspaceObservation) ([]string, bool
 	return gates, ok && ledger.State() == state.ArtifactPresent && stateAwaitingHuman(ledger.Bytes())
 }
 
-func openBlockingQuestionGates(data []byte) []string {
+// OpenBlockingQuestionGates returns the deduplicated gate kinds (blocking,
+// validating, escalating) still open in questions.md, tolerating both the
+// per-question block form and the register table form. Exported so the
+// handoff resume record reports the same gates the lifecycle enforces.
+func OpenBlockingQuestionGates(data []byte) []string {
 	lines := splitLinesNoTrailing(data)
 	seen := map[string]bool{}
 	var gates []string

package/engine/internal/gate/gate_test.go

@@ -123,7 +123,7 @@ Goal: looks complete without an ordering field
 func TestCheckAndRenderReadiness(t *testing.T) {
 	root := t.TempDir()
 	writeFeature(t, root, "alpha", map[string]string{
-		"state.md":             "- Phase: build\n- Schema: 3\n",
+		"state.md":             "- Phase: build\n- Schema: 4\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "real spec\n",
 		"assumptions.md":       "none\n",
@@ -134,6 +134,7 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 		"traceability.md":      "traceability\n",
 		"eng-review.md":        "ready\n",
 		"test-plan.md":         "tests\n",
+		"gates.md":             testutil.CanonicalGatesMarkdown,
 	})
 
 	res, err := Check(Readiness, root, "alpha")
@@ -164,7 +165,7 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 	root := t.TempDir()
 	files := map[string]string{
-		"state.md":             "| phase | vet |\n| schema | 3 |\n",
+		"state.md":             "| phase | vet |\n| schema | 4 |\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "spec\n",
 		"decisions.md":         "decisions\n",
@@ -177,6 +178,7 @@ func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 		"traceability.md":      "traceability\n",
 		"eng-review.md":        "ready\n",
 		"test-plan.md":         "", // an empty required file must not satisfy the gate
+		"gates.md":             testutil.CanonicalGatesMarkdown,
 	}
 	writeWorkFeature(t, root, "concrete", files)
 
@@ -192,7 +194,7 @@ func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 func TestSealRequiresDurableReviewAndSealArtifacts(t *testing.T) {
 	root := t.TempDir()
 	files := map[string]string{
-		"state.md":             "| phase | seal |\n| schema | 3 |\n",
+		"state.md":             "| phase | seal |\n| schema | 4 |\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "spec\n",
 		"decisions.md":         "decisions\n",
@@ -205,6 +207,7 @@ func TestSealRequiresDurableReviewAndSealArtifacts(t *testing.T) {
 		"traceability.md":      "traceability\n",
 		"eng-review.md":        "ready\n",
 		"test-plan.md":         "tests\n",
+		"gates.md":             testutil.CanonicalGatesMarkdown,
 		"evidence.md":          "evidence\n",
 		"touched-files.md":     "none\n",
 	}
@@ -373,7 +376,7 @@ func TestCheckBlocksOpenHumanQuestions(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			root := t.TempDir()
 			writeFeature(t, root, "alpha", map[string]string{
-				"state.md":     "- Phase: build\n- Status: " + tc.status + "\n- Schema: 3\n",
+				"state.md":     "- Phase: build\n- Status: " + tc.status + "\n- Schema: 4\n",
 				"spec.md":      "spec\n",
 				"plan.md":      "plan\n",
 				"decisions.md": "decisions\n",
@@ -412,7 +415,7 @@ func TestCheckUsesWorkspaceOverrideForStateInvariants(t *testing.T) {
 	override := filepath.Join(physicalRoot, "work", "alpha")
 	t.Setenv("DEVRITES_WORKSPACE", override)
 	testutil.WriteFile(t, filepath.Join(override, "README.md"), "---\nphase: spec\nschemaVersion: 1\n---\n")
-	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n- Status: running\n- Schema: 3\n")
+	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n- Status: running\n- Schema: 4\n")
 	testutil.WriteFile(t, filepath.Join(override, "spec.md"), "spec\n")
 	testutil.WriteFile(t, filepath.Join(override, "questions.md"), "## q-1\nstatus: open\ngate: blocking\n")
 
@@ -426,7 +429,7 @@ func TestCheckUsesWorkspaceOverrideForStateInvariants(t *testing.T) {
 }
 
 func TestOpenBlockingQuestionGates(t *testing.T) {
-	got := openBlockingQuestionGates([]byte("## Q-1\nstatus: open\ngate: blocking\n\n## Not a question\n\n## q-2\nstatus: open\ngate: validating\n\n## q-3\nstatus: resolved\ngate: blocking\n\n## q-4\nstatus: open\ngate: blocking\n\n## Q-5\nstatus: open\ngate: escalating\n"))
+	got := OpenBlockingQuestionGates([]byte("## Q-1\nstatus: open\ngate: blocking\n\n## Not a question\n\n## q-2\nstatus: open\ngate: validating\n\n## q-3\nstatus: resolved\ngate: blocking\n\n## q-4\nstatus: open\ngate: blocking\n\n## Q-5\nstatus: open\ngate: escalating\n"))
 	want := []string{"blocking", "validating", "escalating"}
 	if strings.Join(got, ",") != strings.Join(want, ",") {
 		t.Fatalf("openBlockingQuestionGates=%v, want %v", got, want)
@@ -443,7 +446,7 @@ func TestCheckObservationUsesRetainedPhaseQuestionsReadinessAndReview(t *testing
 	if err != nil {
 		t.Fatal(err)
 	}
-	testutil.WriteFile(t, filepath.Join(workspace, "state.md"), "- Phase: spec\n- Status: running\n- Schema: 3\n")
+	testutil.WriteFile(t, filepath.Join(workspace, "state.md"), "- Phase: spec\n- Status: running\n- Schema: 4\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "questions.md"), "## q-1\nstatus: open\ngate: blocking\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "plan.md"), "# Plan\n\nChanged after observation.\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "eng-review.md"), "# Engineering review\n\nNo binding.\n")
@@ -609,12 +612,14 @@ func writeCompleteGateFeature(t *testing.T, root, slug string, current, required
 		content := "# " + name + "\n\nreal\n"
 		switch name {
 		case "state.md":
-			content = "- Phase: " + string(current) + "\n- Status: running\n- Schema: 3\n"
+			content = "- Phase: " + string(current) + "\n- Status: running\n- Schema: 4\n"
 		case "questions.md":
 			questionsRequired = true
 			content = questions
 		case "tasks.md":
 			content = testutil.CanonicalTasksMarkdown
+		case "gates.md":
+			content = testutil.CanonicalGatesMarkdown
 		}
 		testutil.WriteFile(t, filepath.Join(root, "work", slug, name), content)
 	}
@@ -696,6 +701,9 @@ func TestCheckBlocksOversizedPacketInWorkspaceRoot(t *testing.T) {
 	// Sanctioned conditional artifact over the ceiling: placement stays legal.
 	testutil.WriteFile(t, filepath.Join(workspace, "references.md"),
 		"# refs\n\n"+strings.Repeat("reference line\n", 6000))
+	// Engine-owned machine files over the ceiling: placement stays legal.
+	testutil.WriteFile(t, filepath.Join(workspace, "metrics.jsonl"),
+		strings.Repeat("{}\n", state.PacketMaxBytes/2))
 	// Unsanctioned root payload over the ceiling: blocked.
 	testutil.WriteFile(t, filepath.Join(workspace, "vet-review-input-031.json"),
 		strings.Repeat("x", state.PacketMaxBytes+1))
@@ -711,7 +719,7 @@ func TestCheckBlocksOversizedPacketInWorkspaceRoot(t *testing.T) {
 	if !strings.Contains(joined, "packets/") {
 		t.Fatalf("remediation must name packets/: %q", joined)
 	}
-	if strings.Contains(joined, "references.md") {
+	if strings.Contains(joined, "references.md") || strings.Contains(joined, "metrics.jsonl") {
 		t.Fatalf("sanctioned root artifact must not be treated as misplaced: %q", joined)
 	}
 }

package/engine/internal/gate/gates_ledger.go

@@ -0,0 +1,76 @@
+package gate
+
+import (
+	"fmt"
+
+	"github.com/devrites/devrites/internal/acceptance"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// maxGateLedgerProblems bounds one gate's invariant lines so a malformed
+// ledger reports a usable diagnostic instead of flooding the render.
+const maxGateLedgerProblems = 8
+
+// gateLedgerProblems reduces the workspace's gates.md acceptance ledger into
+// deterministic problems: a malformed ledger, an abandoned gate's required
+// handoff, an unapproved CHECK (the runner can never execute it), and — once
+// the target phase requires proof — every unmet or stale outcome. The engine
+// reports structure only; whether a manual gate's evidence is honest stays
+// with the Prove/Seal reviewers.
+func gateLedgerProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
+	required := false
+	for _, artifact := range policy.RequiredArtifacts {
+		if artifact == state.ArtifactPath(acceptance.GatesFile) {
+			required = true
+			break
+		}
+	}
+	if !required {
+		return nil
+	}
+	fact, ok := observation.Fact(state.ArtifactPath(acceptance.GatesFile))
+	if !ok || fact.State() != state.ArtifactPresent {
+		return nil // the missing-artifact path already blocks it
+	}
+	doc := acceptance.ParseLedger(string(fact.Bytes()))
+	var problems []string
+	if len(doc.Errors) > 0 {
+		for i, parseErr := range doc.Errors {
+			if i >= maxGateLedgerProblems {
+				problems = append(problems, fmt.Sprintf("... and %d more ledger errors", len(doc.Errors)-maxGateLedgerProblems))
+				break
+			}
+			problems = append(problems, "malformed ledger: "+parseErr)
+		}
+		return problems
+	}
+
+	var testPlan []byte
+	if plan, ok := observation.Fact("test-plan.md"); ok && plan.State() == state.ArtifactPresent {
+		testPlan = plan.Bytes()
+	}
+	approved := acceptance.ApprovedCommands(testPlan)
+	slug := observation.Slug()
+	for _, gate := range doc.Gates {
+		gateState := acceptance.GateState(gate, doc)
+		switch {
+		case gateState == acceptance.StateAbandoned:
+			problems = append(problems, fmt.Sprintf(
+				"gate %s abandoned: %s; hand off the outcome instead of reporting completion",
+				gate.ID, doc.Abandoned[gate.ID]))
+		case gate.Check != "" && !acceptance.Approved(gate.Check, gate.Cwd, approved):
+			problems = append(problems, fmt.Sprintf(
+				"gate %s CHECK/CWD matches no test-plan.md Build-entry preflight row; the gate can never execute",
+				gate.ID))
+		case gateState == acceptance.StateStaleUnmet:
+			problems = append(problems, fmt.Sprintf(
+				"gate %s evidence is stale or malformed; rerun `devrites-engine gates reverify %s`",
+				gate.ID, slug))
+		case gateState != acceptance.StateMet && policy.ProofRequired:
+			problems = append(problems, fmt.Sprintf(
+				"gate %s is unmet; run `devrites-engine gates run %s` or record manual evidence via `gates attest`",
+				gate.ID, slug))
+		}
+	}
+	return problems
+}

package/engine/internal/gate/readiness_binding.go

@@ -139,6 +139,45 @@ func verifyReadinessBinding(observation *state.WorkspaceObservation) (string, er
 	return expected, nil
 }
 
+// ReadinessInputDigest is one readiness input's content identity at a moment
+// in time. The aggregate binding answers "did anything change"; the per-input
+// digest answers "which artifact changed", which is what a drift diagnosis and
+// a re-vet route need.
+type ReadinessInputDigest struct {
+	Path    string `json:"path"`
+	Present bool   `json:"present"`
+	SHA256  string `json:"sha256,omitempty"`
+}
+
+// ReadinessInputDigests returns each readiness input's content digest plus the
+// aggregate binding line Vet records in eng-review.md. A required input that
+// is missing, or any unreadable input, is an error — the same refusal the
+// readiness gate applies.
+func ReadinessInputDigests(root, slug string) ([]ReadinessInputDigest, string, error) {
+	observation, err := state.ObserveWorkspace(root, slug)
+	if err != nil {
+		return nil, "", err
+	}
+	binding, err := readinessBindingFromObservation(observation)
+	if err != nil {
+		return nil, "", err
+	}
+	digests := make([]ReadinessInputDigest, 0, len(readinessInputs))
+	for _, input := range readinessInputs {
+		content, present, err := retainedReadinessInput(observation, input)
+		if err != nil {
+			return nil, "", err
+		}
+		entry := ReadinessInputDigest{Path: string(input.logical), Present: present}
+		if present {
+			sum := sha256.Sum256(content)
+			entry.SHA256 = hex.EncodeToString(sum[:])
+		}
+		digests = append(digests, entry)
+	}
+	return digests, binding, nil
+}
+
 func readinessDiagnosticError(diagnostic state.ArtifactDiagnostic) error {
 	prefix := fmt.Sprintf("readiness input %s is %s (%s); ", diagnostic.Path, diagnostic.State, diagnostic.Code)
 	repair := diagnosticRepair(diagnostic.Code)

package/engine/internal/gate/readiness_binding_test.go

@@ -76,12 +76,12 @@ func TestReadinessBindingBindsOnlyStableBuildInputs(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	for _, name := range []string{"state.md", "questions.md", "decisions.md", "assumptions.md", "eng-review.md", "evidence.md", "review.md", "seal.md", "handoff.md", "ambient.md"} {
+	for _, name := range []string{"state.md", "questions.md", "decisions.md", "assumptions.md", "eng-review.md", "evidence.md", "review.md", "seal.md", "handoff.md", "gates.md", "ambient.md"} {
 		// state.md stays a valid v5 workspace when mutated: the schema row is
 		// part of the contract, not part of the bound inputs.
 		body := "# Mutable\n\nChanged outside the stable contract.\n"
 		if name == "state.md" {
-			body = "| phase | build |\n| schema | 3 |\n" + body
+			body = "| phase | build |\n| schema | 4 |\n" + body
 		}
 		testutil.WriteFile(t, filepath.Join(workspace, name), body)
 		if got := mustReadinessBinding(t, root, "stable"); got != baseline {
@@ -413,7 +413,7 @@ func writeReadinessFixture(t *testing.T, root, slug, phase string) string {
 	t.Helper()
 	workspace := filepath.Join(root, "work", slug)
 	for name, body := range map[string]string{
-		"state.md":             "| phase | " + phase + " |\n| schema | 3 |\n",
+		"state.md":             "| phase | " + phase + " |\n| schema | 4 |\n",
 		"brief.md":             "# Brief\n\nReady.\n",
 		"spec.md":              "# Spec\n\nReady.\n",
 		"decisions.md":         "# Decisions\n\nNone.\n",
@@ -426,6 +426,7 @@ func writeReadinessFixture(t *testing.T, root, slug, phase string) string {
 		"traceability.md":      "# Traceability\n\nReady.\n",
 		"eng-review.md":        "# Engineering review\n\nREADY\n",
 		"test-plan.md":         "# Test plan\n\nReady.\n",
+		"gates.md":             testutil.CanonicalGatesMarkdown,
 	} {
 		testutil.WriteFile(t, filepath.Join(workspace, name), body)
 	}

package/engine/internal/install/install.go

@@ -240,7 +240,13 @@ func Apply(opts Options) error {
 	if opts.Mode == ModeUninstall {
 		return r.uninstall()
 	}
-	return r.install()
+	if err := r.install(); err != nil {
+		return err
+	}
+	if !opts.DryRun {
+		reportStaleWorkspaces(opts.Stdout, r.target)
+	}
+	return nil
 }
 
 func newRunner(opts Options) (*runner, error) {

package/engine/internal/install/install_test.go

@@ -217,7 +217,7 @@ func TestInstallMergesClaudePermissionsIntoExistingSettings(t *testing.T) {
   "statusLine": {"type":"command","command":"DEVRITES_THEME=dark echo user-status"},
   "permissions": {
     "defaultMode": "plan",
-    "allow": ["Bash(user-tool *)"],
+    "allow": ["Bash(user-tool *)", "Bash(git checkout *)", "Bash(devrites-engine retired-cmd *)"],
     "ask": ["Bash(rm *)"]
   },
   "hooks": {"Stop":[{"hooks":[
@@ -231,7 +231,7 @@ func TestInstallMergesClaudePermissionsIntoExistingSettings(t *testing.T) {
 	runInstall(t, target, payload, func(o *Options) { o.Stderr = &stderr })
 
 	settings := testutil.ReadFile(t, filepath.Join(target, ".claude", "settings.json"))
-	for _, preserved := range []string{"keep my local notes", `"theme": "dark"`, "echo user-status", "echo user-stop", "Bash(user-tool *)", "Bash(rm *)"} {
+	for _, preserved := range []string{"keep my local notes", `"theme": "dark"`, "echo user-status", "echo user-stop", "Bash(user-tool *)", "Bash(git checkout *)", "Bash(rm *)"} {
 		if !strings.Contains(settings, preserved) {
 			t.Fatalf("Claude settings lost user content %q:\n%s", preserved, settings)
 		}
@@ -239,6 +239,14 @@ func TestInstallMergesClaudePermissionsIntoExistingSettings(t *testing.T) {
 	if strings.Count(settings, "Bash(devrites-engine check readiness *)") != 1 {
 		t.Fatalf("Claude permission was not merged exactly once:\n%s", settings)
 	}
+	for _, managed := range []string{"mcp__codegraph__*", "Bash(git diff *)", "Edit(.devrites/**)"} {
+		if !strings.Contains(settings, managed) {
+			t.Fatalf("Claude settings merge missed managed rule %q:\n%s", managed, settings)
+		}
+	}
+	if strings.Contains(settings, "retired-cmd") {
+		t.Fatalf("Claude settings merge kept a retired engine rule:\n%s", settings)
+	}
 	if strings.Contains(settings, "devrites-engine hook") {
 		t.Fatalf("installer retained a legacy DevRites hook:\n%s", settings)
 	}
@@ -253,7 +261,7 @@ func TestInstallMergesClaudePermissionsIntoExistingSettings(t *testing.T) {
 
 	runUninstall(t, target)
 	settings = testutil.ReadFile(t, filepath.Join(target, ".claude", "settings.json"))
-	for _, preserved := range []string{"keep my local notes", `"theme": "dark"`, "echo user-status", "echo user-stop", "Bash(user-tool *)", "Bash(rm *)", `"defaultMode": "plan"`} {
+	for _, preserved := range []string{"keep my local notes", `"theme": "dark"`, "echo user-status", "echo user-stop", "Bash(user-tool *)", "Bash(git checkout *)", "Bash(rm *)", `"defaultMode": "plan"`} {
 		if !strings.Contains(settings, preserved) {
 			t.Fatalf("Claude settings uninstall lost user content %q:\n%s", preserved, settings)
 		}
@@ -261,6 +269,11 @@ func TestInstallMergesClaudePermissionsIntoExistingSettings(t *testing.T) {
 	if strings.Contains(settings, "Bash(devrites-engine ") || strings.Contains(settings, "devrites-engine hook") {
 		t.Fatalf("Claude settings uninstall left DevRites configuration:\n%s", settings)
 	}
+	for _, managed := range []string{"mcp__codegraph__*", "Bash(git diff *)", "Edit(.devrites/**)"} {
+		if strings.Contains(settings, managed) {
+			t.Fatalf("Claude settings uninstall left managed non-engine rule %q:\n%s", managed, settings)
+		}
+	}
 }
 
 func TestInstallKeepsClaudeMergeOwnershipAcrossReinstall(t *testing.T) {
@@ -1245,7 +1258,7 @@ func writeTestPayload(t *testing.T, root string) {
 	testutil.WriteFile(t, filepath.Join(root, "claude", "settings.json"), `{
   "permissions": {
     "defaultMode": "plan",
-    "allow": ["Bash(devrites-engine check readiness *)"]
+    "allow": ["Bash(devrites-engine check readiness *)", "mcp__codegraph__*", "Bash(git diff *)", "Edit(.devrites/**)"]
   }
 }`+"\n")
 	testutil.WriteFile(t, filepath.Join(root, "codex", "skills", "rite", "SKILL.md"), "codex rite\n")