devrites 6.10.0 → 7.0.1

package/engine/internal/acceptance/preconditions.go

@@ -0,0 +1,201 @@
+package acceptance
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
+)
+
+const preconditionsUsage = "usage: devrites-engine check preconditions <slug> [--slice SLICE-###] [--timeout N]"
+
+var preDispatchRunAtRE = regexp.MustCompile(`(?i)^pre-dispatch SLICE-\d+$`)
+
+// PreflightGateID names a preflight row's transcript directory. The command
+// and cwd digest keeps two rows sharing a Gate cell apart and retires a
+// transcript the moment its row's command changes.
+func PreflightGateID(row PreflightRow) string {
+	sum := sha256.Sum256([]byte(row.Command + "\x00" + row.Cwd))
+	return "preflight-" + valueOr(row.Gate, "row") + "-" + hex.EncodeToString(sum[:4])
+}
+
+// PreflightRowsPassed reports whether every row has a passing transcript in
+// the feature workspace (see PreflightPassed).
+func PreflightRowsPassed(root, slug string, rows []PreflightRow) (bool, error) {
+	work, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return false, err
+	}
+	for _, row := range rows {
+		if !PreflightPassed(work, row) {
+			return false, nil
+		}
+	}
+	return true, nil
+}
+
+// PreflightPassed reports whether the row's newest transcript under
+// <work>/references/gates/ records RESULT: pass. The transcript records its
+// candidate but the lookup does not compare it: Vet writes workspace artifacts
+// after the run, and only a change to the row's command or cwd retires a pass.
+func PreflightPassed(work string, row PreflightRow) bool {
+	dir := filepath.Join(work, "references", "gates", unsafeNameRE.ReplaceAllString(PreflightGateID(row), "_"))
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return false
+	}
+	newest, newestTime := "", time.Time{}
+	for _, entry := range entries {
+		info, err := entry.Info()
+		if err != nil || !info.Mode().IsRegular() || !strings.HasSuffix(entry.Name(), ".log") {
+			continue
+		}
+		if newest == "" || info.ModTime().After(newestTime) {
+			newest, newestTime = entry.Name(), info.ModTime()
+		}
+	}
+	if newest == "" {
+		return false
+	}
+	// #nosec G304 -- transcript path built from the workspace and a sanitized row id
+	body, err := os.ReadFile(filepath.Join(dir, newest))
+	// Only the header counts: command output could print the verdict line.
+	header, _, _ := strings.Cut(string(body), "--- OUTPUT ---")
+	return err == nil && strings.Contains(header, "\nRESULT: pass\n")
+}
+
+// RunPreconditions is `check preconditions <slug> [--slice S]`: it executes
+// the Build-entry preflight rows whose `Run at` is `vet` (or, with --slice,
+// `pre-dispatch <S>`), writes one candidate-bound transcript per row, and exits
+// ExitBlocked on any failure. Rows are the approved surface itself, so nothing
+// outside test-plan.md runs; `action` rows and rows without a `Run at` cell
+// never run here.
+func RunPreconditions(root string, args []string, stdout, stderr io.Writer) int {
+	var slug, slice string
+	timeout := DefaultTimeout
+	for i := 0; i < len(args); i++ {
+		switch {
+		case (args[i] == "--slice" || args[i] == "--timeout") && i+1 < len(args):
+			if args[i] == "--slice" {
+				slice = args[i+1]
+			} else if n, err := strconv.Atoi(args[i+1]); err == nil && n > 0 {
+				timeout = time.Duration(n) * time.Second
+			} else {
+				fmt.Fprintln(stderr, preconditionsUsage)
+				return ExitUsage
+			}
+			i++
+		case strings.HasPrefix(args[i], "-") || slug != "":
+			fmt.Fprintln(stderr, preconditionsUsage)
+			return ExitUsage
+		default:
+			slug = args[i]
+		}
+	}
+	runAt := "vet"
+	if slice != "" {
+		runAt = "pre-dispatch " + slice
+	}
+	if slug == "" || (slice != "" && !preDispatchRunAtRE.MatchString(runAt)) {
+		fmt.Fprintln(stderr, preconditionsUsage)
+		return ExitUsage
+	}
+	work, ledgerPath, testPlanPath, project, err := featurePaths(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "check preconditions: %v\n", err)
+		return ExitBlocked
+	}
+	var plan []byte
+	if err := state.WithFeatureLock(root, slug, func() error {
+		var err error
+		// #nosec G304 -- workspace artifact path resolved from the operator root
+		plan, err = os.ReadFile(testPlanPath)
+		return err
+	}); err != nil {
+		fmt.Fprintf(stderr, "check preconditions: %v\n", err)
+		return ExitBlocked
+	}
+	rows, _ := PreflightRows(plan)
+	fmt.Fprintf(stdout, "feature: %s\nrun-at: %s\n", slug, runAt)
+
+	// The gates lock serializes execution and transcript attempt numbering
+	// with `gates run` and any concurrent run of the same row.
+	failed, ran := false, false
+	lockErr := state.WithLock(ledgerPath+".lock", func() error {
+		var err error
+		failed, ran, err = runPreflightRows(root, slug, work, project, runAt, rows, timeout, stdout)
+		return err
+	})
+	if lockErr != nil {
+		fmt.Fprintf(stderr, "check preconditions: %v\n", lockErr)
+		return ExitBlocked
+	}
+	switch {
+	case failed:
+		fmt.Fprintln(stdout, "result: fail")
+		return ExitBlocked
+	case !ran:
+		fmt.Fprintln(stdout, "result: none")
+	default:
+		fmt.Fprintln(stdout, "result: pass")
+	}
+	return ExitOK
+}
+
+// runPreflightRows executes the rows whose Run at equals runAt and writes their
+// transcripts. It reports whether any row failed or carried an invalid Run at,
+// and whether any row ran.
+func runPreflightRows(root, slug, work, project, runAt string, rows []PreflightRow, timeout time.Duration, stdout io.Writer) (bool, bool, error) {
+	before := candidateLabel(root, slug)
+	failed := false
+	doc := &Document{}
+	var results []GateResult
+	for _, row := range rows {
+		lower := strings.ToLower(row.RunAt)
+		if lower != "" && lower != "vet" && lower != "action" && !preDispatchRunAtRE.MatchString(row.RunAt) {
+			fmt.Fprintf(stdout, "row %s: invalid Run at %q (want vet, pre-dispatch SLICE-###, or action)\n", valueOr(row.Gate, row.Command), row.RunAt)
+			failed = true
+			continue
+		}
+		if !strings.EqualFold(row.RunAt, runAt) {
+			continue
+		}
+		gate := &Gate{ID: PreflightGateID(row), Title: row.Gate, Check: row.Command, Cwd: row.Cwd,
+			Expect: "exit 0 (Expected: " + valueOr(row.Expected, "unstated") + ")"}
+		cwd := project
+		if row.Cwd != "" {
+			cwd = filepath.Join(project, filepath.FromSlash(row.Cwd))
+		}
+		started := time.Now().UTC()
+		outcome := Execute(context.Background(), row.Command, cwd, timeout)
+		passed := outcome.Err == nil && outcome.ExitCode == 0
+		doc.Gates = append(doc.Gates, gate)
+		results = append(results, GateResult{ID: gate.ID, Ran: true, Passed: passed, Outcome: outcome, Started: started, Ended: time.Now().UTC()})
+		if passed {
+			fmt.Fprintf(stdout, "row %s: pass\n", gate.ID)
+		} else {
+			fmt.Fprintf(stdout, "row %s: fail (%s)\n", gate.ID, exitLabel(outcome))
+			failed = true
+		}
+	}
+	if len(results) > 0 {
+		paths, err := writeTranscripts(work, doc, results, before, candidateLabel(root, slug))
+		for _, path := range paths {
+			fmt.Fprintf(stdout, "transcript: %s\n", path)
+		}
+		if err != nil {
+			return failed, true, fmt.Errorf("transcript: %w", err)
+		}
+	}
+	return failed, len(results) > 0, nil
+}

