devrites 3.2.27 → 4.0.0

package/engine/internal/lib/util_test.go

@@ -0,0 +1,44 @@
+package lib
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestRunGitCommandIgnoresInheritedRepositoryTargets(t *testing.T) {
+	target := initGitRepository(t, filepath.Join(t.TempDir(), "target repo"))
+	poison := initGitRepository(t, filepath.Join(t.TempDir(), "poison repo"))
+	want, err := filepath.EvalSymlinks(target)
+	if err != nil {
+		t.Fatal(err)
+	}
+	environ := append(os.Environ(),
+		"GIT_DIR="+filepath.Join(poison, ".git"),
+		"GIT_WORK_TREE="+poison,
+		"GIT_AUTHOR_NAME=Retained Author",
+	)
+
+	out, err := runGitCommand(target, environ, "rev-parse", "--show-toplevel")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := filepath.FromSlash(strings.TrimSpace(string(out))); got != want {
+		t.Fatalf("git top level = %q, want %q", got, want)
+	}
+}
+
+func initGitRepository(t *testing.T, path string) string {
+	t.Helper()
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command("git", "init", "-q", path)
+	cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git init: %v\n%s", err, out)
+	}
+	return path
+}

package/engine/internal/markdowntext/markdowntext.go

@@ -0,0 +1,108 @@
+package markdowntext
+
+import (
+	"bytes"
+	"errors"
+	"unicode/utf8"
+)
+
+// Structural returns Markdown with fenced blocks replaced by spaces. Byte
+// offsets and line breaks stay aligned with the original input.
+func Structural(input []byte) ([]byte, error) {
+	if !utf8.Valid(input) {
+		return nil, errors.New("markdown text contains malformed UTF-8")
+	}
+	if bytes.IndexByte(input, 0) >= 0 {
+		return nil, errors.New("markdown text contains NUL byte")
+	}
+
+	out := append([]byte(nil), input...)
+	var marker byte
+	fenceWidth := 0
+	for start := 0; start < len(input); {
+		lineEnd := bytes.IndexByte(input[start:], '\n')
+		if lineEnd < 0 {
+			lineEnd = len(input)
+		} else {
+			lineEnd += start
+		}
+		contentEnd := lineEnd
+		if contentEnd > start && input[contentEnd-1] == '\r' {
+			contentEnd--
+		}
+		line := input[start:contentEnd]
+
+		if marker == 0 {
+			if nextMarker, width, ok := openingFence(line); ok {
+				marker, fenceWidth = nextMarker, width
+				mask(out[start:lineEnd])
+			}
+		} else {
+			mask(out[start:lineEnd])
+			if closingFence(line, marker, fenceWidth) {
+				marker, fenceWidth = 0, 0
+			}
+		}
+
+		if lineEnd == len(input) {
+			break
+		}
+		start = lineEnd + 1
+	}
+	return out, nil
+}
+
+func openingFence(line []byte) (byte, int, bool) {
+	start, ok := fenceStart(line)
+	if !ok {
+		return 0, 0, false
+	}
+	marker := line[start]
+	end := start
+	for end < len(line) && line[end] == marker {
+		end++
+	}
+	if end-start < 3 {
+		return 0, 0, false
+	}
+	if marker == '`' && bytes.IndexByte(line[end:], '`') >= 0 {
+		return 0, 0, false
+	}
+	return marker, end - start, true
+}
+
+func closingFence(line []byte, marker byte, width int) bool {
+	start, ok := fenceStart(line)
+	if !ok || line[start] != marker {
+		return false
+	}
+	end := start
+	for end < len(line) && line[end] == marker {
+		end++
+	}
+	if end-start < width {
+		return false
+	}
+	for _, b := range line[end:] {
+		if b != ' ' && b != '\t' {
+			return false
+		}
+	}
+	return true
+}
+
+func fenceStart(line []byte) (int, bool) {
+	start := 0
+	for start < len(line) && line[start] == ' ' {
+		start++
+	}
+	return start, start <= 3 && start < len(line) && (line[start] == '`' || line[start] == '~')
+}
+
+func mask(data []byte) {
+	for i, b := range data {
+		if b != '\r' && b != '\n' {
+			data[i] = ' '
+		}
+	}
+}

