devrites 6.9.6 → 7.0.0

package/engine/internal/lib/anchors.go

@@ -0,0 +1,270 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/devrites/devrites/internal/anchor"
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/safepath"
+)
+
+// anchors.go: deterministic quote anchoring for one reviewer return.
+// agents.md § Result admission has root anchor each Critical/Important row's
+// quote at its cited file:line and its `breaks` quote in the spec or standard it
+// names before the row counts as a finding. This check does that with the same
+// matcher /overhaul admit uses, so no row reaches a repair round on a quote
+// nobody can find.
+//
+//	devrites-engine check anchors <slug> <return-file> [--skills-root <dir>]
+//
+//	0  every Critical/Important row anchored (exact or relocated)
+//	2  usage error, workspace or return unreadable
+//	3  blocked: an Unverified or Deferred row, which never drives a repair round
+//
+// A row's site is the first `;`-separated location in its second cell
+// (`path:line[-line]`, or a workspace .md file with no line); its quote is the
+// first backticked span in its observed cell. Paths resolve in the workspace,
+// then the project. Exact match at the cited lines anchors; a quote on exactly
+// one other line relocates; otherwise the row is Unverified (anchor lost or
+// ambiguous). The `breaks "<quote>"` cell must quote spec.md/decisions.md for a
+// spec ID, or the named shipped standard (under --skills-root when a host passes
+// it); with no quote the row is Deferred.
+
+// AnchorsUsage is the help and usage-error text for `check anchors`.
+const AnchorsUsage = "usage: devrites-engine check anchors <slug> <return-file> [--skills-root <dir>]"
+
+var (
+	anchorSiteRE     = regexp.MustCompile(`^(\S+?)(?::([0-9]+)(?::[0-9]+)?(?:[-–]([0-9]+))?)?$`)
+	anchorSeverityRE = regexp.MustCompile(`(?i)^\W*(critical|important)\b`)
+)
+
+type anchorer struct{ root, project, workspace, skillsRoot string }
+
+// RunCheckAnchors implements `devrites-engine check anchors`.
+func RunCheckAnchors(root string, args []string, stdout, stderr io.Writer) int {
+	var positional []string
+	skillsRoot := ""
+	for i := 0; i < len(args); i++ {
+		if args[i] == "--skills-root" && i+1 < len(args) {
+			skillsRoot = args[i+1]
+			i++
+			continue
+		}
+		positional = append(positional, args[i])
+	}
+	if len(positional) != 2 || strings.HasPrefix(positional[0], "-") || strings.HasPrefix(positional[1], "-") {
+		fmt.Fprintln(stderr, AnchorsUsage)
+		return 2
+	}
+	args = positional
+	slug := args[0]
+	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "check anchors: %v\n", err)
+		return 2
+	}
+	raw, err := readBoundedRegularFile(args[1], maxReturnBytes)
+	if err != nil {
+		fmt.Fprintf(stderr, "check anchors: %s: %v\n", args[1], err)
+		return 2
+	}
+	// The digest lets root confirm it anchored on the candidate the reviewer saw.
+	if digest, n, err := CandidateIdentity(root, slug); err == nil {
+		fmt.Fprintf(stdout, "check anchors: candidate %s (%d files)\n", digest, n)
+	} else {
+		fmt.Fprintf(stdout, "check anchors: no candidate (%v); quotes read the live tree\n", err)
+	}
+	a := anchorer{root: root, project: projectDir(root), workspace: workspace, skillsRoot: skillsRoot}
+	counts := map[string]int{}
+	rows := 0
+	for i, line := range strings.Split(string(raw), "\n") {
+		// Fail closed on format drift: a bulleted row or a bold/colon severity is still a blocker row.
+		row, ok := strings.CutPrefix(strings.TrimLeft(line, " \t-*•"), "Finding:")
+		if !ok {
+			continue
+		}
+		cells := splitFindingCells(row)
+		if !anchorSeverityRE.MatchString(cells[0]) {
+			continue
+		}
+		rows++
+		status, detail := a.row(cells)
+		counts[status]++
+		switch claim := strings.TrimSpace(row); status {
+		case "Unverified":
+			fmt.Fprintf(stdout, "%d: Unverified: %s — %s\n", i+1, claim, detail)
+		case "Deferred":
+			fmt.Fprintf(stdout, "%d: Deferred: %s — no spec anchor\n", i+1, claim)
+		default:
+			fmt.Fprintf(stdout, "%d: %s %s\n", i+1, status, detail)
+		}
+	}
+	summary := fmt.Sprintf("anchored=%d relocated=%d unverified=%d deferred=%d",
+		counts["anchored"], counts["relocated"], counts["Unverified"], counts["Deferred"])
+	recordMetricNote(root, slug, cursorPhase(root, slug), "anchors", "", summary)
+	if counts["Unverified"]+counts["Deferred"] > 0 {
+		fmt.Fprintf(stdout, "check anchors: BLOCKED: %d Critical/Important rows, %s; Unverified and Deferred rows never drive a repair round\n", rows, summary)
+		return 3
+	}
+	fmt.Fprintf(stdout, "check anchors: OK: %d Critical/Important rows, %s\n", rows, summary)
+	return 0
+}
+
+// row classifies one blocker row: anchored, relocated, Unverified or Deferred.
+func (a anchorer) row(cells []string) (status, detail string) {
+	if len(cells) < 3 {
+		return "Unverified", "missing file:line"
+	}
+	status, detail = a.site(cells[1], cells[2])
+	if status == "Unverified" {
+		return status, detail
+	}
+	if bs, bd := a.breaks(cells[2:]); bs != "anchored" {
+		return bs, bd
+	}
+	return status, detail
+}
+
+// site anchors the observed quote at the row's cited location.
+func (a anchorer) site(location, observed string) (status, detail string) {
+	cited := strings.TrimSpace(strings.Split(strings.ReplaceAll(location, "`", ""), ";")[0])
+	cited, _, _ = strings.Cut(cited, "§")
+	cited = strings.TrimSpace(cited)
+	m := anchorSiteRE.FindStringSubmatch(cited)
+	if m == nil || m[2] == "" && !strings.HasSuffix(m[1], ".md") {
+		return "Unverified", "missing file:line"
+	}
+	_, rest, hasQuote := strings.Cut(observed, "`")
+	quote, _, closed := strings.Cut(rest, "`")
+	if !hasQuote || !closed || strings.TrimSpace(quote) == "" {
+		return "Unverified", "missing quote"
+	}
+	lines, err := a.lines(m[1])
+	if err != nil {
+		return "Unverified", "anchor lost: " + err.Error()
+	}
+	if m[2] != "" {
+		s, _ := strconv.Atoi(m[2])
+		e := s
+		if m[3] != "" {
+			e, _ = strconv.Atoi(m[3])
+		}
+		if 1 <= s && s <= e && e <= len(lines) {
+			switch anchor.At(lines, s, e, quote) {
+			case anchor.Found:
+				return "anchored", cited
+			case anchor.TooShort:
+				return "Unverified", fmt.Sprintf("anchor ambiguous: quote under %d characters; quote the whole line", anchor.MinRunes)
+			}
+		}
+	}
+	// shortcut: relocation searches single lines; a quote spanning lines anchors only at its cited range.
+	switch hits := anchor.Find(lines, quote); {
+	case len(hits) == 1 && m[2] == "":
+		return "anchored", fmt.Sprintf("%s:%d", m[1], hits[0])
+	case len(hits) == 1:
+		return "relocated", fmt.Sprintf("%s -> %s:%d", cited, m[1], hits[0])
+	case len(hits) == 0:
+		return "Unverified", "anchor lost"
+	}
+	return "Unverified", "anchor ambiguous"
+}
+
+// breaks anchors the `breaks <anchor> "<quote>"` cell in the spec or standard it names.
+func (a anchorer) breaks(cells []string) (status, detail string) {
+	for _, cell := range cells {
+		cited, ok := strings.CutPrefix(strings.TrimSpace(cell), "breaks ")
+		if !ok {
+			continue
+		}
+		open := strings.IndexAny(cited, "\"“")
+		closing := strings.LastIndexAny(cited, "\"”")
+		if open < 0 || closing <= open {
+			return "Deferred", ""
+		}
+		_, size := utf8.DecodeRuneInString(cited[open:])
+		name, quote := cited[:open], cited[open+size:closing]
+		var paths []string
+		switch base := mdName(name); base {
+		case "":
+			paths = []string{filepath.Join(a.workspace, "spec.md"), filepath.Join(a.workspace, "decisions.md")}
+		case "spec.md", "decisions.md":
+			paths = []string{filepath.Join(a.workspace, base)}
+		default:
+			if skills, err := resolveSkillsRoot(a.root, a.skillsRoot); err == nil {
+				paths = []string{filepath.Join(skills, "devrites-lib", "reference", "standards", base)}
+			}
+		}
+		var text []string
+		for _, p := range paths {
+			if raw, err := readBoundedRegularFile(p, workspaceArtifactLimit); err == nil {
+				text = append(text, anchor.Lines(raw)...)
+			}
+		}
+		if len(text) == 0 {
+			return "Unverified", fmt.Sprintf("breaks anchor lost: %s is unreadable", strings.TrimSpace(name))
+		}
+		// One window over the whole text, so a quote wrapped across lines matches.
+		switch anchor.At([]string{strings.Join(text, " ")}, 1, 1, quote) {
+		case anchor.NotFound:
+			return "Unverified", "breaks anchor lost"
+		case anchor.TooShort:
+			return "Unverified", fmt.Sprintf("breaks anchor ambiguous: quote under %d characters", anchor.MinRunes)
+		}
+		return "anchored", ""
+	}
+	return "Deferred", ""
+}
+
+// lines reads a cited file from the workspace, else the project, never outside them.
+func (a anchorer) lines(rel string) ([]string, error) {
+	for _, base := range []string{a.workspace, a.project} {
+		full := rel
+		if !filepath.IsAbs(rel) {
+			full = filepath.Join(base, filepath.FromSlash(rel))
+		}
+		if !safepath.WithinResolved(full, base) {
+			continue
+		}
+		if raw, err := readBoundedRegularFile(full, maxCandidateFileBytes); err == nil {
+			return anchor.Lines(raw), nil
+		}
+	}
+	return nil, fmt.Errorf("%s is not a file under the workspace or project", rel)
+}
+
+// mdName is the base name of the first .md file a breaks anchor names, or "".
+func mdName(name string) string {
+	for _, field := range strings.Fields(strings.ReplaceAll(name, "`", " ")) {
+		if field = strings.TrimRight(field, ",;:"); strings.HasSuffix(field, ".md") {
+			return filepath.Base(field)
+		}
+	}
+	return ""
+}
+
+// splitFindingCells splits a Finding: row on "|" outside backticked code, so a
+// quoted `a || b` stays one cell.
+func splitFindingCells(row string) []string {
+	var cells []string
+	var b strings.Builder
+	code := false
+	for _, r := range row {
+		switch {
+		case r == '`':
+			code = !code
+		case r == '|' && !code:
+			cells = append(cells, b.String())
+			b.Reset()
+			continue
+		}
+		b.WriteRune(r)
+	}
+	return append(cells, b.String())
+}