package/engine/internal/anchor/anchor.go

@@ -0,0 +1,76 @@
+// Package anchor matches a quoted line against file text: whitespace-normalised
+// containment inside a line range, with quotes too short to identify a line
+// rejected. /overhaul admit and `check anchors` share it so both admit the
+// same quotes.
+package anchor
+
+import (
+	"strings"
+	"unicode/utf8"
+)
+
+// MinRunes is the shortest quote (non-space runes) that anchors on its own; a
+// shorter one anchors only when it is the whole cited window.
+const MinRunes = 8
+
+// Result is the outcome of matching one quote.
+type Result int
+
+const (
+	NotFound Result = iota
+	Found
+	TooShort
+)
+
+// Normalize collapses every whitespace run to one space and trims the ends.
+func Normalize(s string) string { return strings.Join(strings.Fields(s), " ") }
+
+// Lines decodes b as text (invalid UTF-8 replaced) split like Python's str.splitlines.
+func Lines(b []byte) []string { return Splitlines(strings.ToValidUTF8(string(b), "�")) }
+
+// Splitlines is Python's str.splitlines().
+func Splitlines(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); {
+		r, size := utf8.DecodeRuneInString(s[i:])
+		i += size
+		switch r {
+		case '\n', '\r', '\v', '\f', 0x1c, 0x1d, 0x1e, 0x85, 0x2028, 0x2029:
+			out = append(out, s[start:i-size])
+			if r == '\r' && i < len(s) && s[i] == '\n' {
+				i++
+			}
+			start = i
+		}
+	}
+	if start < len(s) {
+		out = append(out, s[start:])
+	}
+	return out
+}
+
+// At matches quote inside lines start..end (1-based, inclusive). The caller
+// checks 1 <= start <= end <= len(lines).
+func At(lines []string, start, end int, quote string) Result {
+	q := Normalize(quote)
+	w := Normalize(strings.Join(lines[start-1:end], " "))
+	if q == "" || !strings.Contains(w, q) {
+		return NotFound
+	}
+	if utf8.RuneCountInString(strings.ReplaceAll(q, " ", "")) < MinRunes && q != w {
+		return TooShort
+	}
+	return Found
+}
+
+// Find returns every 1-based line whose own text At admits quote on.
+func Find(lines []string, quote string) []int {
+	var hits []int
+	for i := range lines {
+		if At(lines, i+1, i+1, quote) == Found {
+			hits = append(hits, i+1)
+		}
+	}
+	return hits
+}

