devrites 6.10.0 → 7.0.0

package/engine/help.go

@@ -12,25 +12,29 @@ import (
 )
 
 const (
-	checkUsage = `usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|slice|diff-scope|skill-trust|indexes|regression|drift|windows|dup> ...
+	checkUsage = `usage: devrites-engine check <candidate|readiness|preconditions|seal|path-disjoint|task-graph|slice|diff-scope|skill-trust|indexes|regression|drift|windows|dup|anchors|perturb> ...
 
   check candidate <slug>
   check readiness <slug>
   check readiness --emit-binding <slug>
+  check preconditions <slug> [--slice SLICE-###] [--timeout N]
   check seal <slug>
   check path-disjoint [--root <dir>] [<json-file>|-]
   check task-graph <slug>
   check slice <slug> <SLICE-ID>
-  check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--cwd <dir>]
+  check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--baseline] [--verbose] [--cwd <dir>]
+  check diff-scope <slug> --snapshot [--worktree|--staged|--base <ref>] [--cwd <dir>]
+  check perturb <slug> --patch <file> --expect <test-name> --gate <G-ID> [--timeout N]
   check skill-trust <path>
   check indexes [--root <dir>]
   check regression <slug> [--update]
   check drift <slug> [--record]
-  check windows <slug> [--worktree|--staged|--base <ref>] [--cwd <dir>]
+  check windows <slug> [--worktree|--staged|--base <ref>|--since-dispatch <wave>] [--cwd <dir>]
   check dup [slug] [--all|--worktree|--staged|--base <ref>]
+  check anchors <slug> <return-file> [--skills-root <dir>]
 `
 
-	stateUsage = `usage: devrites-engine state <resolve|merge-manifest|apply-bundle|close> ...
+	stateUsage = `usage: devrites-engine state <resolve|merge-manifest|apply-bundle|set|append|close> ...
 
   state resolve <qid> "<answer>"
   state resolve --drop <qid> ["<reason>"]
@@ -40,6 +44,8 @@ const (
   state resolve --human --batch <file>
   state merge-manifest <slug> [<predecessor>...]
   state apply-bundle <slug> <bundle.json>... [--dry-run]
+  state set <slug> <key>=<value>... [--unset <key>]...
+  state append <slug> <ledger.md> --heading "<text>" --body-file <path|->
   state close <slug>
 `
 
@@ -51,14 +57,14 @@ const (
 
 	orientUsage  = "usage: devrites-engine orient [slug]"
 	nextUsage    = "usage: devrites-engine next [slug]"
-	handoffUsage = "usage: devrites-engine handoff [slug]"
-	contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--slice <SLICE-###>] [--trigger a,b] [--skills-root <dir>] [--out <path>]`
+	handoffUsage = "usage: devrites-engine handoff [slug] [--resume]"
+	contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--slice <SLICE-###>] [--recheck <inventory>] [--trigger a,b] [--inline-contract] [--whole] [--skills-root <dir>] [--out <path>]`
 	metricsUsage = `usage: devrites-engine metrics <record|summary> ...
 
   metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]
   metrics summary [slug] [--by-slice]
 `
-	dispatchUsage  = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon> [--phase p] [--wave w] [--role r] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>]`
+	dispatchUsage  = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon|attribute> [--phase p] [--wave w] [--role r] [--handle h] [--reason s] [--slice SLICE-###] [--reslice-review <DRIFT-ID>] [--contract <file>] [--packet <file>] [--outcome findings|no-findings|gap] [--result <file>] [--all] [--claim-session <id> --claim <path>... [--claim-ttl <minutes>]] [--release] [--path <path>...]`
 	claimUsageText = `usage: devrites-engine claim <add|release|list|check> ...
 
   claim add --session <id> [--ttl <minutes>] [--reason <s>] <path>...
@@ -66,8 +72,9 @@ const (
   claim list [--session <id>] [--all]
   claim check [--session <id>] <path>...
 `
-	diffScopeUsage = `usage: devrites-engine check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--cwd <dir>]`
-	migrateUsage   = "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]"
+	diffScopeUsage = `usage: devrites-engine check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--baseline] [--verbose] [--cwd <dir>]
+       devrites-engine check diff-scope <slug> --snapshot [--worktree|--staged|--base <ref>] [--cwd <dir>]`
+	migrateUsage = "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]"
 	// scanCmdUsage is help text for `secret-scan`. The identifier must not
 	// contain "secret": gosec G101 treats secret* string consts as credentials.
 	scanCmdUsage        = "usage: devrites-engine secret-scan [--staged] [--stdin] [slug]"
