devrites 3.0.7 → 3.2.0

package/engine/internal/lib/recoveryattempts.go

@@ -0,0 +1,298 @@
+package lib
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/fsutil"
+)
+
+const (
+	recoveryAttemptsFile = "recovery-attempts.jsonl"
+	recoveryAttemptLimit = 3
+	recoveryRouteSchema  = "recovery-route/v1"
+)
+
+type recoveryClass string
+type recoveryOwner string
+type recoveryAction string
+
+const (
+	recoveryIntentGap            recoveryClass = "intent_gap"
+	recoverySpecGap              recoveryClass = "spec_gap"
+	recoveryPlanGap              recoveryClass = "plan_gap"
+	recoveryImplementationDefect recoveryClass = "implementation_defect"
+	recoveryProofToolDefect      recoveryClass = "proof_tool_defect"
+	recoveryEnvironmentDefect    recoveryClass = "environment_defect"
+	recoveryPreexisting          recoveryClass = "preexisting"
+	recoveryNotADefect           recoveryClass = "not_a_defect"
+)
+
+type recoveryRoute struct {
+	Schema     string         `json:"schema"`
+	Class      recoveryClass  `json:"class"`
+	Owner      recoveryOwner  `json:"owner"`
+	Action     recoveryAction `json:"action"`
+	HumanPause bool           `json:"humanPause"`
+}
+
+var recoveryRoutes = [...]recoveryRoute{
+	{recoveryRouteSchema, recoveryIntentGap, "human_clarify", "clarify_intent", true},
+	{recoveryRouteSchema, recoverySpecGap, "clarify", "clarify_missing_decision", true},
+	{recoveryRouteSchema, recoveryPlanGap, "plan", "rite_plan_repair", false},
+	{recoveryRouteSchema, recoveryImplementationDefect, "wright", "repair_implementation_and_rerun_proof", false},
+	{recoveryRouteSchema, recoveryProofToolDefect, "debug_recovery", "repair_proof_tool_and_rerun_original_proof", false},
+	{recoveryRouteSchema, recoveryEnvironmentDefect, "debug_recovery", "normalize_environment_and_run_discriminator", false},
+	{recoveryRouteSchema, recoveryPreexisting, "baseline", "record_baseline_and_fix_if_acceptance_blocked", false},
+	{recoveryRouteSchema, recoveryNotADefect, "caller", "record_authority_and_continue", false},
+}
+
+type recoveryAttempt struct {
+	Fingerprint string        `json:"fingerprint"`
+	RootCause   string        `json:"rootCause"`
+	Class       recoveryClass `json:"class,omitempty"`
+	Attempt     int           `json:"attempt"`
+	Status      string        `json:"status"`
+	Failure     string        `json:"failure,omitempty"`
+	At          string        `json:"at"`
+}
+
+var recoveryWhitespace = regexp.MustCompile(`\s+`)
+
+// RecoveryAttempts durably accounts bounded technical recovery across agents
+// and sessions.
+//
+//	recovery route <class>
+//	recovery record [--class <class>] "<root cause>" "<failure>" [slug]
+//	recovery check "<root cause>" [slug]
+//	recovery clear [--class <class>] "<root cause>" [slug]
+//	recovery fingerprint "<root cause>"
+func RecoveryAttempts(root string, args []string, stdout, stderr io.Writer) int {
+	sub := strings.ToLower(strings.TrimSpace(argAt(args, 0)))
+	if sub == "route" {
+		return writeRecoveryRoute(args[1:], stdout, stderr)
+	}
+
+	commandArgs := args[1:]
+	var class recoveryClass
+	if sub == "record" || sub == "clear" {
+		var err error
+		class, commandArgs, err = parseRecoveryClass(commandArgs)
+		if err != nil {
+			fmt.Fprintf(stderr, "recovery: %v\n", err)
+			return 2
+		}
+	}
+	rootCause := strings.TrimSpace(argAt(commandArgs, 0))
+	if sub == "fingerprint" {
+		if rootCause == "" || len(commandArgs) != 1 {
+			fmt.Fprintln(stderr, `usage: devrites-engine recovery fingerprint "<root cause>"`)
+			return 2
+		}
+		fmt.Fprintln(stdout, recoveryFingerprint(rootCause))
+		return 0
+	}
+	if sub != "record" && sub != "check" && sub != "clear" {
+		fmt.Fprintln(stderr, `usage: devrites-engine recovery <route|record|check|clear|fingerprint> ...`)
+		return 2
+	}
+	if rootCause == "" {
+		fmt.Fprintln(stderr, "recovery: root cause is required")
+		return 2
+	}
+
+	var failure string
+	var slugArgs []string
+	if sub == "record" {
+		failure = strings.TrimSpace(argAt(commandArgs, 1))
+		if failure == "" {
+			fmt.Fprintln(stderr, "recovery: record requires a concise failure")
+			return 2
+		}
+		slugArgs = commandArgs[2:]
+	} else {
+		slugArgs = commandArgs[1:]
+	}
+	if len(slugArgs) > 1 {
+		fmt.Fprintln(stderr, "recovery: at most one slug is allowed")
+		return 2
+	}
+	slug := slugOrActive(root, slugArgs)
+	if slug == "" {
+		fmt.Fprintln(stderr, "recovery: no active workspace")
+		return 2
+	}
+	path := featureFile(root, slug, recoveryAttemptsFile)
+	entries, err := readRecoveryAttempts(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "recovery: %v\n", err)
+		return 2
+	}
+	fingerprint := recoveryFingerprint(rootCause)
+	attempts := activeRecoveryAttempts(entries, fingerprint)
+
+	switch sub {
+	case "check":
+		if attempts >= recoveryAttemptLimit {
+			fmt.Fprintf(stderr, "recovery: exhausted %d/%d for %s\n", attempts, recoveryAttemptLimit, fingerprint)
+			return 3
+		}
+		fmt.Fprintf(stdout, "recovery: available %d/%d used for %s\n", attempts, recoveryAttemptLimit, fingerprint)
+		return 0
+	case "record":
+		if attempts >= recoveryAttemptLimit {
+			fmt.Fprintf(stderr, "recovery: exhausted %d/%d for %s; no new attempt recorded\n", attempts, recoveryAttemptLimit, fingerprint)
+			return 3
+		}
+		attempts++
+		entries = append(entries, recoveryAttempt{
+			Fingerprint: fingerprint,
+			RootCause:   normalizeRecoveryCause(rootCause),
+			Class:       class,
+			Attempt:     attempts,
+			Status:      "failed",
+			Failure:     failure,
+			At:          nowUTC(),
+		})
+		if err := writeRecoveryAttempts(path, entries); err != nil {
+			fmt.Fprintf(stderr, "recovery: persist attempt: %v\n", err)
+			return 1
+		}
+		if attempts >= recoveryAttemptLimit {
+			fmt.Fprintf(stderr, "recovery: recorded attempt %d/%d; automatic recovery exhausted for %s\n", attempts, recoveryAttemptLimit, fingerprint)
+			return 3
+		}
+		fmt.Fprintf(stdout, "recovery: recorded attempt %d/%d for %s\n", attempts, recoveryAttemptLimit, fingerprint)
+		return 0
+	case "clear":
+		entries = append(entries, recoveryAttempt{
+			Fingerprint: fingerprint,
+			RootCause:   normalizeRecoveryCause(rootCause),
+			Class:       class,
+			Status:      "cleared",
+			At:          nowUTC(),
+		})
+		if err := writeRecoveryAttempts(path, entries); err != nil {
+			fmt.Fprintf(stderr, "recovery: clear attempts: %v\n", err)
+			return 1
+		}
+		fmt.Fprintf(stdout, "recovery: cleared attempts for %s\n", fingerprint)
+		return 0
+	}
+	return 2
+}
+
+func writeRecoveryRoute(args []string, stdout, stderr io.Writer) int {
+	if len(args) != 1 {
+		fmt.Fprintln(stderr, "usage: devrites-engine recovery route <class>")
+		return 2
+	}
+	route, ok := recoveryRouteFor(recoveryClass(strings.TrimSpace(args[0])))
+	if !ok {
+		fmt.Fprintf(stderr, "recovery: unknown class %q\n", args[0])
+		return 2
+	}
+	if err := json.NewEncoder(stdout).Encode(route); err != nil {
+		fmt.Fprintf(stderr, "recovery: encode route: %v\n", err)
+		return 1
+	}
+	return 0
+}
+
+func recoveryRouteFor(class recoveryClass) (recoveryRoute, bool) {
+	for _, route := range recoveryRoutes {
+		if route.Class == class {
+			return route, true
+		}
+	}
+	return recoveryRoute{}, false
+}
+
+func parseRecoveryClass(args []string) (recoveryClass, []string, error) {
+	if argAt(args, 0) != "--class" {
+		return "", args, nil
+	}
+	if len(args) < 2 {
+		return "", nil, fmt.Errorf("--class requires a value")
+	}
+	class := recoveryClass(strings.TrimSpace(args[1]))
+	if _, ok := recoveryRouteFor(class); !ok {
+		return "", nil, fmt.Errorf("unknown class %q", args[1])
+	}
+	return class, args[2:], nil
+}
+
+func recoveryFingerprint(rootCause string) string {
+	sum := sha256.Sum256([]byte(normalizeRecoveryCause(rootCause)))
+	return hex.EncodeToString(sum[:])
+}
+
+func normalizeRecoveryCause(rootCause string) string {
+	return strings.ToLower(recoveryWhitespace.ReplaceAllString(strings.TrimSpace(rootCause), " "))
+}
+
+func readRecoveryAttempts(path string) ([]recoveryAttempt, error) {
+	raw, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("read %s: %w", recoveryAttemptsFile, err)
+	}
+	var entries []recoveryAttempt
+	for index, line := range strings.Split(strings.TrimSpace(string(raw)), "\n") {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		var entry recoveryAttempt
+		if err := json.Unmarshal([]byte(line), &entry); err != nil {
+			return nil, fmt.Errorf("%s line %d is invalid: %w", recoveryAttemptsFile, index+1, err)
+		}
+		if entry.Fingerprint == "" || entry.Status == "" {
+			return nil, fmt.Errorf("%s line %d is incomplete", recoveryAttemptsFile, index+1)
+		}
+		if entry.Class != "" {
+			if _, ok := recoveryRouteFor(entry.Class); !ok {
+				return nil, fmt.Errorf("%s line %d has unknown class %q", recoveryAttemptsFile, index+1, entry.Class)
+			}
+		}
+		entries = append(entries, entry)
+	}
+	return entries, nil
+}
+
+func activeRecoveryAttempts(entries []recoveryAttempt, fingerprint string) int {
+	attempts := 0
+	for _, entry := range entries {
+		if entry.Fingerprint != fingerprint {
+			continue
+		}
+		if entry.Status == "cleared" {
+			attempts = 0
+			continue
+		}
+		if entry.Status == "failed" && entry.Attempt > attempts {
+			attempts = entry.Attempt
+		}
+	}
+	return attempts
+}
+
+func writeRecoveryAttempts(path string, entries []recoveryAttempt) error {
+	var out strings.Builder
+	for _, entry := range entries {
+		data, err := json.Marshal(entry)
+		if err != nil {
+			return err
+		}
+		out.Write(data)
+		out.WriteByte('\n')
+	}
+	return fsutil.WriteFileAtomic(path, []byte(out.String()), 0o600)
+}