package/engine/internal/lib/apply_bundle.go

@@ -361,7 +361,8 @@ func applyHunks(base string, hunks []candidateHunk) (string, []string) {
 // checkBundleResult rejects an outcome the root would otherwise discover only
 // at Vet: a tracked ID that vanished from every touched file without being
 // listed in retired_ids, a new tasks.md graph problem, or a budgeted artifact
-// that grew into material overshoot without a `Budget override:` line.
+// that grew into material overshoot without a covering
+// `Budget override: <=N lines; <reason>` line.
 func checkBundleResult(targets []*bundleTarget, retired map[string]bool) []string {
 	var problems []string
 	beforeIDs, afterIDs := map[string]bool{}, map[string]bool{}

package/engine/internal/lib/candidate.go

@@ -69,29 +69,38 @@ func loadCandidateIdentity(root, slug string) (candidateIdentity, error) {
 		return candidateIdentity{}, fmt.Errorf("candidate manifest %s: %w; refresh touched-files.md", manifestPath, err)
 	}
 	project := projectDir(root)
+	if err := validateCandidateRows(project, rows); err != nil {
+		return candidateIdentity{}, err
+	}
+	digest, err := hashCandidate(project, rows)
+	if err != nil {
+		return candidateIdentity{}, err
+	}
+	return candidateIdentity{digest: digest, rows: rows}, nil
+}
+
+// validateCandidateRows checks every row against the filesystem and the
+// per-file, aggregate, and distinct-object bounds before anything is hashed.
+func validateCandidateRows(project string, rows []candidateRow) error {
 	var total int64
 	for i := range rows {
 		if err := validateCandidateRow(project, &rows[i]); err != nil {
-			return candidateIdentity{}, fmt.Errorf("candidate %q: %w", rows[i].path, err)
+			return fmt.Errorf("candidate %q: %w", rows[i].path, err)
 		}
 		if rows[i].state == "present" {
 			// ponytail: the 4096-row cap bounds portable pairwise identity checks; index native file IDs if that cap grows.
 			for prior := range rows[:i] {
 				if rows[prior].state == "present" && os.SameFile(rows[prior].info, rows[i].info) {
-					return candidateIdentity{}, fmt.Errorf("candidate %q: same filesystem object as candidate %q", rows[i].path, rows[prior].path)
+					return fmt.Errorf("candidate %q: same filesystem object as candidate %q", rows[i].path, rows[prior].path)
 				}
 			}
 			if rows[i].size > maxCandidateTotalBytes-total {
-				return candidateIdentity{}, errors.New("candidate present files exceed 256 MiB aggregate limit")
+				return errors.New("candidate present files exceed 256 MiB aggregate limit")
 			}
 			total += rows[i].size
 		}
 	}
-	digest, err := hashCandidate(project, rows)
-	if err != nil {
-		return candidateIdentity{}, err
-	}
-	return candidateIdentity{digest: digest, rows: rows}, nil
+	return nil
 }
 
 func readBoundedRegularFile(name string, limit int64) ([]byte, error) {

package/engine/internal/lib/claims.go

@@ -272,45 +272,52 @@ func claimAdd(root string, args []string, stdout, stderr io.Writer) int {
 			raw = append(raw, args[i])
 		}
 	}
+	_, code := addClaim(root, session, reason, ttl, raw, stdout, stderr)
+	return code
+}
+
+// addClaim records one claim and returns its id. It refuses, writing nothing,
+// while a live foreign session holds an overlapping path.
+func addClaim(root, session, reason string, ttl int, raw []string, stdout, stderr io.Writer) (string, int) {
 	if !validSession(session) {
 		fmt.Fprintln(stderr, "claim: --session is required (1-128 chars: letters, digits, - _ . : /)")
-		return 2
+		return "", 2
 	}
 	paths, err := normalizeClaimPaths(raw)
 	if err != nil {
 		fmt.Fprintf(stderr, "claim: %v\n", err)
-		return 2
+		return "", 2
 	}
 	path := claimsPath(root)
 	// Hold the ledger lock across read, conflict check, and append so two
 	// sessions cannot both pass the check and claim the same path.
-	code := 0
+	id, code := "", 0
 	if err := state.WithLock(path+".lock", func() error {
-		code = claimAddLocked(path, session, reason, ttl, paths, stdout, stderr)
+		id, code = claimAddLocked(path, session, reason, ttl, paths, stdout, stderr)
 		return nil
 	}); err != nil {
 		fmt.Fprintf(stderr, "claim: %v\n", err)
-		return 2
+		return "", 2
 	}
-	return code
+	return id, code
 }
 