package/engine/internal/markdowntext/markdowntext_test.go

@@ -0,0 +1,58 @@
+package markdowntext
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"testing"
+)
+
+func TestStructuralMasksFencedBlocksWithoutMovingBytes(t *testing.T) {
+	corpus, err := os.ReadFile("testdata/structural.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cases []struct {
+		Name   string `json:"name"`
+		Input  string `json:"input"`
+		Output string `json:"output"`
+	}
+	if err := json.Unmarshal(corpus, &cases); err != nil {
+		t.Fatal(err)
+	}
+	if len(cases) == 0 {
+		t.Fatal("structural Markdown corpus is empty")
+	}
+
+	for _, test := range cases {
+		t.Run(test.Name, func(t *testing.T) {
+			input := []byte(test.Input)
+			got, err := Structural(input)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if want := []byte(test.Output); !bytes.Equal(got, want) {
+				t.Fatalf("Structural() = %q, want %q", got, want)
+			}
+			if len(got) != len(input) {
+				t.Fatalf("len(Structural()) = %d, want %d", len(got), len(input))
+			}
+			for i, b := range input {
+				if (b == '\n' || b == '\r') && got[i] != b {
+					t.Fatalf("line break at byte %d changed from %q to %q", i, b, got[i])
+				}
+			}
+		})
+	}
+}
+
+func TestStructuralRejectsCorruptText(t *testing.T) {
+	for _, input := range [][]byte{
+		{'o', 'k', 0},
+		{'o', 'k', 0xff},
+	} {
+		if _, err := Structural(input); err == nil {
+			t.Fatalf("Structural(%q) error = nil", input)
+		}
+	}
+}

package/engine/internal/markdowntext/testdata/structural.json

@@ -0,0 +1,27 @@
+[
+  {
+    "name": "indentation boundary",
+    "input": "    ```\nnot fenced\n",
+    "output": "    ```\nnot fenced\n"
+  },
+  {
+    "name": "CRLF marker width and mismatched close",
+    "input": "before\r\n   ````go\r\n## hidden\r\n~~~\r\n```\r\n   ````\r\nafter\r\n",
+    "output": "before\r\n         \r\n         \r\n   \r\n   \r\n       \r\nafter\r\n"
+  },
+  {
+    "name": "backtick info restriction",
+    "input": "```go`bad\nnot fenced\n",
+    "output": "```go`bad\nnot fenced\n"
+  },
+  {
+    "name": "tilde fence through EOF",
+    "input": "~~~\n| hidden |\n",
+    "output": "   \n          \n"
+  },
+  {
+    "name": "Unicode byte length",
+    "input": "π before\n~~~md\n## hïdden π\n~~~\nπ after\n",
+    "output": "π before\n     \n             \n   \nπ after\n"
+  }
+]

package/engine/internal/reason/reason.go