package/engine/internal/gate/drivers.go

@@ -0,0 +1,144 @@
+package gate
+
+import (
+	"fmt"
+	"regexp"
+	"slices"
+	"strings"
+
+	"github.com/devrites/devrites/internal/acceptance"
+	"github.com/devrites/devrites/internal/markdowntext"
+	"github.com/devrites/devrites/internal/state"
+)
+
+var (
+	// testDriverRE matches a test driver script: a file under a scripts/
+	// directory whose basename carries a whole test/tests word
+	// (scripts/dev-run-test.sh, scripts/run-tests.mjs). Word boundaries keep
+	// latest-release.sh and attest.sh out, and unit test files outside
+	// scripts/ are run by a driver rather than being one.
+	testDriverRE = regexp.MustCompile(`(?:^|/)scripts/(?:[^/]+/)*(?:[^/]*[-_.])?tests?(?:[-_.][^/]*)?\.(?:sh|bash|py|mjs|js)$`)
+	// writerAllowlistRE reads a tasks.md slice field the way the task parser
+	// does: a column-1 `Writer allowlist:` line of `,`/`;` separated paths.
+	writerAllowlistRE = regexp.MustCompile(`(?im)^writer allowlist:[ \t]*(.*)$`)
+	// touchedPresentRE reads a `present` row of touched-files.md's candidate
+	// manifest table (| State | File | Slice | Reason |).
+	touchedPresentRE = regexp.MustCompile("(?m)^\\|[ \t]*present[ \t]*\\|[ \t]*`([^`]+)`[ \t]*\\|")
+	// driverWaiverRE reads `Driver waiver: <path> — <DEC-id> <reason>` from
+	// gates.md; the first DEC id on the line is the backing decision, and a
+	// reason must follow it after a space or `:`/`,`/`.`/`;`.
+	driverWaiverRE    = regexp.MustCompile("(?m)^Driver waiver:[ \t]*`?([^\\s`]+)`?.*?\\b(DEC-[A-Za-z0-9-]*[A-Za-z0-9])[ \t:,.;]+\\S")
+	decisionHeadingRE = regexp.MustCompile(`(?m)^#{1,6}[ \t]+(DEC-[A-Za-z0-9-]*[A-Za-z0-9])`)
+)
+
+// testDriverProblems blocks a test driver script the feature plans to write (a
+// tasks.md Writer allowlist, before proof) or touched (a touched-files.md
+// present row, once proof is required) when no gates.md CHECK executes it and
+// no `Driver waiver:` line cites a DEC id that decisions.md records. A touched
+// driver no gate runs can be red at seal unnoticed. Waived drivers are returned
+// separately so the gate output names every deferral.
+func testDriverProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) (problems, waived []string) {
+	if !slices.Contains(policy.RequiredArtifacts, state.ArtifactPath(acceptance.GatesFile)) {
+		return nil, nil
+	}
+	gatesText := structuralFact(observation, state.ArtifactPath(acceptance.GatesFile))
+	doc := acceptance.ParseLedger(gatesText)
+	if len(doc.Errors) > 0 {
+		return nil, nil // gateLedgerProblems already blocks a malformed ledger
+	}
+
+	source, re := "tasks.md", writerAllowlistRE
+	if policy.ProofRequired {
+		source, re = "touched-files.md", touchedPresentRE
+	}
+	var drivers []string
+	for _, match := range re.FindAllStringSubmatch(structuralFact(observation, state.ArtifactPath(source)), -1) {
+		for _, part := range strings.FieldsFunc(match[1], func(r rune) bool { return r == ',' || r == ';' }) {
+			driver := strings.TrimPrefix(strings.Trim(strings.TrimSpace(part), "`'\""), "./")
+			if testDriverRE.MatchString(driver) && !slices.Contains(drivers, driver) {
+				drivers = append(drivers, driver)
+			}
+		}
+	}
+	if len(drivers) == 0 {
+		return nil, nil
+	}
+	slices.Sort(drivers)
+
+	waivers := map[string]string{}
+	for _, match := range driverWaiverRE.FindAllStringSubmatch(gatesText, -1) {
+		waivers[strings.TrimPrefix(match[1], "./")] = match[2]
+	}
+	decisions := map[string]bool{}
+	for _, match := range decisionHeadingRE.FindAllStringSubmatch(structuralFact(observation, "decisions.md"), -1) {
+		decisions[match[1]] = true
+	}
+	for _, driver := range drivers {
+		if driverExecuted(driver, doc.Gates) {
+			continue
+		}
+		decision, ok := waivers[driver]
+		switch {
+		case !ok:
+			problems = append(problems, fmt.Sprintf(
+				"test driver %s is in %s but no gates.md CHECK executes it; add a CHECK or a DEC-backed `Driver waiver: %s — DEC-### <reason>` line",
+				driver, source, driver))
+		case !decisions[decision]:
+			problems = append(problems, fmt.Sprintf(
+				"test driver %s waiver cites %s, which has no decisions.md heading; record that decision or add a CHECK",
+				driver, decision))
+		default:
+			waived = append(waived, fmt.Sprintf("unexecuted driver (waived by %s): %s", decision, driver))
+		}
+	}
+	return problems, waived
+}
+
+// driverExecuted reports whether a CHECK names the driver by its
+// repository-relative path, or by its path relative to the gate's CWD.
+func driverExecuted(driver string, gates []*acceptance.Gate) bool {
+	for _, gate := range gates {
+		if gate.Check == "" {
+			continue
+		}
+		if namesPath(gate.Check, driver) {
+			return true
+		}
+		cwd := strings.TrimSuffix(strings.TrimPrefix(gate.Cwd, "./"), "/")
+		if rel, ok := strings.CutPrefix(driver, cwd+"/"); ok && namesPath(gate.Check, rel) {
+			return true
+		}
+	}
+	return false
+}
+
+// namesPath reports whether check contains path as a whole path: at the start,
+// or after whitespace, a quote, '=' or a leading "./" or "../", so
+// tools/scripts/test.sh never satisfies scripts/test.sh.
+func namesPath(check, path string) bool {
+	for from := 0; ; {
+		i := strings.Index(check[from:], path)
+		if i < 0 {
+			return false
+		}
+		at := from + i
+		if at == 0 || strings.ContainsRune(" \t'\"=", rune(check[at-1])) || strings.HasSuffix(check[:at], "./") {
+			return true
+		}
+		from = at + 1
+	}
+}
+
+// structuralFact returns a present artifact's text with fenced examples
+// masked, or "" when it is absent or unreadable.
+func structuralFact(observation *state.WorkspaceObservation, path state.ArtifactPath) string {
+	fact, ok := observation.Fact(path)
+	if !ok || fact.State() != state.ArtifactPresent {
+		return ""
+	}
+	structural, err := markdowntext.Structural(fact.Bytes())
+	if err != nil {
+		return ""
+	}
+	return string(structural)
+}