package/engine/internal/lib/recoveryattempts_test.go

@@ -0,0 +1,215 @@
+package lib
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRecoveryAttemptsPersistLimitAcrossCalls(t *testing.T) {
+	root := t.TempDir()
+	slug := "recovery"
+	writeReadinessFile(t, root, slug, "state.md", "- Phase: build\n")
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte(slug+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cause := "CSS extractor mishandles same-line imports"
+
+	for attempt := 1; attempt <= recoveryAttemptLimit; attempt++ {
+		var stdout, stderr bytes.Buffer
+		code := RecoveryAttempts(root, []string{"record", cause, "scanner exit 3"}, &stdout, &stderr)
+		if attempt < recoveryAttemptLimit && code != 0 {
+			t.Fatalf("attempt %d code=%d stderr=%q", attempt, code, stderr.String())
+		}
+		if attempt == recoveryAttemptLimit && code != 3 {
+			t.Fatalf("third attempt code=%d stdout=%q stderr=%q, want exhausted", code, stdout.String(), stderr.String())
+		}
+	}
+
+	// A fresh invocation reads the durable ledger and cannot receive three more
+	// attempts merely because chat/agent context changed.
+	var stderr bytes.Buffer
+	if code := RecoveryAttempts(root, []string{"check", cause}, &bytes.Buffer{}, &stderr); code != 3 {
+		t.Fatalf("restart check code=%d stderr=%q, want exhausted", code, stderr.String())
+	}
+	if code := RecoveryAttempts(root, []string{"record", cause, "fourth failure"}, &bytes.Buffer{}, &stderr); code != 3 {
+		t.Fatalf("fourth record code=%d, want refused", code)
+	}
+
+	if code := RecoveryAttempts(root, []string{"clear", cause}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("clear code=%d", code)
+	}
+	if code := RecoveryAttempts(root, []string{"check", cause}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("check after green clear code=%d", code)
+	}
+}
+
+func TestRecoveryAttemptsKeyByNormalizedRootCause(t *testing.T) {
+	root := t.TempDir()
+	slug := "recovery"
+	writeReadinessFile(t, root, slug, "state.md", "- Phase: build\n")
+	if got, want := recoveryFingerprint(" CSS   GAP "), recoveryFingerprint("css gap"); got != want {
+		t.Fatalf("normalized fingerprints differ: %s != %s", got, want)
+	}
+	if recoveryFingerprint("css gap") == recoveryFingerprint("browser timeout") {
+		t.Fatal("different root causes share a fingerprint")
+	}
+
+	if code := RecoveryAttempts(root, []string{"record", "css gap", "exit 3", slug}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("record code=%d", code)
+	}
+	var stdout bytes.Buffer
+	if code := RecoveryAttempts(root, []string{"check", "browser timeout", slug}, &stdout, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("different cause check code=%d", code)
+	}
+	if !strings.Contains(stdout.String(), "0/3") {
+		t.Fatalf("different cause inherited attempts: %q", stdout.String())
+	}
+}
+
+func TestRecoveryAttemptsFailsClosedOnCorruptLedger(t *testing.T) {
+	root := t.TempDir()
+	slug := "recovery"
+	writeReadinessFile(t, root, slug, "state.md", "- Phase: build\n")
+	writeReadinessFile(t, root, slug, recoveryAttemptsFile, "{not-json}\n")
+	var stderr bytes.Buffer
+	if code := RecoveryAttempts(root, []string{"check", "css gap", slug}, &bytes.Buffer{}, &stderr); code != 2 {
+		t.Fatalf("code=%d stderr=%q, want fail closed", code, stderr.String())
+	}
+}
+
+func TestRecoveryRoutesCoverEveryClass(t *testing.T) {
+	tests := []struct {
+		scenario   string
+		class      recoveryClass
+		owner      recoveryOwner
+		action     recoveryAction
+		humanPause bool
+	}{
+		{"desired behavior is undecided", recoveryIntentGap, "human_clarify", "clarify_intent", true},
+		{"acceptance omits an error outcome", recoverySpecGap, "clarify", "clarify_missing_decision", true},
+		{"proof plan omits required provenance", recoveryPlanGap, "plan", "rite_plan_repair", false},
+		{"stable product assertion is red", recoveryImplementationDefect, "wright", "repair_implementation_and_rerun_proof", false},
+		{"declared CSS import defeats the scanner", recoveryProofToolDefect, "debug_recovery", "repair_proof_tool_and_rerun_original_proof", false},
+		{"browser runner exhausts resources", recoveryEnvironmentDefect, "debug_recovery", "normalize_environment_and_run_discriminator", false},
+		{"unrelated baseline lint already fails", recoveryPreexisting, "baseline", "record_baseline_and_fix_if_acceptance_blocked", false},
+		{"observed behavior matches accepted authority", recoveryNotADefect, "caller", "record_authority_and_continue", false},
+	}
+
+	if len(recoveryRoutes) != len(tests) {
+		t.Fatalf("route count=%d, want %d", len(recoveryRoutes), len(tests))
+	}
+	for _, test := range tests {
+		t.Run(test.scenario, func(t *testing.T) {
+			route, ok := recoveryRouteFor(test.class)
+			if !ok {
+				t.Fatalf("missing route for %q", test.class)
+			}
+			if route.Schema != recoveryRouteSchema || route.Owner != test.owner ||
+				route.Action != test.action || route.HumanPause != test.humanPause {
+				t.Fatalf("route=%+v", route)
+			}
+		})
+	}
+}
+
+func TestRecoveryRouteOutputIsStableJSON(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	if code := RecoveryAttempts("", []string{"route", "proof_tool_defect"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	const want = `{"schema":"recovery-route/v1","class":"proof_tool_defect","owner":"debug_recovery","action":"repair_proof_tool_and_rerun_original_proof","humanPause":false}` + "\n"
+	if stdout.String() != want {
+		t.Fatalf("stdout=%q, want %q", stdout.String(), want)
+	}
+}
+
+func TestRecoveryReplayDEC031RoutesWithoutAuthorization(t *testing.T) {
+	proofRoute, ok := recoveryRouteFor(recoveryProofToolDefect)
+	if !ok || proofRoute.HumanPause || proofRoute.Action != "repair_proof_tool_and_rerun_original_proof" {
+		t.Fatalf("DEC-031 proof route=%+v, found=%v", proofRoute, ok)
+	}
+	planRoute, ok := recoveryRouteFor(recoveryPlanGap)
+	if !ok || planRoute.HumanPause || planRoute.Action != "rite_plan_repair" {
+		t.Fatalf("DEC-031 provenance route=%+v, found=%v", planRoute, ok)
+	}
+}
+
+func TestRecoveryReplayDEC032SeparatesScannerAndEnvironment(t *testing.T) {
+	scannerCause := "CSS extractor mishandles same-line imports"
+	environmentCause := "browser target timeout ERR_INSUFFICIENT_RESOURCES"
+	if recoveryFingerprint(scannerCause) == recoveryFingerprint(environmentCause) {
+		t.Fatal("DEC-032 causal fingerprints must not share an attempt budget")
+	}
+	for _, class := range []recoveryClass{recoveryProofToolDefect, recoveryEnvironmentDefect} {
+		route, ok := recoveryRouteFor(class)
+		if !ok || route.HumanPause || route.Owner != "debug_recovery" {
+			t.Fatalf("DEC-032 route for %s=%+v, found=%v", class, route, ok)
+		}
+	}
+}
+
+func TestRecoveryAttemptsPersistsClassAndReadsLegacyJSONL(t *testing.T) {
+	root := t.TempDir()
+	slug := "recovery"
+	cause := "declared CSS import exits 3"
+	writeReadinessFile(t, root, slug, "state.md", "- Phase: build\n")
+	legacy := recoveryAttempt{
+		Fingerprint: recoveryFingerprint(cause),
+		RootCause:   normalizeRecoveryCause(cause),
+		Attempt:     1,
+		Status:      "failed",
+		Failure:     "legacy scanner failure",
+		At:          "2026-07-23T00:00:00Z",
+	}
+	legacyJSON, err := json.Marshal(legacy)
+	if err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(root, "work", slug, recoveryAttemptsFile)
+	writeReadinessFile(t, root, slug, recoveryAttemptsFile, string(legacyJSON)+"\n")
+
+	var stdout, stderr bytes.Buffer
+	args := []string{"record", "--class", "proof_tool_defect", cause, "scanner still exits 3", slug}
+	if code := RecoveryAttempts(root, args, &stdout, &stderr); code != 0 {
+		t.Fatalf("record code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	entries, err := readRecoveryAttempts(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 2 || entries[0].Class != "" || entries[1].Class != recoveryProofToolDefect {
+		t.Fatalf("entries=%+v", entries)
+	}
+	if entries[1].Attempt != 2 {
+		t.Fatalf("typed attempt=%d, want legacy budget continuation at 2", entries[1].Attempt)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	clearArgs := []string{"clear", "--class", "proof_tool_defect", cause, slug}
+	if code := RecoveryAttempts(root, clearArgs, &stdout, &stderr); code != 0 {
+		t.Fatalf("clear code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	entries, err = readRecoveryAttempts(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 3 || entries[2].Class != recoveryProofToolDefect || entries[2].Status != "cleared" {
+		t.Fatalf("typed clear=%+v", entries)
+	}
+}
+
+func TestRecoveryAttemptsRejectsUnknownClass(t *testing.T) {
+	var stderr bytes.Buffer
+	args := []string{"record", "--class", "retry_authorization", "cause", "failure", "slug"}
+	if code := RecoveryAttempts(t.TempDir(), args, &bytes.Buffer{}, &stderr); code != 2 {
+		t.Fatalf("code=%d stderr=%q, want usage failure", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "unknown class") {
+		t.Fatalf("stderr=%q", stderr.String())
+	}
+}

package/engine/internal/lib/resolve.go

@@ -15,8 +15,8 @@ import (
 )
 
 // Resolve answers or drops an open question and keeps questions.md and state.md
-// consistent: it rewrites the question's block and, when state.md is awaiting that
-// question, clears the "Awaiting human" block and flips Status back to running.
+// consistent by updating the question block. When state.md is waiting for that
+// question, it clears the "Awaiting human" block and restores the running status.
 // The workspace is <root>/features/<slug>.
 //
 //	0  resolved         2  no active workspace      3  qid not found
@@ -67,6 +67,17 @@ func Resolve(root string, args []string, stdout, stderr io.Writer) int {
 		}
 	}
 
+	code := 0
+	if err := state.WithFeatureLock(root, slug, func() error {
+		code = resolveMutation(mode, qid, payload, qfile, sfile, stdout, stderr)
+		return nil
+	}); err != nil {
+		return fail(stderr, err.Error(), 1)
+	}
+	return code
+}
+
+func resolveMutation(mode, qid, payload, qfile, sfile string, stdout, stderr io.Writer) int {
 	switch mode {
 	case "answer":
 		if code := resolveQuestion(qfile, qid, "answered", payload, stderr); code != 0 {
@@ -148,12 +159,9 @@ func splitColon(s string) (before, after string) {
 	return before, after
 }
 
-// clockNow is the single wall-clock read for the resolve command. When
-// DEVRITES_NOW is set to an RFC-3339 timestamp or a bare YYYY-MM-DD date it pins
-// the clock, so date-derived output (the next question id) is deterministic
-// under test and stable across the day boundaries that otherwise rot golden
-// snapshots. One overridable seam instead of scattered time.Now() reads. See
-// ADR-0006.
+// clockNow is the resolve command's single wall-clock read. DEVRITES_NOW accepts
+// an RFC-3339 timestamp or YYYY-MM-DD date so tests can keep date-derived
+// question IDs stable. See ADR-0006.
 func clockNow() time.Time {
 	if s := os.Getenv("DEVRITES_NOW"); s != "" {
 		for _, layout := range []string{time.RFC3339, "2006-01-02"} {
@@ -174,21 +182,13 @@ func resolveNextQID(qpath string, stdout, stderr io.Writer) int {
 	if qpath == "" {
 		return fail(stderr, "Usage: devrites-engine resolve next-qid <questions.md path>", 5)
 	}
-	today := clockNow().Format("2006-01-02")
-	used := 0
 	var content []byte
 	if isFile(qpath) {
 		content, _ = os.ReadFile(qpath)
-		countRe := regexp.MustCompile(`(?m)^## q-` + regexp.QuoteMeta(today) + `-`)
-		used = len(countRe.FindAllIndex(content, -1))
 	}
-	next := used + 1
-	qid := fmt.Sprintf("q-%s-%03d", today, next)
-	if content != nil {
-		collideRe := regexp.MustCompile(`(?m)^## ` + regexp.QuoteMeta(qid) + `([[:space:]]|$)`)
-		if collideRe.Match(content) {
-			return fail(stderr, "qid already present: "+qid+" (questions.md edited out of sequence)", 6)
-		}
+	qid, err := nextQuestionID(content, clockNow())
+	if err != nil {
+		return fail(stderr, "qid already present: "+qid+" (questions.md edited out of sequence)", 6)
 	}
 	fmt.Fprintln(stdout, qid)
 	return 0
@@ -202,6 +202,10 @@ func resolveQuestion(qfile, qid, status, answer string, stderr io.Writer) int {
 	if err != nil {
 		return fail(stderr, "questions.md missing at "+qfile, 2)
 	}
+	answer, err = normalizeGitAuthorityResolution(data, qid, status, answer)
+	if err != nil {
+		return fail(stderr, err.Error(), 5)
+	}
 	ts := nowUTC()
 	target := regexp.MustCompile(`^## ` + regexp.QuoteMeta(qid) + `([[:space:]]|$)`)
 

package/engine/internal/lib/runbook_context_test.go

@@ -60,6 +60,26 @@ func TestContextSyncRejectsUnsafePath(t *testing.T) {
 	}
 }
 
+func TestContextSyncRefusesExternalWorkspaceOverride(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	target := filepath.Join(project, "AGENTS.md")
+	if err := os.WriteFile(target, []byte("unchanged\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(t.TempDir(), "feature"))
+	stderr := &bytes.Buffer{}
+	if code := Context(root, []string{"sync", "AGENTS.md"}, &bytes.Buffer{}, stderr); code != 3 {
+		t.Fatalf("external workspace context sync = %d, want refusal\n%s", code, stderr)
+	}
+	if got := testutil.ReadFile(t, target); got != "unchanged\n" {
+		t.Fatalf("refused context sync mutated target:\n%s", got)
+	}
+}
+
 func TestRunbookValidateAndGateResume(t *testing.T) {
 	project := t.TempDir()
 	root := filepath.Join(project, ".devrites")