@@ -10,140 +10,19 @@ import (
 type ID string
 
 const (
-	RootSelected ID = "DRV-ROOT-SELECTED"
-
 	GateReadinessPassed  ID = "DRV-GATE-READINESS-PASSED" // #nosec G101 -- stable decision ID, not a credential
 	GateReadinessMissing ID = "DRV-GATE-READINESS-MISSING"
+	GateReadinessStale   ID = "DRV-GATE-READINESS-STALE"
 	GateSealPassed       ID = "DRV-GATE-SEAL-PASSED" // #nosec G101 -- stable decision ID, not a credential
 	GateSealMissing      ID = "DRV-GATE-SEAL-MISSING"
-
-	HookDisabled                 ID = "DRV-HOOK-DISABLED"
-	HookAllowApproved            ID = "DRV-HOOK-ALLOW-APPROVED"
-	HookStopClear                ID = "DRV-HOOK-STOP-CLEAR"
-	HookStopInputInvalid         ID = "DRV-HOOK-STOP-INPUT-INVALID"
-	HookStopReentry              ID = "DRV-HOOK-STOP-REENTRY"
-	HookStopWorkspaceUnavailable ID = "DRV-HOOK-STOP-WORKSPACE-UNAVAILABLE" // #nosec G101 -- stable decision ID, not a credential
-	HookStopRed                  ID = "DRV-HOOK-STOP-RED"
-	HookStopUnsurfacedHumanGate  ID = "DRV-HOOK-STOP-UNSURFACED-HUMAN-GATE"
-	HookStopMissingProof         ID = "DRV-HOOK-STOP-MISSING-PROOF"
-	HookReviewerReadonlyDenied   ID = "DRV-HOOK-REVIEWER-READONLY-DENIED"
-	HookReviewerReadonlyObserved ID = "DRV-HOOK-REVIEWER-READONLY-OBSERVED"
-	HookA1Denied                 ID = "DRV-HOOK-A1-DENIED"
-	HookA1Observed               ID = "DRV-HOOK-A1-OBSERVED"
-	HookWrightScopeDenied        ID = "DRV-HOOK-WRIGHT-SCOPE-DENIED"
-	HookWrightScopeObserved      ID = "DRV-HOOK-WRIGHT-SCOPE-OBSERVED"
-	HookWrightForbiddenDenied    ID = "DRV-HOOK-WRIGHT-FORBIDDEN-DENIED"
-	HookForgeBindingDenied       ID = "DRV-HOOK-FORGE-BINDING-DENIED"
-	HookIngestWarning            ID = "DRV-HOOK-INGEST-WARNING"
-
-	GitAuthorityPending     ID = "DRV-GIT-AUTHORITY-PENDING"
-	GitAuthorityGranted     ID = "DRV-GIT-AUTHORITY-GRANTED"
-	GitAuthorityExpired     ID = "DRV-GIT-AUTHORITY-EXPIRED"
-	GitAuthorityRefused     ID = "DRV-GIT-AUTHORITY-REFUSED"
-	GitAuthorityReplayed    ID = "DRV-GIT-AUTHORITY-REPLAYED"
-	GitAuthorityCorrupt     ID = "DRV-GIT-AUTHORITY-CORRUPT"
-	GitAuthorityUnavailable ID = "DRV-GIT-AUTHORITY-UNAVAILABLE"
-	GitWorkspaceUnavailable ID = "DRV-GIT-WORKSPACE-UNAVAILABLE"
-
-	GitInputTooLarge          ID = "DRV-GIT-INPUT-TOO-LARGE"
-	GitAmbiguousSyntax        ID = "DRV-GIT-AMBIGUOUS-SYNTAX"
-	GitAmbiguousDynamic       ID = "DRV-GIT-AMBIGUOUS-DYNAMIC"
-	GitAmbiguousAlias         ID = "DRV-GIT-AMBIGUOUS-ALIAS"
-	GitAmbiguousGlobalOption  ID = "DRV-GIT-AMBIGUOUS-GLOBAL-OPTION"
-	GitAmbiguousStdin         ID = "DRV-GIT-AMBIGUOUS-STDIN"
-	GitDestructiveReset       ID = "DRV-GIT-DESTRUCTIVE-RESET"
-	GitDestructiveClean       ID = "DRV-GIT-DESTRUCTIVE-CLEAN"
-	GitDestructiveCheckout    ID = "DRV-GIT-DESTRUCTIVE-CHECKOUT"
-	GitDestructiveRestore     ID = "DRV-GIT-DESTRUCTIVE-RESTORE"
-	GitDestructiveSwitch      ID = "DRV-GIT-DESTRUCTIVE-SWITCH"
-	GitDestructiveRemove      ID = "DRV-GIT-DESTRUCTIVE-RM"
-	GitDestructiveBranch      ID = "DRV-GIT-DESTRUCTIVE-BRANCH"
-	GitDestructiveTag         ID = "DRV-GIT-DESTRUCTIVE-TAG"
-	GitDestructiveUpdateRef   ID = "DRV-GIT-DESTRUCTIVE-UPDATE-REF"
-	GitDestructiveStash       ID = "DRV-GIT-DESTRUCTIVE-STASH"
-	GitDestructiveReflog      ID = "DRV-GIT-DESTRUCTIVE-REFLOG"
-	GitDestructivePrune       ID = "DRV-GIT-DESTRUCTIVE-PRUNE"
-	GitDestructiveHistory     ID = "DRV-GIT-DESTRUCTIVE-HISTORY"
-	GitDestructivePushForce   ID = "DRV-GIT-DESTRUCTIVE-PUSH-FORCE"
-	GitDestructivePushDelete  ID = "DRV-GIT-DESTRUCTIVE-PUSH-DELETE"
-	GitDestructiveWorktree    ID = "DRV-GIT-DESTRUCTIVE-WORKTREE"
-	GitDestructiveRefDeletion ID = "DRV-GIT-DESTRUCTIVE-REF-DELETE"
-
-	AgentNamed                  ID = "DRV-AGENT-NAMED"
-	AgentGenericFallback        ID = "DRV-AGENT-GENERIC-FALLBACK"
-	AgentInlineFallback         ID = "DRV-AGENT-INLINE-FALLBACK"
-	AgentUnavailable            ID = "DRV-AGENT-UNAVAILABLE"
-	AgentResultAccepted         ID = "DRV-AGENT-RESULT-ACCEPTED"
-	AgentResultMalformed        ID = "DRV-AGENT-RESULT-MALFORMED"
-	AgentResultStale            ID = "DRV-AGENT-RESULT-STALE"
-	AgentResultIdentityMismatch ID = "DRV-AGENT-RESULT-IDENTITY-MISMATCH"
-	AgentResultOutOfScope       ID = "DRV-AGENT-RESULT-OUT-OF-SCOPE"
 )
 
 var catalog = []ID{
-	RootSelected,
 	GateReadinessPassed,
 	GateReadinessMissing,
+	GateReadinessStale,
 	GateSealPassed,
 	GateSealMissing,
-	HookDisabled,
-	HookAllowApproved,
-	HookStopClear,
-	HookStopInputInvalid,
-	HookStopReentry,
-	HookStopWorkspaceUnavailable,
-	HookStopRed,
-	HookStopUnsurfacedHumanGate,
-	HookStopMissingProof,
-	HookReviewerReadonlyDenied,
-	HookReviewerReadonlyObserved,
-	HookA1Denied,
-	HookA1Observed,
-	HookWrightScopeDenied,
-	HookWrightScopeObserved,
-	HookWrightForbiddenDenied,
-	HookForgeBindingDenied,
-	HookIngestWarning,
-	GitAuthorityPending,
-	GitAuthorityGranted,
-	GitAuthorityExpired,
-	GitAuthorityRefused,
-	GitAuthorityReplayed,
-	GitAuthorityCorrupt,
-	GitAuthorityUnavailable,
-	GitWorkspaceUnavailable,
-	GitInputTooLarge,
-	GitAmbiguousSyntax,
-	GitAmbiguousDynamic,
-	GitAmbiguousAlias,
-	GitAmbiguousGlobalOption,
-	GitAmbiguousStdin,
-	GitDestructiveReset,
-	GitDestructiveClean,
-	GitDestructiveCheckout,
-	GitDestructiveRestore,
-	GitDestructiveSwitch,
-	GitDestructiveRemove,
-	GitDestructiveBranch,
-	GitDestructiveTag,
-	GitDestructiveUpdateRef,
-	GitDestructiveStash,
-	GitDestructiveReflog,
-	GitDestructivePrune,
-	GitDestructiveHistory,
-	GitDestructivePushForce,
-	GitDestructivePushDelete,
-	GitDestructiveWorktree,
-	GitDestructiveRefDeletion,
-	AgentNamed,
-	AgentGenericFallback,
-	AgentInlineFallback,
-	AgentUnavailable,
-	AgentResultAccepted,
-	AgentResultMalformed,
-	AgentResultStale,
-	AgentResultIdentityMismatch,
-	AgentResultOutOfScope,
 }
 
 var known = func() map[ID]struct{} {

package/engine/internal/reason/reason_test.go

@@ -24,8 +24,10 @@ func TestCatalogIsKnownUniqueAndStableShaped(t *testing.T) {
 }
 
 func TestParseRejectsUnregisteredAndFreeText(t *testing.T) {
-	if got, err := Parse(string(GateSealMissing)); err != nil || got != GateSealMissing {
-		t.Fatalf("Parse registered = %q, %v", got, err)
+	for _, want := range []ID{GateReadinessStale, GateSealMissing} {
+		if got, err := Parse(string(want)); err != nil || got != want {
+			t.Fatalf("Parse registered = %q, %v", got, err)
+		}
 	}
 	for _, raw := range []string{"", "DRV-UNKNOWN", "/absolute/repo", "operator-private-value"} {
 		if _, err := Parse(raw); err == nil {

package/engine/internal/rootfacts/facts.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/gitenv"
 	"github.com/devrites/devrites/internal/safepath"
 )
 
@@ -255,16 +256,13 @@ func inspectWorkspaceState(facts *Facts) {
 	if root == "" {
 		return
 	}
-	for _, layout := range []string{"work", "features"} {
-		entries, err := os.ReadDir(filepath.Join(root, layout))
-		if err != nil {
-			continue
-		}
+	entries, err := os.ReadDir(filepath.Join(root, "work"))
+	if err == nil {
 		for _, entry := range entries {
 			if entry.Type()&os.ModeSymlink == 0 {
 				continue
 			}
-			path := filepath.Join(root, layout, entry.Name())
+			path := filepath.Join(root, "work", entry.Name())
 			if safepath.WithinResolved(path, root) {
 				continue
 			}
@@ -320,7 +318,7 @@ func inspectWorkspaceState(facts *Facts) {
 		})
 		return
 	}
-	if !isDir(filepath.Join(root, "work", slug)) && !isDir(filepath.Join(root, "features", slug)) {
+	if !isDir(filepath.Join(root, "work", slug)) {
 		facts.Hazards = append(facts.Hazards, Hazard{
 			ID:          "DRV-ACTIVE-STALE",
 			Severity:    "warning",
@@ -352,7 +350,7 @@ func gitPath(dir, flag string) (string, bool) {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
 	cmd := exec.CommandContext(ctx, "git", "-C", dir, "rev-parse", "--path-format=absolute", flag)
-	cmd.Env = append(os.Environ(), "GIT_OPTIONAL_LOCKS=0", "GIT_TERMINAL_PROMPT=0")
+	cmd.Env = append(gitenv.Sanitize(os.Environ()), "GIT_OPTIONAL_LOCKS=0", "GIT_TERMINAL_PROMPT=0")
 	out, err := cmd.Output()
 	if err != nil || ctx.Err() != nil {
 		return "", false

package/engine/internal/rootfacts/facts_test.go

@@ -101,6 +101,26 @@ func TestResolveKeepsRepositoryBoundaryWhenGitProbeIsUnavailable(t *testing.T) {
 	}
 }
 
+func TestGitPathIgnoresInheritedRepositoryTargets(t *testing.T) {
+	target := initRepository(t, filepath.Join(t.TempDir(), "target repo"))
+	poison := initRepository(t, filepath.Join(t.TempDir(), "poison repo"))
+	t.Setenv("GIT_DIR", filepath.Join(poison, ".git"))
+	t.Setenv("GIT_WORK_TREE", poison)
+	t.Setenv("GIT_CONFIG_COUNT", "1")
+	t.Setenv("GIT_CONFIG_KEY_0", "core.worktree")
+	t.Setenv("GIT_CONFIG_VALUE_0", poison)
+	t.Setenv("GIT_AUTHOR_NAME", "Retained Author")
+	want, err := physical(target)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	got, ok := gitPath(target, "--show-toplevel")
+	if !ok || got != want {
+		t.Fatalf("gitPath() = %q, %v, want %q, true", got, ok, want)
+	}
+}
+
 func TestResolveLinkedWorktreeUsesPerWorktreeRootAndCommonDir(t *testing.T) {
 	base := t.TempDir()
 	main := initRepository(t, filepath.Join(base, "main"))

package/engine/internal/state/cmd/workflowmanifest/main.go

@@ -18,19 +18,17 @@ func main() {
 	flag.Parse()
 
 	document := struct {
-		GeneratedBy         string                     `json:"generatedBy"`
-		SchemaVersion       int                        `json:"schemaVersion"`
-		AuthorityPolicy     state.AuthorityPolicy      `json:"authorityPolicy"`
-		Phases              []state.WorkflowPhase      `json:"phases"`
-		ClarifyReturnFields []state.ClarifyFieldPolicy `json:"clarifyReturnFields"`
-		CursorKeyAliases    []state.CursorKeyAlias     `json:"cursorKeyAliases"`
+		GeneratedBy      string                 `json:"generatedBy"`
+		SchemaVersion    int                    `json:"schemaVersion"`
+		AuthorityPolicy  state.AuthorityPolicy  `json:"authorityPolicy"`
+		Phases           []state.WorkflowPhase  `json:"phases"`
+		CursorKeyAliases []state.CursorKeyAlias `json:"cursorKeyAliases"`
 	}{
-		GeneratedBy:         "go generate ./internal/state; DO NOT EDIT",
-		SchemaVersion:       state.SchemaVersion,
-		AuthorityPolicy:     state.WorkflowAuthorityPolicy(),
-		Phases:              state.WorkflowPhases(),
-		ClarifyReturnFields: state.ClarifyFieldPolicies(),
-		CursorKeyAliases:    state.CursorKeyAliases(),
+		GeneratedBy:      "go generate ./internal/state; DO NOT EDIT",
+		SchemaVersion:    state.SchemaVersion,
+		AuthorityPolicy:  state.WorkflowAuthorityPolicy(),
+		Phases:           state.WorkflowPhases(),
+		CursorKeyAliases: state.CursorKeyAliases(),
 	}
 	data, err := json.MarshalIndent(document, "", "  ")
 	if err != nil {

package/engine/internal/state/cursor.go

@@ -4,6 +4,8 @@ import (
 	"sort"
 	"strings"
 	"unicode"
+
+	"github.com/devrites/devrites/internal/markdowntext"
 )
 
 // Canonical cursor keys. Callers use these constants so schema spelling changes
@@ -56,8 +58,12 @@ const (
 // CursorField reads a state.md field from either the canonical | key | value |
 // cursor table or the legacy "- Key: value" form.
 func CursorField(lines []string, key string) (string, bool) {
+	structural, ok := structuralCursorLines(lines)
+	if !ok {
+		return "", false
+	}
 	want := normalizeCursorKey(key)
-	for _, line := range lines {
+	for _, line := range structural {
 		gotKey, value, _, ok := parseCursorLine(line)
 		if ok && normalizeCursorKey(gotKey) == want {
 			return value, true
@@ -69,20 +75,29 @@ func CursorField(lines []string, key string) (string, bool) {
 // SetCursorField replaces an existing state.md field without changing whether
 // the file uses the canonical table or legacy bullet form.
 func SetCursorField(lines []string, key, value string) ([]string, bool) {
+	structural, ok := structuralCursorLines(lines)
+	if !ok {
+		return append([]string(nil), lines...), false
+	}
+	return setCursorField(lines, structural, key, value)
+}
+
+func setCursorField(lines, structural []string, key, value string) ([]string, bool) {
 	want := normalizeCursorKey(key)
 	out := append([]string(nil), lines...)
-	for i, line := range out {
+	for i, line := range structural {
 		gotKey, _, kind, ok := parseCursorLine(line)
 		if !ok || normalizeCursorKey(gotKey) != want {
 			continue
 		}
+		original := out[i]
 		switch kind {
 		case cursorLineTable:
-			indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))]
+			indent := original[:len(original)-len(strings.TrimLeft(original, " \t"))]
 			out[i] = indent + "| " + strings.TrimSpace(gotKey) + " | " + value + " |"
 		case cursorLineLegacy:
-			colon := strings.IndexByte(line, ':')
-			out[i] = line[:colon+1] + " " + value
+			colon := strings.IndexByte(original, ':')
+			out[i] = original[:colon+1] + " " + value
 		}
 		return out, true
 	}
@@ -92,13 +107,17 @@ func SetCursorField(lines []string, key, value string) ([]string, bool) {
 // UpsertCursorField replaces key when present or inserts it into the canonical
 // cursor table (falling back to a legacy bullet when no table exists).
 func UpsertCursorField(lines []string, key, value string) []string {
-	if out, ok := SetCursorField(lines, key, value); ok {
+	structural, ok := structuralCursorLines(lines)
+	if !ok {
+		return append([]string(nil), lines...)
+	}
+	if out, ok := setCursorField(lines, structural, key, value); ok {
 		return out
 	}
 	out := append([]string(nil), lines...)
 	lastTable := -1
 	inCursor := false
-	for i, line := range out {
+	for i, line := range structural {
 		trimmed := strings.TrimSpace(line)
 		if strings.HasPrefix(trimmed, "## ") {
 			if inCursor {
@@ -133,18 +152,34 @@ func UpsertCursorField(lines []string, key, value string) []string {
 // DeleteCursorField removes every presentation of key from canonical or legacy
 // state without disturbing unrelated prose.
 func DeleteCursorField(lines []string, key string) []string {
+	structural, ok := structuralCursorLines(lines)
+	if !ok {
+		return append([]string(nil), lines...)
+	}
 	want := normalizeCursorKey(key)
 	out := make([]string, 0, len(lines))
-	for _, line := range lines {
+	for i, line := range structural {
 		gotKey, _, _, ok := parseCursorLine(line)
 		if ok && normalizeCursorKey(gotKey) == want {
 			continue
 		}
-		out = append(out, line)
+		out = append(out, lines[i])
 	}
 	return out
 }
 
+func structuralCursorLines(lines []string) ([]string, bool) {
+	if len(lines) == 0 {
+		return nil, true
+	}
+	structural, err := markdowntext.Structural([]byte(strings.Join(lines, "\n")))
+	if err != nil {
+		return nil, false
+	}
+	masked := strings.Split(string(structural), "\n")
+	return masked, len(masked) == len(lines)
+}
+
 func parseCursorLine(line string) (key, value string, kind cursorLineKind, ok bool) {
 	trimmed := strings.TrimSpace(line)
 	if len(trimmed) >= 2 && trimmed[0] == '|' && trimmed[len(trimmed)-1] == '|' {
@@ -163,15 +198,19 @@ func parseCursorLine(line string) (key, value string, kind cursorLineKind, ok bo
 }
 
 func normalizeCursorKey(key string) string {
+	normalized := rawCursorKey(key)
+	if canonical, ok := cursorKeyAliases[normalized]; ok {
+		return normalizeCursorKey(canonical)
+	}
+	return normalized
+}
+
+func rawCursorKey(key string) string {
 	var b strings.Builder
 	for _, r := range strings.ToLower(key) {
 		if unicode.IsLetter(r) || unicode.IsDigit(r) {
 			b.WriteRune(r)
 		}
 	}
-	normalized := b.String()
-	if canonical, ok := cursorKeyAliases[normalized]; ok {
-		return normalizeCursorKey(canonical)
-	}
-	return normalized
+	return b.String()
 }