package/engine/internal/gate/gate.go

@@ -7,6 +7,7 @@ package gate
 import (
 	"fmt"
 	"regexp"
+	"slices"
 	"strings"
 
 	"github.com/devrites/devrites/internal/markdowntext"
@@ -38,6 +39,7 @@ type Result struct {
 	Diagnostics     []state.ArtifactDiagnostic
 	AddContentFiles []string
 	StateProblems   []string
+	Notes           []string // non-blocking lines printed pass or blocked, e.g. waived test drivers
 	Blocked         bool
 	ReasonID        reason.ID
 }
@@ -53,6 +55,20 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 	if err != nil {
 		return nil, fmt.Errorf("gate %s: %w", kind, err)
 	}
+	for _, problem := range dependencyDryRunProblems(kind, root, observation) {
+		result.StateProblems = append(result.StateProblems, "preconditions: "+problem)
+		if !result.Blocked {
+			result.Blocked = true
+			result.ReasonID = ResultReasonID(kind, true)
+		}
+	}
+	if kind == Readiness {
+		for _, problem := range predecessorProblems(root, observation) {
+			result.StateProblems = append(result.StateProblems, "predecessor: "+problem)
+			result.Blocked = true
+			result.ReasonID = reason.GateReadinessStale
+		}
+	}
 	for _, problem := range unsanctionedRootFiles(observation) {
 		result.StateProblems = append(result.StateProblems, "placement: "+problem)
 		// Keep a more specific reason (readiness-stale) when the observation
@@ -150,6 +166,15 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			blocked = true
 		}
 	}