-func claimAddLocked(path, session, reason string, ttl int, paths []string, stdout, stderr io.Writer) int {
+func claimAddLocked(path, session, reason string, ttl int, paths []string, stdout, stderr io.Writer) (string, int) {
 	latest, order, bad, err := readClaims(path)
 	if err != nil {
 		fmt.Fprintf(stderr, "claim: %v\n", err)
-		return 2
+		return "", 2
 	}
 	if bad > 0 {
 		fmt.Fprintf(stderr, unparsedLedgerMsg, bad)
-		return 2
+		return "", 2
 	}
 	now := time.Now().UTC()
 	probe := newHolderProbe()
 	conflicts := claimConflicts(probe.withoutGone(liveClaims(latest, order, now)), session, paths)
 	if len(conflicts) > 0 {
 		printConflicts(stderr, conflicts)
-		return 3
+		return "", 3
 	}
 	rec := &claimRecord{
 		ID:        newClaimID(),
@@ -325,10 +332,10 @@ func claimAddLocked(path, session, reason string, ttl int, paths []string, stdou
 	}
 	if err := appendClaim(path, rec); err != nil {
 		fmt.Fprintf(stderr, "claim: %v\n", err)
-		return 2
+		return "", 2
 	}
 	fmt.Fprintf(stdout, "claim: %s claimed %d path(s) until %s\n", rec.ID, len(paths), rec.ExpiresAt)
-	return 0
+	return rec.ID, 0
 }
 
 func claimRelease(root string, args []string, stdout, stderr io.Writer) int {
@@ -350,33 +357,38 @@ func claimRelease(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stderr, "claim: release requires --session and --id")
 		return 2
 	}
-	path := claimsPath(root)
-	latest, _, _, err := readClaims(path)
+	n, err := releaseClaim(root, session, id)
 	if err != nil {
 		fmt.Fprintf(stderr, "claim: %v\n", err)
 		return 2
 	}
+	fmt.Fprintf(stdout, "claim: %s released %d path(s)\n", id, n)
+	return 0
+}
+
+// releaseClaim marks session's claim id released and returns its path count.
+func releaseClaim(root, session, id string) (int, error) {
+	path := claimsPath(root)
+	latest, _, _, err := readClaims(path)
+	if err != nil {
+		return 0, err
+	}
 	rec, ok := latest[id]
 	if !ok {
-		fmt.Fprintf(stderr, "claim: unknown claim %q\n", id)
-		return 2
+		return 0, fmt.Errorf("unknown claim %q", id)
 	}
 	if rec.Session != session {
-		fmt.Fprintf(stderr, "claim: %q belongs to session %q, not %q\n", id, rec.Session, session)
-		return 2
+		return 0, fmt.Errorf("%q belongs to session %q, not %q", id, rec.Session, session)
 	}
 	if rec.Released {
-		fmt.Fprintf(stderr, "claim: %q already released\n", id)
-		return 2
+		return 0, fmt.Errorf("%q already released", id)
 	}
 	released := *rec
 	released.Released = true
 	if err := appendClaim(path, &released); err != nil {
-		fmt.Fprintf(stderr, "claim: %v\n", err)
-		return 2
+		return 0, err
 	}
-	fmt.Fprintf(stdout, "claim: %s released %d path(s)\n", id, len(rec.Paths))
-	return 0
+	return len(rec.Paths), nil
 }
 
 func claimList(root string, args []string, stdout, stderr io.Writer) int {
@@ -401,18 +413,18 @@ func claimList(root string, args []string, stdout, stderr io.Writer) int {
 	}
 	now := time.Now().UTC()
 	probe := newHolderProbe()
-	rows := liveClaims(latest, order, now)
-	if all {
-		rows = rows[:0]
-		for _, id := range order {
-			rows = append(rows, latest[id])
-		}
-	}
-	printed := 0
-	for _, rec := range rows {
+	// Bare list keeps every unreleased claim (expired and dead rows decide
+	// who may take a path) and folds the released history into one count.
+	printed, released := 0, 0
+	for _, id := range order {
+		rec := latest[id]
 		if rec == nil || (session != "" && rec.Session != session) {
 			continue
 		}
+		if rec.Released && !all {
+			released++
+			continue
+		}
 		state := "live"
 		if rec.Released {
 			state = "released"
@@ -431,6 +443,9 @@ func claimList(root string, args []string, stdout, stderr io.Writer) int {
 	if printed == 0 {
 		fmt.Fprintln(stdout, "claim: no claims")
 	}
+	if released > 0 {
+		fmt.Fprintf(stdout, "claim: %d released (use --all)\n", released)
+	}
 	if bad > 0 {
 		fmt.Fprintf(stdout, "claim: %d unparsed ledger line(s)\n", bad)
 	}