devrites 3.2.17 → 3.2.19

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.19](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.18...v3.2.19) (2026-07-28)
+
+### Fixed
+
+* **devrites:** recover ignored Codex reads ([9b0db60](https://github.com/ViktorsBaikers/DevRites/commit/9b0db603b298a8c8d7e36aafa61b909d11c00361))
+
+## [3.2.18](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.17...v3.2.18) (2026-07-28)
+
+### Fixed
+
+* **devrites:** fail closed on filesystem errors ([e0e6c6c](https://github.com/ViktorsBaikers/DevRites/commit/e0e6c6c5c9114fc423cc704b8031d4bcb3728831))
+* **devrites:** validate archive entry types ([02235fb](https://github.com/ViktorsBaikers/DevRites/commit/02235fb078ff4c15bdd36e58c57cc32e6bba8b75))
+
 ## [3.2.17](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.16...v3.2.17) (2026-07-27)
 
 ### Fixed

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.17`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.17): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.19`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.19): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/engine/Makefile

@@ -6,9 +6,9 @@ PLATFORMS := darwin/arm64 darwin/amd64 linux/amd64 linux/arm64 windows/amd64
 
 .PHONY: build fmt-check test test-race vet quality staticcheck govulncheck gosec cover crosscompile clean
 
-STATICCHECK_VERSION := 2025.1.1
-GOVULNCHECK_VERSION := v1.5.0
-GOSEC_VERSION := v2.27.1
+STATICCHECK_VERSION := 2026.1
+GOVULNCHECK_VERSION := v1.6.0
+GOSEC_VERSION := v2.28.0
 STATICCHECK := go run honnef.co/go/tools/cmd/staticcheck@$(STATICCHECK_VERSION)
 GOVULNCHECK := go run golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
 GOSEC := go run github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)

package/engine/internal/install/install.go

@@ -280,14 +280,20 @@ func newRunner(opts Options) (*runner, error) {
 		source = inferSourceDir()
 	}
 	if source != "" {
-		source, _ = filepath.Abs(source)
+		source, err = filepath.Abs(source)
+		if err != nil {
+			return nil, fmt.Errorf("resolve source %s: %w", opts.SourceDir, err)
+		}
 	}
 	payload := opts.PayloadDir
 	if payload == "" {
 		payload = inferPayloadDir(source)
 	}
 	if payload != "" {
-		payload, _ = filepath.Abs(payload)
+		payload, err = filepath.Abs(payload)
+		if err != nil {
+			return nil, fmt.Errorf("resolve payload %s: %w", opts.PayloadDir, err)
+		}
 	}
 	r := &runner{
 		opts:      opts,
@@ -304,7 +310,10 @@ func newRunner(opts Options) (*runner, error) {
 			return nil, fmt.Errorf("validate payload: %w", err)
 		}
 	}
-	r.prev = readManifest(filepath.Join(target, ManifestName))
+	r.prev, err = readManifest(filepath.Join(target, ManifestName))
+	if err != nil {
+		return nil, err
+	}
 	return r, nil
 }
 
@@ -737,13 +746,15 @@ func (r *runner) mergeMarkerFile(merge hostpack.MarkerMerge) error {
 	dest := filepath.Join(r.target, filepath.FromSlash(merge.TargetRel))
 	if r.opts.DryRun {
 		verb := "create DevRites block"
-		if exists(dest) {
-			current, _ := os.ReadFile(dest)
+		current, readErr := os.ReadFile(dest)
+		if readErr == nil {
 			if bytes.Contains(current, []byte(merge.Begin)) {
 				verb = "refresh DevRites block"
 			} else {
 				verb = "append DevRites block"
 			}
+		} else if !errors.Is(readErr, fs.ErrNotExist) {
+			return fmt.Errorf("cannot read %s: %w", merge.TargetRel, readErr)
 		}
 		fmt.Fprintf(r.opts.Stdout, "  [merge] %s (%s)\n", merge.TargetRel, verb)
 	} else {
@@ -751,8 +762,11 @@ func (r *runner) mergeMarkerFile(merge hostpack.MarkerMerge) error {
 			return err
 		}
 		next := block
-		if current, err := os.ReadFile(dest); err == nil {
+		current, readErr := os.ReadFile(dest)
+		if readErr == nil {
 			next = hostpack.MergeMarkerBlock(current, block, merge.Begin, merge.End)
+		} else if !errors.Is(readErr, fs.ErrNotExist) {
+			return fmt.Errorf("cannot read %s: %w", merge.TargetRel, readErr)
 		}
 		if err := fsutil.WriteFileAtomic(dest, next, 0o644); err != nil {
 			return fmt.Errorf("cannot write %s: %w", merge.TargetRel, err)
@@ -974,7 +988,10 @@ func (r *runner) flagsString() string {
 
 func (r *runner) uninstall() error {
 	mf := filepath.Join(r.target, ManifestName)
-	entries := readManifestList(mf)
+	entries, err := readManifestList(mf)
+	if err != nil {
+		return err
+	}
 	if len(entries) == 0 {
 		return fmt.Errorf("no DevRites manifest at %s - nothing to uninstall", mf)
 	}
@@ -1922,20 +1939,23 @@ func readEngineVersion(path string, timeout time.Duration) (string, error) {
 	return line, nil
 }
 
-func readManifest(path string) map[string]managedRecord {
-	records, _ := parseManifest(path)
-	return records
+func readManifest(path string) (map[string]managedRecord, error) {
+	records, _, err := parseManifest(path)
+	return records, err
 }
 
-func readManifestList(path string) []string {
-	_, entries := parseManifest(path)
-	return entries
+func readManifestList(path string) ([]string, error) {
+	_, entries, err := parseManifest(path)
+	return entries, err
 }
 
-func parseManifest(path string) (map[string]managedRecord, []string) {
+func parseManifest(path string) (map[string]managedRecord, []string, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
-		return map[string]managedRecord{}, nil
+		if errors.Is(err, fs.ErrNotExist) {
+			return map[string]managedRecord{}, nil, nil
+		}
+		return nil, nil, fmt.Errorf("read manifest %s: %w", path, err)
 	}
 	hashes := map[string]string{}
 	var out []string
@@ -1967,7 +1987,7 @@ func parseManifest(path string) (map[string]managedRecord, []string) {
 	for _, rel := range out {
 		records[rel] = managedRecord{Hash: hashes[rel]}
 	}
-	return records, out
+	return records, out, nil
 }
 
 func validManagedHash(hash string) bool {

package/engine/internal/install/install_test.go

@@ -18,6 +18,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/devrites/devrites/internal/hostpack"
 	"github.com/devrites/devrites/internal/testutil"
 )
 
@@ -188,6 +189,50 @@ func TestMarkerMergeAndUninstallPreserveUserContent(t *testing.T) {
 	}
 }
 
+func TestMarkerMergeDryRunReportsUnreadableTarget(t *testing.T) {
+	payload := t.TempDir()
+	if err := os.WriteFile(filepath.Join(payload, "block.md"), []byte("DevRites\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	target := t.TempDir()
+	if err := os.Mkdir(filepath.Join(target, "AGENTS.md"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	r := runner{
+		opts:      Options{DryRun: true, Stdout: &bytes.Buffer{}},
+		target:    target,
+		payloadFS: os.DirFS(payload),
+	}
+	err := r.mergeMarkerFile(hostpack.MarkerMerge{
+		TargetRel:  "AGENTS.md",
+		PayloadRel: "block.md",
+		Begin:      "<!-- BEGIN -->",
+		End:        "<!-- END -->",
+	})
+	if err == nil || !strings.Contains(err.Error(), "cannot read AGENTS.md") {
+		t.Fatalf("mergeMarkerFile error = %v, want target read error", err)
+	}
+}
+
+func TestUninstallReportsUnreadableManifest(t *testing.T) {
+	target := t.TempDir()
+	if err := os.Mkdir(filepath.Dir(filepath.Join(target, ManifestName)), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(filepath.Join(target, ManifestName), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	opts := DefaultOptions(ModeUninstall)
+	opts.Target = target
+	err := Apply(opts)
+	if err == nil || !strings.Contains(err.Error(), "read manifest") {
+		t.Fatalf("Apply error = %v, want manifest read error", err)
+	}
+	if info, statErr := os.Stat(filepath.Join(target, ManifestName)); statErr != nil || !info.IsDir() {
+		t.Fatalf("manifest was replaced: info=%v err=%v", info, statErr)
+	}
+}
+
 func TestInstallMergesClaudeHooksIntoExistingSettings(t *testing.T) {
 	t.Setenv("DEVRITES_NO_BINARY", "1")
 	payload := testPayload(t)
@@ -259,7 +304,11 @@ func TestInstallKeepsClaudeMergeOwnershipAcrossReinstall(t *testing.T) {
 	if !exists(filepath.Join(target, filepath.FromSlash(markerRel))) {
 		t.Fatal("first install did not create the Claude hook merge marker")
 	}
-	if _, ok := readManifest(filepath.Join(target, ManifestName))[markerRel]; !ok {
+	manifestRecords, err := readManifest(filepath.Join(target, ManifestName))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := manifestRecords[markerRel]; !ok {
 		t.Fatalf("first install did not record the Claude hook merge marker:\n%s", testutil.ReadFile(t, filepath.Join(target, ManifestName)))
 	}
 	runInstall(t, target, payload, func(o *Options) {})

package/engine/internal/iohooks/iohooks.go

@@ -690,9 +690,9 @@ func repoChangedSince(root, stamp string) bool {
 	}
 	stampTime := info.ModTime()
 	changed := false
-	_ = filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+	if err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
 		if err != nil {
-			return nil
+			return err
 		}
 		if d.IsDir() {
 			if path != root && refreshExcludedDirs[d.Name()] {
@@ -705,7 +705,9 @@ func repoChangedSince(root, stamp string) bool {
 			return filepath.SkipAll
 		}
 		return nil
-	})
+	}); err != nil {
+		return true
+	}
 	return changed
 }
 

package/engine/internal/iohooks/iohooks_test.go

@@ -548,3 +548,14 @@ func TestRefreshStateAndChangeScan(t *testing.T) {
 		t.Fatalf("repoChangedSince=false after tracked file write, want true")
 	}
 }
+
+func TestRepoChangedSinceTreatsScanFailureAsChanged(t *testing.T) {
+	base := t.TempDir()
+	stamp := filepath.Join(base, "stamp")
+	if err := os.WriteFile(stamp, nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if !repoChangedSince(filepath.Join(base, "missing"), stamp) {
+		t.Fatal("repoChangedSince=false after repository scan failure, want conservative refresh")
+	}
+}

package/engine/internal/lib/adoption.go

@@ -584,8 +584,11 @@ func SpecDedupe(root string, args []string, stdout, stderr io.Writer) int {
 	}
 	var hits []hit
 	for _, base := range targets {
-		_ = filepath.WalkDir(base, func(p string, d os.DirEntry, err error) error {
-			if err != nil || d.IsDir() || !strings.HasSuffix(strings.ToLower(p), ".md") {
+		err := filepath.WalkDir(base, func(p string, d os.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if d.IsDir() || !strings.HasSuffix(strings.ToLower(p), ".md") {
 				return nil
 			}
 			lowName := strings.ToLower(filepath.Base(p))
@@ -594,7 +597,7 @@ func SpecDedupe(root string, args []string, stdout, stderr io.Writer) int {
 			}
 			b, err := os.ReadFile(p) // #nosec G122 -- scoring walk over the project's own .scratch tree; a symlink race requires an attacker already writing to the checkout
 			if err != nil {
-				return nil
+				return err
 			}
 			text := strings.ToLower(string(b))
 			score := 0
@@ -604,11 +607,18 @@ func SpecDedupe(root string, args []string, stdout, stderr io.Writer) int {
 				}
 			}
 			if score >= 2 || score == len(terms) {
-				rel, _ := filepath.Rel(project, p)
+				rel, err := filepath.Rel(project, p)
+				if err != nil {
+					return err
+				}
 				hits = append(hits, hit{score: score, path: filepath.ToSlash(rel), line: firstLine(string(b))})
 			}
 			return nil
 		})
+		if err != nil && !os.IsNotExist(err) {
+			fmt.Fprintf(stderr, "spec-dedupe: search %s: %v\n", base, err)
+			return 1
+		}
 	}
 	sort.Slice(hits, func(i, j int) bool {
 		if hits[i].score == hits[j].score {

package/engine/internal/lib/analyze.go

@@ -53,8 +53,16 @@ func Analyze(root string, args []string, stdout, stderr io.Writer) int {
 		return 2
 	}
 
-	specData, _ := os.ReadFile(spec)
-	tasksData, _ := os.ReadFile(tasks)
+	specData, err := os.ReadFile(spec)
+	if err != nil {
+		fmt.Fprintf(stderr, "analyze: read spec.md: %v\n", err)
+		return 2
+	}
+	tasksData, err := os.ReadFile(tasks)
+	if err != nil {
+		fmt.Fprintf(stderr, "analyze: read tasks.md: %v\n", err)
+		return 2
+	}
 
 	specACs := sortedACIDs(acIDRe, specData, true) // legacy brackets stripped: "[AC1]" -> "AC1"
 	taskACs := sortedACIDs(taskACRe, tasksData, false)

package/engine/internal/lib/archivesearch.go

@@ -1,8 +1,10 @@
 package lib
 
 import (
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"sort"
@@ -11,11 +13,11 @@ import (
 
 // ArchiveSearch surfaces shipped features whose spec.md overlaps a query, so
 // /rite-spec can spot prior art before writing a new spec: an extension, a
-// conflict, or a re-spec of solved work. It is advisory, not a gate: it always
-// exits 0 when it runs (empty output means no overlap), and reserves exit 2 for
-// a missing query. The query is the feature's key nouns, one or many args; a
-// quoted phrase is split on whitespace. Ranking is by the count of distinct query
-// terms a spec contains, highest first, ties broken by slug.
+// conflict, or a re-spec of solved work. It is advisory, not a gate: empty
+// output means no overlap. Exit 2 means a missing query; exit 3 means the
+// archive could not be read. The query is the feature's key nouns, one or many
+// args; a quoted phrase is split on whitespace. Ranking is by the count of
+// distinct query terms a spec contains, highest first, ties broken by slug.
 //
 // args is `<term>...`. Terms shorter than three characters are dropped as noise.
 func ArchiveSearch(root string, args []string, stdout, stderr io.Writer) int {
@@ -34,10 +36,24 @@ func ArchiveSearch(root string, args []string, stdout, stderr io.Writer) int {
 		return 2 // usage
 	}
 
-	entries, err := os.ReadDir(filepath.Join(root, "archive"))
+	archive := filepath.Join(root, "archive")
+	info, err := os.Stat(archive)
 	if err != nil {
-		// No archive yet: no prior art to surface. Silent, successful no-op.
-		return 0
+		if errors.Is(err, fs.ErrNotExist) {
+			// No archive yet: no prior art to surface. Silent, successful no-op.
+			return 0
+		}
+		fmt.Fprintf(stderr, "archive-search: read archive: %v\n", err)
+		return 3
+	}
+	if !info.IsDir() {
+		fmt.Fprintf(stderr, "archive-search: read archive: %s is not a directory\n", archive)
+		return 3
+	}
+	entries, err := os.ReadDir(archive)
+	if err != nil {
+		fmt.Fprintf(stderr, "archive-search: read archive: %v\n", err)
+		return 3
 	}
 
 	type hit struct {
@@ -51,9 +67,25 @@ func ArchiveSearch(root string, args []string, stdout, stderr io.Writer) int {
 			continue
 		}
 		spec := filepath.Join(root, "archive", e.Name(), "spec.md")
+		info, err := os.Stat(spec)
+		if err != nil {
+			if errors.Is(err, fs.ErrNotExist) {
+				continue
+			}
+			fmt.Fprintf(stderr, "archive-search: read %s: %v\n", spec, err)
+			return 3
+		}
+		if !info.Mode().IsRegular() {
+			fmt.Fprintf(stderr, "archive-search: read %s: not a regular file\n", spec)
+			return 3
+		}
 		b, err := os.ReadFile(spec)
 		if err != nil {
-			continue
+			if errors.Is(err, fs.ErrNotExist) {
+				continue
+			}
+			fmt.Fprintf(stderr, "archive-search: read %s: %v\n", spec, err)
+			return 3
 		}
 		body := strings.ToLower(string(b))
 		n := 0

package/engine/internal/lib/archivesearch_test.go

@@ -98,6 +98,34 @@ func TestArchiveSearchNoArchive(t *testing.T) {
 	}
 }
 
+func TestArchiveSearchReportsUnreadableArchive(t *testing.T) {
+	root := t.TempDir()
+	if err := os.WriteFile(filepath.Join(root, "archive"), []byte("not a directory"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := ArchiveSearch(root, []string{"anything"}, stdout, stderr); code != 3 {
+		t.Fatalf("code=%d, want 3; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "read archive") {
+		t.Fatalf("stderr=%q, want archive read error", stderr.String())
+	}
+}
+
+func TestArchiveSearchReportsUnreadableSpec(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "archive", "broken", "spec.md"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := ArchiveSearch(root, []string{"anything"}, stdout, stderr); code != 3 {
+		t.Fatalf("code=%d, want 3; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "archive-search: read") {
+		t.Fatalf("stderr=%q, want spec read error", stderr.String())
+	}
+}
+
 func writeArchiveSpec(t *testing.T, root, slug, content string) {
 	t.Helper()
 	dir := filepath.Join(root, "archive", slug)

package/engine/internal/lib/buildreadiness.go

@@ -32,7 +32,11 @@ func BuildReadiness(root string, args []string, stdout, stderr io.Writer) int {
 		return readinessCode("workspace-missing")
 	}
 
-	data, _ := os.ReadFile(s)
+	data, err := os.ReadFile(s)
+	if err != nil {
+		fmt.Fprintf(stderr, "readiness: cannot read state.md: %v\n", err)
+		return readinessCode("workspace-missing")
+	}
 	lines := splitLinesNoTrailing(data)
 
 	status := readinessField(lines, "Status")

package/engine/internal/lib/context.go

@@ -2,8 +2,10 @@ package lib
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
@@ -258,7 +260,10 @@ func upsertContextBlock(path, block string) error {
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
 		return fmt.Errorf("create context dir: %w", err)
 	}
-	existingBytes, _ := os.ReadFile(path)
+	existingBytes, err := os.ReadFile(path)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return fmt.Errorf("read existing context file: %w", err)
+	}
 	existing := string(existingBytes)
 	var next string
 	start := strings.Index(existing, contextStart)

package/engine/internal/lib/extensions.go

@@ -481,7 +481,11 @@ func extensionsSync(extDir, projectDir string, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stderr, "extensions: not syncing: validation failed (run `devrites-engine extensions validate`)")
 		return code
 	}
-	exts, _ := discoverExtensions(extDir)
+	exts, err := discoverExtensions(extDir)
+	if err != nil {
+		fmt.Fprintf(stderr, "extensions: discovery failed: %v\n", err)
+		return 1
+	}
 	if len(exts) == 0 {
 		fmt.Fprintln(stdout, "extensions: nothing to sync")
 		return 0

package/engine/internal/lib/learnings.go

@@ -367,8 +367,11 @@ func countSubdirs(arch string) int {
 // anyFileNewerThan reports whether any regular file under arch was modified after t.
 func anyFileNewerThan(arch string, t time.Time) bool {
 	newer := false
-	_ = filepath.WalkDir(arch, func(_ string, d os.DirEntry, err error) error {
-		if err != nil || d.IsDir() {
+	err := filepath.WalkDir(arch, func(_ string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
 			return nil
 		}
 		if info, err := d.Info(); err == nil && info.Mode().IsRegular() && info.ModTime().After(t) {
@@ -377,6 +380,9 @@ func anyFileNewerThan(arch string, t time.Time) bool {
 		}
 		return nil
 	})
+	if err != nil && !os.IsNotExist(err) {
+		return true
+	}
 	return newer
 }
 

package/engine/internal/lib/ledger.go

@@ -92,7 +92,11 @@ func planFold(root, workspaceDir string, stderr io.Writer) ([]capabilityFold, in
 
 	var folds []capabilityFold
 	for _, capability := range order {
-		fold := foldCapability(root, capability, byCap[capability])
+		fold, err := foldCapability(root, capability, byCap[capability])
+		if err != nil {
+			fmt.Fprintf(stderr, "ledger: %v\n", err)
+			return nil, 2
+		}
 		folds = append(folds, fold)
 	}
 	return folds, 0
@@ -102,8 +106,17 @@ func planFold(root, workspaceDir string, stderr io.Writer) ([]capabilityFold, in
 // A requirement with no delta kind (a flat feature spec) folds as ADDED. ADDED and
 // MODIFIED are both an upsert (replace in place if the header exists, else append);
 // REMOVED deletes. Ordering: existing blocks keep their position, new blocks append.
-func foldCapability(root, capability string, deltas []Requirement) capabilityFold {
-	existing, _ := ParseSpec(ledgerCapabilityPath(root, capability))
+func foldCapability(root, capability string, deltas []Requirement) (capabilityFold, error) {
+	path := ledgerCapabilityPath(root, capability)
+	var existing *SpecDoc
+	if _, err := os.Stat(path); err == nil {
+		existing, err = ParseSpec(path)
+		if err != nil {
+			return capabilityFold{}, fmt.Errorf("read capability %s: %w", capability, err)
+		}
+	} else if !os.IsNotExist(err) {
+		return capabilityFold{}, fmt.Errorf("inspect capability %s: %w", capability, err)
+	}
 	var blocks []Requirement
 	idx := map[string]int{}
 	if existing != nil {
@@ -140,7 +153,7 @@ func foldCapability(root, capability string, deltas []Requirement) capabilityFol
 		}
 	}
 	fold.blocks = blocks
-	return fold
+	return fold, nil
 }
 
 // renderLedgerSpec assembles a capability's ledger spec.md from its resolved blocks.

package/engine/internal/lib/ledger_test.go

@@ -160,3 +160,27 @@ The system SHALL group appearance controls together.
 		}
 	}
 }
+
+func TestLedgerSyncDoesNotOverwriteUnreadableCapability(t *testing.T) {
+	root := t.TempDir()
+	capability := ledgerCapabilityPath(root, "billing")
+	if err := os.MkdirAll(capability, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	wsParent := t.TempDir()
+	writeSpec(t, wsParent, "feat", `## ADDED Requirements — capability: billing
+### Requirement: Invoice export
+The system SHALL export invoices.
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := Ledger(root, []string{"sync", filepath.Join(wsParent, "feat")}, stdout, stderr)
+	if code != 2 {
+		t.Fatalf("sync code=%d, want 2; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "read capability billing") {
+		t.Fatalf("stderr=%q, want capability read error", stderr.String())
+	}
+	if info, err := os.Stat(capability); err != nil || !info.IsDir() {
+		t.Fatalf("capability was overwritten: info=%v err=%v", info, err)
+	}
+}

package/engine/internal/lib/resolve.go

@@ -1,8 +1,10 @@
 package lib
 
 import (
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"regexp"
@@ -182,9 +184,12 @@ func resolveNextQID(qpath string, stdout, stderr io.Writer) int {
 	if qpath == "" {
 		return fail(stderr, "Usage: devrites-engine resolve next-qid <questions.md path>", 5)
 	}
-	var content []byte
-	if isFile(qpath) {
-		content, _ = os.ReadFile(qpath)
+	content, err := os.ReadFile(qpath)
+	if err != nil {
+		if !errors.Is(err, fs.ErrNotExist) {
+			return fail(stderr, "read questions.md: "+err.Error(), 5)
+		}
+		content = nil
 	}
 	qid, err := nextQuestionID(content, clockNow())
 	if err != nil {

package/engine/internal/lib/resolve_remediation_test.go

@@ -48,6 +48,20 @@ func TestResolveAcceptsCanonicalUppercaseQuestionID(t *testing.T) {
 	}
 }
 
+func TestResolveNextQIDReportsUnreadableQuestions(t *testing.T) {
+	qpath := filepath.Join(t.TempDir(), "questions.md")
+	if err := os.Mkdir(qpath, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr bytes.Buffer
+	if code := resolveNextQID(qpath, &stdout, &stderr); code != 5 {
+		t.Fatalf("code = %d, want 5; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "read questions.md") {
+		t.Fatalf("stderr = %q, want read error", stderr.String())
+	}
+}
+
 func resolveWorkspace(t *testing.T, questions string) string {
 	t.Helper()
 	root := t.TempDir()

package/engine/internal/lib/runbook.go

@@ -151,7 +151,10 @@ func executeRunbook(root, path string, start int, runID string, dry bool, stdout
 			return 3
 		}
 	}
-	_ = writeRunbookState(root, runbookState{RunID: runID, Source: path, Next: len(steps), Status: "completed"})
+	if err := writeRunbookState(root, runbookState{RunID: runID, Source: path, Next: len(steps), Status: "completed"}); err != nil {
+		fmt.Fprintf(stderr, "runbook: %v\n", err)
+		return 1
+	}
 	fmt.Fprintf(stdout, "runbook: completed %s\n", runID)
 	return 0
 }