+	var notes []string
+	if len(missingFiles) == 0 {
+		driverProblems, waived := testDriverProblems(observation, policy)
+		for _, problem := range driverProblems {
+			stateProblems = append(stateProblems, "gates: "+problem)
+			blocked = true
+		}
+		notes = waived
+	}
 	if len(missingFiles) == 0 {
 		for _, problem := range artifactBudgetProblems(observation, policy) {
 			stateProblems = append(stateProblems, "budget: "+problem)
@@ -165,10 +190,7 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			continue
 		}
 		if diagnostic, has := fact.Diagnostic(); has && diagnostic.Code == state.DiagnosticFileTooLarge {
-			stateProblems = append(stateProblems, fmt.Sprintf(
-				"budget: %s exceeds the %d-byte artifact cap; relocate history (history/<file>-<YYYYMMDD>.md) or split the feature via /rite-plan revise|course-correct",
-				artifact, state.MaxArtifactBytes,
-			))
+			stateProblems = append(stateProblems, "budget: "+readCapProblem(artifact))
 			blocked = true
 		}
 	}
@@ -196,6 +218,7 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 		Diagnostics:     diagnostics,
 		AddContentFiles: addContentFiles,
 		StateProblems:   stateProblems,
+		Notes:           notes,
 		Blocked:         blocked,
 	}
 	result.ReasonID = ResultReasonID(kind, blocked)
@@ -205,18 +228,25 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 	return result, nil
 }
 