@@ -75,6 +82,7 @@ const (
 	versionUsage        = "usage: devrites-engine version"
 	candidateUsage      = "usage: devrites-engine check candidate <slug>"
 	readinessUsage      = "usage: devrites-engine check readiness <slug>\n       devrites-engine check readiness --emit-binding <slug>"
+	preconditionsUsage  = "usage: devrites-engine check preconditions <slug> [--slice SLICE-###] [--timeout N]"
 	sealUsage           = "usage: devrites-engine check seal <slug>"
 	taskGraphUsage      = "usage: devrites-engine check task-graph <slug>"
 	sliceCheckUsage     = "usage: devrites-engine check slice <slug> <SLICE-ID>"
@@ -83,15 +91,17 @@ const (
 	regressionUsageLine = "usage: devrites-engine check regression <slug> [--update]"
 	driftUsageLine      = "usage: devrites-engine check drift <slug> [--record]"
 	detectUsageLine     = "usage: devrites-engine detect commands [--root <dir>] [--json]"
-	windowsUsageLine    = "usage: devrites-engine check windows <slug> [--worktree|--staged|--base <ref>] [--cwd <dir>]"
+	windowsUsageLine    = "usage: devrites-engine check windows <slug> [--worktree|--staged|--base <ref>|--since-dispatch <wave>] [--cwd <dir>]"
 	dupUsageLine        = "usage: devrites-engine check dup [slug] [--all|--worktree|--staged|--base <ref>] [--min-lines n] [--threshold f] [--ignore-file <path>] [--limit n] [--exclude <csv>] [--phase p] [--cwd <dir>]"
 	resolveUsage        = `usage: devrites-engine state resolve <qid> "<answer>"  |  state resolve --drop <qid> ["<reason>"]  |  state resolve --batch <file>  |  state resolve --human <qid> "<answer>"  |  state resolve --human --drop <qid> ["<reason>"]  |  state resolve --human --batch <file>`
 	mergeManifestUsage  = "usage: devrites-engine state merge-manifest <slug> [<predecessor>...]"
 	applyBundleUsage    = "usage: devrites-engine state apply-bundle <slug> <bundle.json>... [--dry-run]"
 	closeUsage          = "usage: devrites-engine state close <slug>"
+	stateSetUsage       = "usage: devrites-engine state set <slug> <key>=<value>... [--unset <key>]..."
+	stateAppendUsage    = `usage: devrites-engine state append <slug> <ledger.md> --heading "<text>" --body-file <path|->`
 	observeSliceUsage   = "usage: devrites-engine observe slice <slug> <SLICE-ID>"
 	observeSummaryUsage = "usage: devrites-engine observe summary [slug]"
-	gatesFamilyUsage    = `usage: devrites-engine gates <scaffold|status|run|reverify|lint|attest|abandon> <slug> ...
+	gatesFamilyUsage    = `usage: devrites-engine gates <scaffold|status|run|reverify|lint|precheck|attest|abandon> <slug> ...
 
   gates scaffold <slug>            Create gates.md from spec.md AC ids (only when absent)
   gates status <slug>              Reduce the ledger without executing; exit 3 unless ALL MET
@@ -99,6 +109,7 @@ const (
   gates reverify <slug> [--timeout N] [--transcripts]  Re-execute every runnable gate, demoting stale passes
                                    (--transcripts: one redacted, candidate-bound file per gate in references/gates/)
   gates lint <slug> [--strict]     Audit oracle quality without executing
+  gates precheck <slug> --worktree <path>  Run RUN: writer gates + check windows in <path>; no ledger, EVIDENCE or transcript write (check windows logs its metric); never evidence
   gates attest <slug> <id> <note>  Record human evidence on a manual gate
   gates abandon <slug> <id> <why>  Record a terminal ABANDON handoff on a gate
 `
@@ -122,7 +133,7 @@ func isHelpToken(arg string) bool {
 // still in flag position rather than in a value position.
 func takesSubcommand(command string) bool {
 	switch command {
-	case "check", "state", "observe", "parallel", "gates", "claim", "note", "metrics", "detect", "overhaul":
+	case "check", "state", "observe", "parallel", "gates", "claim", "note", "metrics", "detect", "overhaul", "candidate":
 		return true
 	default:
 		return false
@@ -133,9 +144,11 @@ func takesSubcommand(command string) bool {
 // value. A command listed here has known flags, so its help flag is honoured
 // anywhere except as the value of one of these flags.
 var valueFlags = map[string]map[string]bool{
-	"claim":    {"--session": true, "--reason": true, "--ttl": true, "--id": true},
-	"dispatch": {"--phase": true, "--wave": true, "--role": true, "--handle": true, "--reason": true},
-	"recall":   {"--paths": true, "--limit": true},
+	"claim":     {"--session": true, "--reason": true, "--ttl": true, "--id": true},
+	"dispatch":  {"--phase": true, "--wave": true, "--role": true, "--handle": true, "--reason": true, "--claim-session": true, "--claim": true, "--claim-ttl": true, "--path": true},
+	"packet":    {"--wave": true, "--phase": true, "--role": true, "--slice": true, "--checks": true, "--focus": true},
+	"candidate": {"--wave": true, "--slice": true, "--base": true},
+	"recall":    {"--paths": true, "--limit": true},
 }
 
 // hasHelpFlag reports whether args (the arguments after the command word) are a
@@ -173,7 +186,7 @@ func shouldPrintHelp(args []string) bool {
 		return true
 	}
 	switch args[0] {
-	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate", "overhaul", "next", "dispatch", "secret-scan", "open-visual", "recall":
+	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate", "overhaul", "next", "dispatch", "secret-scan", "open-visual", "recall", "packet", "candidate":
 		return len(args) >= 2 && args[1] == "help"
 	default:
 		return false
@@ -225,6 +238,10 @@ func commandHelp(args []string) (string, bool) {
 		return metricsUsage, true
 	case "dispatch":
 		return dispatchUsage, true
+	case "packet":
+		return lib.PacketUsage, true
+	case "candidate":
+		return lib.CandidateFreezeUsage, true
 	case "claim":
 		return claimUsageText, true
 	case "parallel":
@@ -256,6 +273,8 @@ func helpCheck(rest []string) string {
 		return candidateUsage
 	case "readiness":
 		return readinessUsage
+	case "preconditions":
+		return preconditionsUsage
 	case "seal":
 		return sealUsage
 	case "path-disjoint":
@@ -278,6 +297,10 @@ func helpCheck(rest []string) string {
 		return windowsUsageLine
 	case "dup":
 		return dupUsageLine
+	case "anchors":
+		return lib.AnchorsUsage
+	case "perturb":
+		return lib.PerturbUsage
 	default:
 		return checkUsage
 	}
@@ -291,6 +314,10 @@ func helpState(rest []string) string {
 		return mergeManifestUsage
 	case "apply-bundle":
 		return applyBundleUsage
+	case "set":
+		return stateSetUsage
+	case "append":
+		return stateAppendUsage
 	case "close":
 		return closeUsage
 	default:

package/engine/internal/acceptance/approve.go

@@ -16,6 +16,17 @@ type ApprovedCommand struct {
 	Cwd     string // normalized; "" means the repository root
 }
 
+// PreflightRow is one row of test-plan.md's Build-entry preflight table: the
+// approved (command, cwd) pair plus the cells check preconditions reads.
+type PreflightRow struct {
+	ApprovedCommand
+	Gate     string
+	Expected string
+	// RunAt is the optional `Run at` cell (`vet`, `pre-dispatch SLICE-###`,
+	// `action`), whitespace-collapsed; "" when the row or table has none.
+	RunAt string
+}
+
 // ApprovedCommands extracts the approved command surface of test-plan.md: the
 // Command and Cwd cells of every row under `## Build-entry preflight`. No
 // other section approves execution — fenced examples, prose mentions, and
@@ -28,17 +39,29 @@ type ApprovedCommand struct {
 // as "no approval is applicable".
 func ApprovedCommands(testPlan []byte) []ApprovedCommand {
 	approved := []ApprovedCommand{}
+	rows, _ := PreflightRows(testPlan)
+	for _, row := range rows {
+		approved = append(approved, row.ApprovedCommand)
+	}
+	return approved
+}
+
+// PreflightRows parses every command row under `## Build-entry preflight`, the
+// one parser behind the approved surface. hasRunAt reports whether a table in
+// the section declares the optional `Run at` column; plans without it keep
+// the pre-column behavior everywhere.
+func PreflightRows(testPlan []byte) (rows []PreflightRow, hasRunAt bool) {
 	structural, err := markdowntext.Structural(testPlan)
 	if err != nil {
-		return approved
+		return nil, false
 	}
 	inSection := false
-	commandCol, cwdCol := -1, -1
+	commandCol, cwdCol, gateCol, expectedCol, runAtCol := -1, -1, -1, -1, -1
 	for _, line := range strings.Split(string(structural), "\n") {
 		trimmed := strings.TrimSpace(line)
 		if strings.HasPrefix(trimmed, "##") {
 			inSection = strings.EqualFold(trimmed, "## Build-entry preflight")
-			commandCol, cwdCol = -1, -1
+			commandCol = -1
 			continue
 		}
 		if !inSection {
@@ -51,6 +74,10 @@ func ApprovedCommands(testPlan []byte) []ApprovedCommand {
 		if commandCol < 0 {
 			commandCol = columnIndex(cells, "command")
 			cwdCol = columnIndex(cells, "cwd")
+			gateCol = columnIndex(cells, "gate")
+			expectedCol = columnIndex(cells, "expected")
+			runAtCol = columnIndex(cells, "run at")
+			hasRunAt = hasRunAt || (commandCol >= 0 && runAtCol >= 0)
 			continue
 		}
 		if isDividerRow(cells) || commandCol >= len(cells) {
@@ -60,13 +87,25 @@ func ApprovedCommands(testPlan []byte) []ApprovedCommand {
 		if command == "" {
 			continue
 		}
-		cwd := ""
+		row := PreflightRow{ApprovedCommand: ApprovedCommand{Command: command}}
 		if cwdCol >= 0 && cwdCol < len(cells) {
-			cwd = normalizeApprovedCwd(cells[cwdCol])
+			row.Cwd = normalizeApprovedCwd(cells[cwdCol])
 		}
-		approved = append(approved, ApprovedCommand{Command: command, Cwd: cwd})
+		row.Gate = cellText(cells, gateCol)
+		row.Expected = cellText(cells, expectedCol)
+		row.RunAt = strings.Join(strings.Fields(cellText(cells, runAtCol)), " ")
+		rows = append(rows, row)
 	}
-	return approved
+	return rows, hasRunAt
+}
+
+// cellText returns a cell's trimmed text without code backticks, "" when the
+// column is absent or the row is short.
+func cellText(cells []string, col int) string {
+	if col < 0 || col >= len(cells) {
+		return ""
+	}
+	return strings.TrimSpace(strings.Trim(strings.TrimSpace(cells[col]), "`"))
 }
 
 // Approved reports whether (check, cwd) is a vetted pair. Approval is

package/engine/internal/acceptance/cli.go

@@ -33,6 +33,10 @@ Subcommands:
                              (--transcripts writes one redacted, candidate-bound
                              file per gate under references/gates/<gate-id>/)
   lint <slug> [--strict]     Audit oracle quality without executing
+  precheck <slug> --worktree <path>
+                             Run every RUN: writer gate, then check windows, in
+                             <path>; writes no ledger, EVIDENCE line or
+                             transcript (check windows still logs its metric)
   attest <slug> <id> <note>  Record human evidence on a manual gate
   abandon <slug> <id> <why>  Record a terminal ABANDON handoff on a gate
 
@@ -60,6 +64,8 @@ func Run(root string, args []string, stdout, stderr io.Writer) int {
 		return cmdRun(root, rest, true, stdout, stderr)
 	case "lint":
 		return cmdLint(root, rest, stdout, stderr)
+	case "precheck":
+		return cmdPrecheck(root, rest, stdout, stderr)
 	case "attest":
 		return cmdAttest(root, rest, stdout, stderr)
 	case "abandon":
@@ -363,6 +369,102 @@ func cmdLint(root string, args []string, stdout, stderr io.Writer) int {
 	return ExitOK
 }
 
+// WindowsCheck runs `check windows` with the given arguments. main wires it to
+// lib.RunCheckWindows because acceptance cannot import lib (lib imports it).
+var WindowsCheck func(root string, args []string, stdout, stderr io.Writer) int
+
+// cmdPrecheck is the wright's pre-return run of the `RUN: writer` gates and
+// `check windows` against its worktree. It reads gates.md but writes no
+// ledger, EVIDENCE line or transcript: nothing it prints is evidence, and the
+// root still runs every gate canonically.
+func cmdPrecheck(root string, args []string, stdout, stderr io.Writer) int {
+	const usage = "usage: devrites-engine gates precheck <slug> --worktree <path>"
+	var slug, worktree string
+	for i := 0; i < len(args); i++ {
+		switch {
+		case args[i] == "--worktree" && i+1 < len(args) && worktree == "":
+			worktree = args[i+1]
+			i++
+		case strings.HasPrefix(args[i], "-") || slug != "":
+			fmt.Fprintln(stderr, usage)
+			return ExitUsage
+		default:
+			slug = args[i]
+		}
+	}
+	if slug == "" || worktree == "" {
+		fmt.Fprintln(stderr, usage)
+		return ExitUsage
+	}
+	worktree, err := filepath.Abs(worktree)
+	if err == nil {
+		var info os.FileInfo
+		if info, err = os.Stat(worktree); err == nil && !info.IsDir() {
+			err = fmt.Errorf("%s is not a directory", worktree)
+		}
+	}
+	if err != nil {
+		fmt.Fprintf(stderr, "gates precheck: worktree: %v\n", err)
+		return ExitBlocked
+	}
+	_, ledgerPath, testPlanPath, _, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates precheck: %v\n", err)
+		return ExitBlocked
+	}
+	text, err := ReadLedgerFile(ledgerPath)
+	if err != nil {
+		fmt.Fprintf(stderr, "gates precheck: %v\n", err)
+		return ExitBlocked
+	}
+	doc := ParseLedger(text)
+	for _, parseErr := range doc.Errors {
+		fmt.Fprintf(stdout, "error: %s\n", parseErr)
+	}
+	// Like cmdRun: a malformed ledger (e.g. a CWD escaping the worktree) runs nothing.
+	if len(doc.Errors) > 0 {
+		fmt.Fprintln(stdout, "precheck: fail (not evidence; fix before returning)")
+		return ExitBlocked
+	}
+	failed := false
+	approved := loadTestPlan(testPlanPath)
+	for _, gate := range doc.WriterGates() {
+		expectation, expectErr := CompileExpect(gate.Expect)
+		switch {
+		case gate.Check == "":
+			fmt.Fprintf(stdout, "FAIL %s (RUN: writer row has no CHECK)\n", gate.ID)
+		case !Approved(gate.Check, gate.Cwd, approved):
+			fmt.Fprintf(stdout, "FAIL %s (CHECK/CWD is not an approved test-plan.md preflight row; not executed)\n", gate.ID)
+		case expectErr != nil:
+			fmt.Fprintf(stdout, "FAIL %s (%v)\n", gate.ID, expectErr)
+		default:
+			outcome := Execute(context.Background(), gate.Check, filepath.Join(worktree, filepath.FromSlash(gate.Cwd)), DefaultTimeout)
+			if outcome.Err == nil && outcome.ExitCode == 0 && expectation.Matches(outcome.Output) {
+				fmt.Fprintf(stdout, "PASS %s\n", gate.ID)
+				continue
+			}
+			fmt.Fprintf(stdout, "FAIL %s (%s)\n", gate.ID, failDetail(outcome, expectation))
+		}
+		failed = true
+	}
+	switch {
+	case WindowsCheck == nil:
+		fmt.Fprintln(stdout, "FAIL windows (check windows is not wired into this engine)")
+		failed = true
+	case WindowsCheck(root, []string{slug, "--worktree", "--cwd", worktree}, stdout, stderr) != ExitOK:
+		fmt.Fprintln(stdout, "FAIL windows")
+		failed = true
+	default:
+		fmt.Fprintln(stdout, "PASS windows")
+	}
+	if failed {
+		fmt.Fprintln(stdout, "precheck: fail (not evidence; fix before returning)")
+		return ExitBlocked
+	}
+	fmt.Fprintln(stdout, "precheck: pass (not evidence; the root still runs every gate)")
+	return ExitOK
+}
+
 func cmdAttest(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) < 3 {
 		fmt.Fprintln(stderr, "usage: devrites-engine gates attest <slug> <gate-id> <evidence note>")

package/engine/internal/acceptance/exec.go

@@ -104,18 +104,20 @@ func Execute(ctx context.Context, check, cwd string, timeout time.Duration) RunO
 		return RunOutcome{Err: fmt.Errorf("check could not start: %v", startErr)}
 	}
 	waitErr := cmd.Wait()
-	if ctx.Err() == context.DeadlineExceeded {
-		return RunOutcome{Err: fmt.Errorf("check timed out after %s", timeout), TimedOut: true}
-	}
-	if stdout.overflow || stderr.overflow {
-		return RunOutcome{Err: fmt.Errorf("check output exceeded %d bytes", MaxOutputBytes)}
-	}
 	out, errText := stdout.buf.String(), stderr.buf.String()
 	canonical := out
 	if out != "" && errText != "" {
 		canonical += "\n"
 	}
 	canonical += errText
+	if ctx.Err() == context.DeadlineExceeded {
+		// Keep what the check printed before the deadline so its transcript shows
+		// how far it got; Err still fails the gate.
+		return RunOutcome{Err: fmt.Errorf("check timed out after %s", timeout), TimedOut: true, Output: canonical, OutputBytes: len(canonical)}
+	}
+	if stdout.overflow || stderr.overflow {
+		return RunOutcome{Err: fmt.Errorf("check output exceeded %d bytes", MaxOutputBytes)}
+	}
 	if len(canonical) > MaxOutputBytes {
 		return RunOutcome{Err: fmt.Errorf("check output exceeded %d bytes after decoding", MaxOutputBytes)}
 	}

package/engine/internal/acceptance/ledger.go

@@ -31,6 +31,7 @@ type Gate struct {
 	Expect   string
 	Cwd      string
 	Inputs   string // optional whitespace-separated paths/globs the result depends on
+	Run      string // optional "writer": the wright pre-runs it via `gates precheck`; default root
 	Evidence string
 	Line     int // 1-based line of the "- [ ]" row in the original text
 }
@@ -47,7 +48,7 @@ type Document struct {
 
 var (
 	gateLineRE      = regexp.MustCompile(`^\s*- \[([ xX])\] ([^\s:]+): (.*)$`)
-	attrLineRE      = regexp.MustCompile(`^(\s+)(CHECK|EXPECT|CWD|INPUTS|EVIDENCE):(.*)$`)
+	attrLineRE      = regexp.MustCompile(`^(\s+)(CHECK|EXPECT|CWD|INPUTS|EVIDENCE|RUN):(.*)$`)
 	unindentedAttr  = regexp.MustCompile(`^(CHECK|EXPECT|CWD|INPUTS|EVIDENCE):`)
 	abandonLineRE   = regexp.MustCompile(`^ABANDON: (\S+)\s*(.*)$`)
 	indentedAbandon = regexp.MustCompile(`^\s+ABANDON:`)
@@ -117,6 +118,8 @@ func ParseLedger(text string) *Document {
 				current.Cwd = value
 			case "INPUTS":
 				current.Inputs = value
+			case "RUN":
+				current.Run = value
 			case "EVIDENCE":
 				current.Evidence = value
 			}
@@ -253,6 +256,18 @@ func (e Expectation) Matches(output string) bool {
 	return strings.Contains(output, e.Literal)
 }
 
+// WriterGates returns the live gates marked `RUN: writer`. The wright pre-runs
+// them through `gates precheck`; the root still runs every gate canonically.
+func (d *Document) WriterGates() []*Gate {
+	var gates []*Gate
+	for _, gate := range d.Gates {
+		if _, abandoned := d.Abandoned[gate.ID]; !abandoned && gate.Run == "writer" {
+			gates = append(gates, gate)
+		}
+	}
+	return gates
+}
+
 // Newline returns the document's original line-ending style for writeback.
 func (d *Document) Newline() string {
 	if d.newline == "" {

package/engine/internal/acceptance/lint.go

@@ -29,7 +29,8 @@ var (
 
 // LintLedger audits oracle quality without executing anything: fixed-output
 // commands, expectations that also appear in failure output, path-shaped
-// regexes, activity titles, unmeasured numbers, and mostly-manual ledgers.
+// regexes, activity titles, unmeasured numbers, mostly-manual ledgers, and a
+// `RUN:` value precheck cannot honor.
 // approved is the vetted (command, cwd) surface; a runnable CHECK outside it
 // is an authoring error because the runner can never execute it.
 func LintLedger(doc *Document, approved []ApprovedCommand) []Finding {
@@ -76,6 +77,13 @@ func LintLedger(doc *Document, approved []ApprovedCommand) []Finding {
 					"EXPECT %q looks like a literal path but is read as a regular expression, so its dots are wildcards", gate.Expect)
 			}
 		}
+		switch {
+		case gate.Run != "" && gate.Run != "writer" && gate.Run != "root":
+			add("error", gate.ID, "run-value", "RUN %q must be writer or root", gate.Run)
+		case gate.Run == "writer" && gate.Check == "":
+			add("error", gate.ID, "writer-manual",
+				"RUN: writer needs a CHECK: `gates precheck` executes the row, and a manual gate has nothing to execute")
+		}
 		if activityStartRE.MatchString(gate.Title) {
 			add("warn", gate.ID, "activity-not-outcome",
 				"names an activity, not an outcome a stranger could judge: %q", gate.Title)