devrites 6.0.4 → 6.1.0

package/engine/internal/install/preflight.go

@@ -8,6 +8,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"slices"
 	"sort"
 	"strings"
 
@@ -41,6 +42,13 @@ func (r *runner) preflightInstall() error {
 		if err != nil {
 			return err
 		}
+		if !snapshot.missing && r.isPinnedAlias(rel) {
+			// scripts/pin.sh aliases are not in the payload; carry them
+			// forward (hashed) so prune keeps them and uninstall removes them.
+			r.addManifest(rel)
+			r.addInstallRecord(rel, snapshot.hash)
+			continue
+		}
 		if !snapshot.missing {
 			if kind := managedConflict(record, snapshot); kind != "" && !r.opts.Force {
 				conflicts = append(conflicts, fmt.Sprintf("%s: %s", kind, rel))
@@ -50,6 +58,9 @@ func (r *runner) preflightInstall() error {
 			if _, err := r.rememberPath(merge.TargetRel); err != nil {
 				return err
 			}
+			if err := dryRunStripMarker(map[string][]byte{}, r.target, merge); err != nil {
+				return err
+			}
 		}
 	}
 	for _, rel := range r.installMergeTargets() {
@@ -60,7 +71,42 @@ func (r *runner) preflightInstall() error {
 	if _, err := r.rememberPath(ManifestName); err != nil {
 		return err
 	}
-	return managedConflictError(conflicts)
+	if err := managedConflictError(conflicts); err != nil {
+		return err
+	}
+	return r.preflightMerges()
+}
+
+// preflightMerges computes every config merge against the current files, so
+// a merge the installer would reject fails before anything is written.
+func (r *runner) preflightMerges() error {
+	if !r.opts.WithSkills {
+		return nil
+	}
+	for _, m := range []struct {
+		enabled bool
+		merge   hostpack.MarkerMerge
+	}{
+		{r.opts.WithCodex, hostpack.CodexAgentsMerge},
+		{r.opts.WithPi, hostpack.PiAgentsMerge},
+		{r.opts.WithDevin, hostpack.DevinAgentsMerge},
+	} {
+		if !m.enabled {
+			continue
+		}
+		if _, _, err := r.markerMergeNext(m.merge); err != nil {
+			return fmt.Errorf("merge %s: %w", m.merge.TargetRel, err)
+		}
+	}
+	if r.opts.WithCodex {
+		if _, err := r.codexConfigNext(); err != nil {
+			return fmt.Errorf("merge %s: %w", hostpack.CodexConfigMerge.TargetRel, err)
+		}
+	}
+	if _, _, err := r.claudeSettingsNext(); err != nil {
+		return fmt.Errorf("seed claude settings: %w", err)
+	}
+	return nil
 }
 
 func (r *runner) preflightUninstall(entries []string) error {
@@ -91,6 +137,27 @@ func (r *runner) preflightUninstall(entries []string) error {
 	return managedConflictError(conflicts)
 }
 
+// isPinnedAlias reports whether a dropped manifest entry is a scripts/pin.sh
+// alias wrapper: <skills>/<name>/SKILL.md for a name that is not a built-in
+// alias, delegating with the alias description.
+func (r *runner) isPinnedAlias(rel string) bool {
+	var name string
+	for _, prefix := range []string{hostpack.ClaudeSkillsTarget, hostpack.CodexSkillsTarget} {
+		if rest, ok := strings.CutPrefix(rel, prefix+"/"); ok {
+			name, ok = strings.CutSuffix(rest, "/SKILL.md")
+			if !ok || strings.Contains(name, "/") {
+				return false
+			}
+		}
+	}
+	if name == "" || slices.ContainsFunc(hostpack.Aliases, func(a hostpack.Alias) bool { return a.Name == name }) {
+		return false
+	}
+	// #nosec G304 -- manifest entry under the operator target, path-checked by rememberPath
+	data, err := os.ReadFile(filepath.Join(r.target, filepath.FromSlash(rel)))
+	return err == nil && strings.Contains(string(data), "\ndescription: Alias of DevRites /")
+}
+
 func (r *runner) desiredInstallPaths() (map[string]bool, error) {
 	out := map[string]bool{".devrites/README.md": true}
 	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi, r.opts.WithDevin) {
@@ -132,6 +199,9 @@ func (r *runner) desiredInstallPaths() (map[string]bool, error) {
 	if r.opts.WithSkills {
 		out[hostpack.ClaudeSettingsMerge.MarkerRel] = true
 	}
+	for _, config := range r.hostConfigs() {
+		out[config.Rel] = true
+	}
 	return out, nil
 }
 

package/engine/internal/install/uninstall.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 
 	"github.com/devrites/devrites/internal/hostpack"
@@ -25,6 +26,11 @@ func (r *runner) uninstall() error {
 		fmt.Fprintln(r.opts.Stdout, "  (dry run - no changes)")
 	}
 	fmt.Fprintln(r.opts.Stdout)
+	kept, err := r.relinquishEditedHostConfigs()
+	if err != nil {
+		return err
+	}
+	entries = slices.DeleteFunc(entries, func(rel string) bool { return kept[rel] })
 	if err := r.preflightUninstall(entries); err != nil {
 		return err
 	}
@@ -57,7 +63,7 @@ func (r *runner) uninstall() error {
 			continue
 		}
 		if merge.TargetRel == hostpack.ClaudeSettingsMerge.TargetRel {
-			if err := r.stripClaudeSettings(filepath.Join(r.target, filepath.FromSlash(merge.TargetRel)), true); err != nil {
+			if err := r.stripClaudeSettings(filepath.Join(r.target, filepath.FromSlash(merge.TargetRel))); err != nil {
 				return fmt.Errorf("strip DevRites settings from %s: %w", merge.TargetRel, err)
 			}
 			continue

package/engine/internal/install/update.go

@@ -77,6 +77,9 @@ func runUpdate(opts Options) error {
 			return fmt.Errorf("parse manifest install flags: %w", err)
 		}
 	}
+	if err := parseArgs(opts.args, &next); err != nil {
+		return fmt.Errorf("parse update flags: %w", err)
+	}
 	next.Target = target
 	next.PayloadDir = payload
 	next.SourceDir = source
@@ -147,12 +150,13 @@ func runRemoteUpdate(opts Options, target, installed string) error {
 	if _, err := verifyEngineBinary(candidate.EnginePath, tag, 30*time.Second); err != nil {
 		return fmt.Errorf("verify update engine: %w", err)
 	}
-	args := []string{
-		"update",
+	// Explicit flags first so the fixed handoff arguments below win.
+	args := append([]string{"update"}, opts.args...)
+	args = append(args,
 		"--target", target,
 		"--source-dir", candidate.SourceDir,
 		"--payload-dir", candidate.PayloadDir,
-	}
+	)
 	if opts.DryRun {
 		args = append(args, "--dry-run")
 	}

package/engine/internal/lib/claims.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"slices"
 	"sort"
 	"strconv"
 	"strings"
@@ -159,14 +160,17 @@ func normalizeClaimPaths(raw []string) ([]string, error) {
 		if err != nil {
 			return nil, err
 		}
-		if norm == ".devrites" || strings.HasPrefix(norm, ".devrites/") ||
-			norm == ".git" || strings.HasPrefix(norm, ".git/") {
+		// Fold case: on a case-insensitive filesystem .DEVRITES is the control
+		// tree and A.go and a.go are one file.
+		folded := strings.ToLower(norm)
+		if folded == ".devrites" || strings.HasPrefix(folded, ".devrites/") ||
+			folded == ".git" || strings.HasPrefix(folded, ".git/") {
 			return nil, fmt.Errorf("path must not claim control-tree or git internals: %q", norm)
 		}
-		if _, dup := seen[norm]; dup {
+		if _, dup := seen[folded]; dup {
 			return nil, fmt.Errorf("duplicate path %q", norm)
 		}
-		seen[norm] = struct{}{}
+		seen[folded] = struct{}{}
 		out = append(out, norm)
 	}
 	sort.Strings(out)
@@ -186,27 +190,31 @@ func validSession(s string) bool {
 	return true
 }
 
-// claimConflicts returns live claims by other sessions covering any path.
+// claimConflicts returns live claims by other sessions overlapping any path: a
+// claimed directory covers every path beneath it, and vice versa.
 func claimConflicts(live []*claimRecord, session string, paths []string) []*claimRecord {
-	want := map[string]struct{}{}
-	for _, p := range paths {
-		want[p] = struct{}{}
-	}
 	var out []*claimRecord
 	for _, rec := range live {
 		if rec.Session == session {
 			continue
 		}
-		for _, p := range rec.Paths {
-			if _, hit := want[p]; hit {
-				out = append(out, rec)
-				break
-			}
+		if slices.ContainsFunc(rec.Paths, func(held string) bool {
+			return slices.ContainsFunc(paths, func(p string) bool { return claimPathsOverlap(held, p) })
+		}) {
+			out = append(out, rec)
 		}
 	}
 	return out
 }
 
+// claimPathsOverlap folds case always: on a case-sensitive filesystem a false
+// overlap only serializes two writers, while a missed one on macOS/Windows
+// lets both edit the same file.
+func claimPathsOverlap(a, b string) bool {
+	a, b = strings.ToLower(a), strings.ToLower(b)
+	return a == b || strings.HasPrefix(a, b+"/") || strings.HasPrefix(b, a+"/")
+}
+
 // An unreadable line may be a live claim, so the conflict gates refuse to
 // answer rather than report a path free.
 const unparsedLedgerMsg = "claim: %d unparsed ledger line(s); cannot rule out a conflict, repair the claims ledger\n"
@@ -250,6 +258,10 @@ func claimAdd(root string, args []string, stdout, stderr io.Writer) int {
 			ttl = min(max(n, claimMinTTL), claimMaxTTL)
 			i++
 		default:
+			if strings.HasPrefix(args[i], "-") {
+				fmt.Fprintf(stderr, "claim: unknown flag %q\n", args[i])
+				return 2
+			}
 			raw = append(raw, args[i])
 		}
 	}
@@ -420,6 +432,10 @@ func claimCheck(root string, args []string, stdout, stderr io.Writer) int {
 			session = argAt(args, i+1)
 			i++
 		default:
+			if strings.HasPrefix(args[i], "-") {
+				fmt.Fprintf(stderr, "claim: unknown flag %q\n", args[i])
+				return 2
+			}
 			raw = append(raw, args[i])
 		}
 	}

package/engine/internal/lib/cli_observe.go

@@ -37,6 +37,12 @@ func RunTaskGraphCheck(root, slug string, stdout, stderr io.Writer) int {
 			recordMetric(root, slug, "define", "size-advisory", "", int64(over))
 		}
 	}
+	if edges := edgeAdvisories(graph); len(edges) > 0 {
+		for _, line := range edges {
+			fmt.Fprintf(stdout, "task-graph: %s\n", line)
+		}
+		recordMetric(root, slug, "define", "edge-advisory", "", int64(len(edges)))
+	}
 	return 0
 }
 

package/engine/internal/lib/context.go

@@ -157,8 +157,17 @@ func RunContext(root string, args []string, stdout, stderr io.Writer) int {
 	// reference text.
 	if opts.role != "" {
 		rel := roleAgentPath(manifest, opts.role)
-		if writeContextEntry(&bundle, filepath.Join(skillsRoot, "..", "agents", filepath.FromSlash(rel)),
-			"agents/"+rel, seen, true) {
+		abs, label := filepath.Join(skillsRoot, "..", "agents", filepath.FromSlash(rel)), "agents/"+rel
+		// A Codex install has skills in .agents/skills but role agents at
+		// <project>/.codex/agents/<name>.toml, with no Markdown sibling.
+		if _, err := os.Stat(abs); err != nil {
+			codex := strings.TrimSuffix(filepath.Base(filepath.FromSlash(rel)), ".md") + ".toml"
+			candidate := filepath.Join(filepath.Dir(root), ".codex", "agents", codex)
+			if info, err := os.Stat(candidate); err == nil && info.Mode().IsRegular() {
+				abs, label = candidate, ".codex/agents/"+codex
+			}
+		}
+		if writeContextEntry(&bundle, abs, label, seen, true) {
 			loaded++
 		} else {
 			// The agent contract is a pack file, not a workspace artifact: a
@@ -543,15 +552,23 @@ func parseContextArgs(args []string, stderr io.Writer) (contextOpts, int) {
 // canonical pack (this repo), a project-level install, then the user-global
 // install.
 func resolveSkillsRoot(root, explicit string) (string, error) {
+	// root is the .devrites directory; its parent is the project root that
+	// holds pack/ and host skill installs.
+	project := filepath.Dir(root)
 	if explicit != "" {
-		if info, err := os.Stat(explicit); err == nil && info.IsDir() {
-			return explicit, nil
+		candidates := []string{explicit}
+		// Host guidance passes a project-relative root (.omp/skills); keep it
+		// working when the engine runs from a subdirectory.
+		if !filepath.IsAbs(explicit) {
+			candidates = append(candidates, filepath.Join(project, explicit))
+		}
+		for _, candidate := range candidates {
+			if info, err := os.Stat(candidate); err == nil && info.IsDir() {
+				return candidate, nil
+			}
 		}
 		return "", fmt.Errorf("skills root %q is not a directory", explicit)
 	}
-	// root is the .devrites directory; its parent is the project root that
-	// holds pack/ and host skill installs.
-	project := filepath.Dir(root)
 	candidates := []string{
 		filepath.Join(project, "pack", ".claude", "skills"),
 		filepath.Join(root, "pack", ".claude", "skills"),

package/engine/internal/lib/diffscope.go

@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
 )
 
 const diffScopeUsage = `usage: devrites-engine check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--cwd <dir>]
@@ -15,6 +17,9 @@ Verifies the changed-path set stays inside the declared allowlist. Modes:
   --staged    git diff --name-only --cached
   --base ref  git diff --name-only <ref> (tracked only)
 Allowlist entries match exactly or as directory prefixes ("dir" covers "dir/...").
+A rename counts as both its old and new path. Engine-written .devrites machine
+files (claims ledger, dispatch/metrics/baseline/lease/lock files, ctx/ bundles)
+are ignored; every other .devrites path is reported.
 Exit 0 clean, 3 a path escaped the allowlist or the diff is empty without --allow-empty.`
 
 // RunCheckDiffScope is the mechanical post-return contract gate: a writer's
@@ -97,6 +102,10 @@ func parseDiffScopeArgs(root string, args []string, stderr io.Writer) (diffScope
 		case "--base":
 			opts.mode = "base"
 			opts.base = argAt(args, i+1)
+			if strings.HasPrefix(opts.base, "-") {
+				fmt.Fprintln(stderr, "diff-scope: --base requires a ref (not a flag)")
+				return opts, 2
+			}
 			i++
 		case "--allow-empty":
 			opts.allowEmpty = true
@@ -142,14 +151,81 @@ func (o diffScopeOpts) changedPaths() ([]string, error) {
 	if dir == "" {
 		dir = o.root
 	}
+	var paths []string
+	var err error
 	switch o.mode {
 	case "staged":
-		return gitDiffNames(dir, "--cached")
+		paths, err = gitDiffNames(dir, "--cached")
 	case "base":
-		return gitDiffNames(dir, o.base)
+		paths, err = gitDiffNames(dir, o.base)
 	default:
-		return gitStatusPaths(dir)
+		paths, err = gitStatusPaths(dir)
+	}
+	if err != nil {
+		return nil, err
+	}
+	// The engine's own machine files are never task paths.
+	control := devritesRepoPrefix(dir, o.root)
+	kept := paths[:0]
+	for _, path := range paths {
+		if rel, ok := strings.CutPrefix(path, control+"/"); !ok || !engineMachineFile(rel) {
+			kept = append(kept, path)
+		}
+	}
+	return kept, nil
+}
+
+// engineMachineFiles are the feature-root files the engine itself writes:
+// the dispatch ledger, metrics ledger, drift and regression baselines, the
+// parallel lease, and the feature lock.
+var engineMachineFiles = map[string]bool{
+	"dispatch.json":        true,
+	MetricsFile:            true,
+	driftBaselineFile:      true,
+	regressionBaselineFile: true,
+	"parallel-lease.md":    true,
+	".lock":                true,
+}
+
+// engineMachineFile reports whether rel, relative to the .devrites tree, is
+// engine-written: the claims ledger and its lock, a feature's machine files,
+// or its ctx/ context bundles. Every other .devrites path stays reported.
+func engineMachineFile(rel string) bool {
+	if rel == ClaimsFile || rel == ClaimsFile+".lock" {
+		return true
+	}
+	rest, ok := strings.CutPrefix(rel, "work/")
+	if !ok {
+		return false
+	}
+	slug, name, ok := strings.Cut(rest, "/")
+	return ok && devritespaths.ValidSlug(slug) && (engineMachineFiles[name] || strings.HasPrefix(name, "ctx/"))
+}
+
+// devritesRepoPrefix returns the project's control tree as a path relative to
+// dir's repository root: normally ".devrites", or "sub/.devrites" when the
+// project lives in a subdirectory of the repository.
+func devritesRepoPrefix(dir, root string) string {
+	if filepath.Base(root) != ".devrites" {
+		return ".devrites"
+	}
+	top, err := runGitCommand(dir, nil, "rev-parse", "--show-toplevel")
+	if err != nil {
+		return ".devrites"
+	}
+	physicalTop, err := filepath.EvalSymlinks(strings.TrimSpace(string(top)))
+	if err != nil {
+		return ".devrites"
+	}
+	physicalRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		return ".devrites"
+	}
+	rel, err := filepath.Rel(physicalTop, physicalRoot)
+	if err != nil || !filepath.IsLocal(rel) {
+		return ".devrites"
 	}
+	return filepath.ToSlash(rel)
 }
 
 // gitStatusPaths lists every path the writer touched: tracked modifications,

package/engine/internal/lib/dispatch.go

@@ -26,8 +26,10 @@ import (
 const 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>]
 
 Wave barrier for parallel agent dispatch: seal fails until every declared
-role has a distinct handle; return fails before seal; status exits nonzero
-while a wave is open, sealed, or abandoned.
+role has a distinct handle; return fails before seal. status --wave exits
+nonzero until that wave is complete; bare status lists every wave and exits
+nonzero while any wave is open or sealed (abandoned waves are listed only).
+A complete wave cannot be abandoned.
 
 A build wave with a wright role must name its slice(s) with --slice; a vet
 wave may (slice-bound recheck). Every 5 rounds of one kind on one slice, the
@@ -55,6 +57,15 @@ type dispatchWave struct {
 	ResliceReviewed []string                 `json:"reslice_reviewed,omitempty"`
 }
 
+func waveStarted(w *dispatchWave) bool {
+	for _, r := range w.Roles {
+		if r != nil && r.StartedAt != "" {
+			return true
+		}
+	}
+	return false
+}
+
 type dispatchRole struct {
 	Handle     string `json:"handle,omitempty"`
 	StartedAt  string `json:"started,omitempty"`
@@ -294,7 +305,7 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 			for _, name := range sortedKeys(f.Waves) {
 				w := f.Waves[name]
 				fmt.Fprintf(stdout, "dispatch: wave %s state=%s roles=%d\n", name, w.State, len(w.Roles))
-				if w.State != "complete" {
+				if w.State == "open" || w.State == "sealed" {
 					incomplete = append(incomplete, name)
 				}
 			}
@@ -335,6 +346,9 @@ func dispatchLocked(root, slug, sub, phase, wave, role, handle, reason string, r
 		if w == nil {
 			return fail("no wave %q", wave)
 		}
+		if w.State == "complete" {
+			return fail("wave %q is complete; a complete wave cannot be abandoned", wave)
+		}
 		if strings.TrimSpace(reason) == "" {
 			return fail("--reason is required (non-empty, recorded in dispatch.json)")
 		}
@@ -363,7 +377,7 @@ func roundKind(w *dispatchWave) string {
 }
 
 func isBuildWrightWave(w *dispatchWave) bool {
-	if w.Phase != "build" {
+	if !strings.EqualFold(w.Phase, "build") {
 		return false
 	}
 	for r := range w.Roles {
@@ -403,16 +417,17 @@ func admitWrightRounds(root, slug string, f *dispatchFile, w *dispatchWave, revi
 		prior, reviews := 0, 0
 		var unreturned []string
 		for name, other := range f.Waves {
-			if other.State == "abandoned" || roundKind(other) != kind {
+			// An abandoned wave spends its round once any role started.
+			if (other.State == "abandoned" && !waveStarted(other)) || roundKind(other) != kind {
 				continue
 			}
-			if slices.Contains(other.Slices, id) {
+			if containsSlice(other.Slices, id) {
 				prior++
 				if other.State == "open" || other.State == "sealed" {
 					unreturned = append(unreturned, name)
 				}
 			}
-			if slices.Contains(other.ResliceReviewed, id) {
+			if containsSlice(other.ResliceReviewed, id) {
 				reviews++
 			}
 		}
@@ -460,6 +475,18 @@ func admitWrightRounds(root, slug string, f *dispatchFile, w *dispatchWave, revi
 	return lines, 0
 }
 
+// containsSlice reports whether ids names the same slice as id, ignoring
+// zero padding (SLICE-1 == SLICE-001) so a respelling cannot reset the cap.
+func containsSlice(ids []string, id string) bool {
+	return slices.ContainsFunc(ids, func(other string) bool {
+		return sliceNumber(other) == sliceNumber(id)
+	})
+}
+
+func sliceNumber(id string) string {
+	return strings.TrimLeft(strings.TrimPrefix(id, "SLICE-"), "0")
+}
+
 // driftHeading returns the drift.md level-2 heading line for id, or "".
 func driftHeading(drift, id string) string {
 	re := regexp.MustCompile(`(?m)^## ` + regexp.QuoteMeta(id) + `\b.*$`)

package/engine/internal/lib/drift.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/gate"
+	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/state"
 )
 
@@ -104,7 +105,7 @@ func recordDriftBaseline(root, slug, baselinePath string, digests []gate.Readine
 		return 2
 	}
 	fmt.Fprintf(stdout, "check drift: baseline recorded (%d inputs, %s)\n", len(digests), binding)
-	recordMetric(root, slug, "", "drift-baseline", "", 0)
+	recordMetric(root, slug, cursorPhase(root, slug), "drift-baseline", "", 0)
 	return 0
 }
 
@@ -147,8 +148,14 @@ func compareDriftFallback(workspace, binding string, stdout io.Writer) int {
 		fmt.Fprintf(stdout, "check drift: unproven — no %s baseline and no readable eng-review.md; run `check drift <slug> --record` after Vet writes the binding\n", driftBaselineFile)
 		return 0
 	}
+	// Fenced examples of the binding line are documentation, not the record.
+	masked, err := markdowntext.Structural(raw)
+	if err != nil {
+		fmt.Fprintf(stdout, "check drift: unproven — eng-review.md unreadable: %v\n", err)
+		return 0
+	}
 	recorded := ""
-	for _, line := range strings.Split(string(raw), "\n") {
+	for _, line := range strings.Split(string(masked), "\n") {
 		if strings.Contains(line, "Readiness inputs SHA-256: ") {
 			recorded = strings.TrimSpace(line)
 		}

package/engine/internal/lib/handoff.go

@@ -148,7 +148,9 @@ func writeHandoffLedger(featureDir string, stdout io.Writer) {
 // writeHandoffDeadEnds replays the decisions.md "## Dead ends" bullets so a
 // resuming agent does not retry approaches already ruled out.
 func writeHandoffDeadEnds(featureDir string, stdout io.Writer) {
-	data := readWorkspaceFile(featureDir, "decisions.md")
+	// Lstat-checked: a symlinked decisions.md could replay lines from any
+	// file outside the workspace.
+	data, _ := readBoundedRegularFile(filepath.Join(featureDir, "decisions.md"), workspaceArtifactLimit)
 	ends := deadEnds(data)
 	if len(ends) == 0 {
 		fmt.Fprintln(stdout, "dead_ends: none")
@@ -164,14 +166,21 @@ func deadEnds(data []byte) []string {
 	inSection := false
 	for _, line := range strings.Split(string(data), "\n") {
 		trimmed := strings.TrimSpace(line)
-		if strings.HasPrefix(trimmed, "##") {
-			inSection = strings.EqualFold(trimmed, "## Dead ends")
+		rest := strings.TrimLeft(trimmed, "#")
+		if level := len(trimmed) - len(rest); level > 0 && (rest == "" || rest[0] == ' ' || rest[0] == '\t') {
+			// Only a level-one or level-two heading leaves the section; a
+			// ### subheading inside it does not.
+			if level <= 2 {
+				inSection = strings.EqualFold(trimmed, "## Dead ends")
+			}
 			continue
 		}
-		if !inSection || !strings.HasPrefix(trimmed, "-") {
+		// A bullet needs "- "; a "---" rule is not an entry.
+		entry, ok := strings.CutPrefix(trimmed, "- ")
+		if !inSection || !ok || strings.TrimSpace(entry) == "" {
 			continue
 		}
-		ends = append(ends, strings.TrimSpace(strings.TrimPrefix(trimmed, "-")))
+		ends = append(ends, strings.TrimSpace(entry))
 	}
 	if len(ends) > deadEndCap {
 		ends = ends[len(ends)-deadEndCap:]