-// artifactBudgetProblems blocks a required artifact only on a material overshoot
-// (>= state.BudgetBlockFactor of a line or byte budget) with no structural
-// `Budget override:` line. Smaller overshoots stay advisory and are reported by
-// `orient`.
+// artifactBudgetProblems blocks every present budget-gated artifact, required
+// by the phase or not (an unrequired drift.md once grew to 7x its budget), on a
+// material overshoot (>= state.BudgetBlockFactor of a line or byte budget) that
+// no bounded `Budget override: <=N lines; <reason>` line covers. Smaller
+// overshoots stay advisory and are reported by `orient`.
 func artifactBudgetProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
 	var problems []string
-	for _, artifact := range policy.RequiredArtifacts {
+	for _, artifact := range state.BudgetGatedArtifacts() {
 		fact, ok := observation.Fact(artifact)
-		if !ok || fact.State() != state.ArtifactPresent {
+		if !ok {
 			continue
 		}
-		if !state.ArtifactBudgetGateApplies(string(artifact)) {
+		// A required artifact over the read cap is already reported with the
+		// missing files; an unrequired one is caught only here.
+		if diagnostic, has := fact.Diagnostic(); has && diagnostic.Code == state.DiagnosticFileTooLarge && !slices.Contains(policy.RequiredArtifacts, artifact) {
+			problems = append(problems, readCapProblem(artifact))
+			continue
+		}
+		if fact.State() != state.ArtifactPresent {
 			continue
 		}
 		status, ok := state.ArtifactBudget(string(artifact), fact.Bytes())
@@ -224,14 +254,21 @@ func artifactBudgetProblems(observation *state.WorkspaceObservation, policy stat
 			continue
 		}
 		problems = append(problems, fmt.Sprintf(
-			"%s is %d lines/%d bytes, at or above %gx its %d-line/%d-byte budget; relocate history (history/<file>-<YYYYMMDD>.md) or split the feature via /rite-plan revise|course-correct, or record a structural `Budget override: <reason>` line",
+			"%s is %d lines/%d bytes, at or above %gx its %d-line/%d-byte budget; %s",
 			status.File, status.Lines, status.Bytes, state.BudgetBlockFactor,
-			status.LineBudget, status.ByteBudget,
+			status.LineBudget, status.ByteBudget, state.BudgetRemedy(status.LineBudget),
 		))
 	}
 	return problems
 }
 
+func readCapProblem(artifact state.ArtifactPath) string {
+	return fmt.Sprintf(
+		"%s exceeds the %d-byte artifact cap; relocate history (history/<file>-<YYYYMMDD>.md) or split the feature via /rite-plan revise|course-correct",
+		artifact, state.MaxArtifactBytes,
+	)
+}
+
 func acceptanceMapProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
 	requireTasks := phaseRequiresTasks(policy)
 	requireTestPlan := phaseRequiresTestPlan(policy)
@@ -350,6 +387,9 @@ func (r *Result) Render() string {
 	if !r.Blocked {
 		b.WriteString("result: pass\n")
 		fmt.Fprintf(&b, "reason: %s\n", r.ReasonID)
+		for _, note := range r.Notes {
+			fmt.Fprintf(&b, "note: %s\n", note)
+		}
 		return b.String()
 	}
 	missing := r.MissingFiles
@@ -377,6 +417,9 @@ func (r *Result) Render() string {
 	for _, problem := range r.StateProblems {
 		fmt.Fprintf(&b, "invariant: %s\n", problem)
 	}
+	for _, note := range r.Notes {
+		fmt.Fprintf(&b, "note: %s\n", note)
+	}
 	fmt.Fprintf(&b, "retry: devrites-engine check %s %s\n", r.Kind, r.Slug)
 	return b.String()
 }

package/engine/internal/gate/preconditions.go

@@ -0,0 +1,121 @@
+package gate
+
+import (
+	"fmt"
+	"path"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/acceptance"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// DependencyManifests pairs each package manifest with its lockfiles; an edit
+// to any of them changes dependency resolution.
+var DependencyManifests = []struct {
+	Manifest string
+	Locks    []string
+}{
+	{"go.mod", []string{"go.sum"}},
+	{"Cargo.toml", []string{"Cargo.lock"}},
+	{"package.json", []string{"package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"}},
+	{"pyproject.toml", []string{"uv.lock", "poetry.lock"}},
+	{"Pipfile", []string{"Pipfile.lock"}},
+}
+
+// dependencyManifests are the manifest and lockfile basenames whose edit
+// changes dependency resolution, which only a dry run observes before Build.
+var dependencyManifests = func() map[string]bool {
+	names := map[string]bool{}
+	for _, m := range DependencyManifests {
+		names[m.Manifest] = true
+		for _, lock := range m.Locks {
+			names[lock] = true
+		}
+	}
+	return names
+}()
+
+var slicePathFieldRE = regexp.MustCompile(`(?im)^\s*(?:[-*]\s+)?(?:files likely touched|writer allowlist):\s*(.*)$`)
+
+// dependencyDryRunProblems blocks leaving Vet while a slice that edits a
+// dependency manifest lacks a `dependency-dry-run <SLICE>` Build-entry
+// preflight row with `Run at` `vet` whose newest transcript passed. Test plans
+// without the `Run at` column predate the requirement and keep today's
+// behavior.
+func dependencyDryRunProblems(kind Kind, root string, observation *state.WorkspaceObservation) []string {
+	if kind != Readiness {
+		return nil
+	}
+	if phase, err := observation.DeclaredPhase(); err != nil || phase != state.PhaseVet {
+		return nil
+	}
+	tasks, ok := observation.Fact("tasks.md")
+	plan, planOK := observation.Fact("test-plan.md")
+	if !ok || !planOK || tasks.State() != state.ArtifactPresent || plan.State() != state.ArtifactPresent {
+		return nil // the missing-artifact path already blocks it
+	}
+	rows, hasRunAt := acceptance.PreflightRows(plan.Bytes())
+	if !hasRunAt {
+		return nil
+	}
+	slug := observation.Slug()
+	var problems []string
+	for _, slice := range state.ParseTaskGraph(tasks.Bytes()).Slices {
+		block, _ := state.ExtractTaskSlice(tasks.Bytes(), slice.ID)
+		manifest := touchedManifest(block)
+		if manifest == "" {
+			continue
+		}
+		matching := dryRunRows(rows, slice.ID)
+		switch {
+		case len(matching) == 0:
+			problems = append(problems, fmt.Sprintf(
+				"%s touches %s but test-plan.md has no `dependency-dry-run %s` Build-entry preflight row with Run at `vet`; add one that applies the planned change in an isolated copy, runs the tidy/lock step, then the project's admission checks",
+				slice.ID, manifest, slice.ID))
+		default:
+			passed, err := acceptance.PreflightRowsPassed(root, slug, matching)
+			if err != nil {
+				return []string{fmt.Sprintf("dependency dry-run transcripts cannot be read: %v", err)}
+			}
+			if passed {
+				continue
+			}
+			problems = append(problems, fmt.Sprintf(
+				"%s dependency dry run has a row without a passing transcript; run `devrites-engine check preconditions %s` and route a failure to Plan repair",
+				slice.ID, slug))
+		}
+	}
+	return problems
+}
+
+func touchedManifest(block string) string {
+	for _, match := range slicePathFieldRE.FindAllStringSubmatch(block, -1) {
+		for _, part := range strings.FieldsFunc(match[1], func(r rune) bool { return r == ';' || r == ',' }) {
+			if name := path.Base(strings.Trim(strings.TrimSpace(part), "`'\"")); dependencyManifests[name] {
+				return name
+			}
+		}
+	}
+	return ""
+}
+
+func dryRunRows(rows []acceptance.PreflightRow, sliceID string) []acceptance.PreflightRow {
+	var matching []acceptance.PreflightRow
+	for _, row := range rows {
+		if strings.EqualFold(row.RunAt, "vet") && strings.Contains(row.Gate, "dependency-dry-run") &&
+			containsToken(row.Gate, sliceID) {
+			matching = append(matching, row)
+		}
+	}
+	return matching
+}
+
+func containsToken(text, token string) bool {
+	for _, field := range strings.FieldsFunc(text, func(r rune) bool { return r == ' ' || r == ',' || r == ';' }) {
+		if field == token {
+			return true
+		}
+	}
+	return false
+}