devrites 2.6.0 → 3.0.0

package/engine/tests/parity_testintegrity_test.go

@@ -0,0 +1,65 @@
+package main_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestParityTestIntegrity sets up a real git repo with a committed test file, then
+// a working-tree change that weakens (or doesn't) the test, diffs the repo against
+// HEAD, and checks stdout + exit against the golden snapshot. Read-only w.r.t. git.
+func TestParityTestIntegrity(t *testing.T) {
+	requireGit(t)
+
+	const baseline = "test('a', () => {\n  expect(1).toBe(1);\n  expect(2).toBe(2);\n});\n"
+
+	// setup builds a fresh committed repo and returns its dir; mutate applies the
+	// working-tree change under test (nil = leave clean).
+	newRepo := func(t *testing.T) string {
+		t.Helper()
+		work := t.TempDir()
+		initGitRepo(t, work)
+		writeFile(t, work, "foo_test.js", baseline)
+		gitCommitAll(t, work, "baseline")
+		makeFeatureDir(t, work, "feat")
+		return work
+	}
+	runCase := func(t *testing.T, work string, goArgs ...string) {
+		c := parityCase{
+			workdir: work,
+			env:     libRootEnv(work),
+			goArgs:  append([]string{"test-integrity"}, goArgs...),
+		}
+		c.assertEqual(t)
+	}
+
+	t.Run("clean", func(t *testing.T) {
+		runCase(t, newRepo(t), "feat")
+	})
+	t.Run("skip-added", func(t *testing.T) {
+		work := newRepo(t)
+		writeFile(t, work, "foo_test.js", baseline+"it.skip('later', () => {});\n")
+		runCase(t, work, "feat")
+	})
+	t.Run("assertion-dropped", func(t *testing.T) {
+		work := newRepo(t)
+		writeFile(t, work, "foo_test.js", "test('a', () => {\n  expect(1).toBe(1);\n});\n")
+		runCase(t, work, "feat")
+	})
+	t.Run("deleted", func(t *testing.T) {
+		work := newRepo(t)
+		if err := os.Remove(filepath.Join(work, "foo_test.js")); err != nil {
+			t.Fatal(err)
+		}
+		runCase(t, work, "feat")
+	})
+	t.Run("ghost-workspace", func(t *testing.T) {
+		runCase(t, newRepo(t), "ghost")
+	})
+	t.Run("not-git", func(t *testing.T) {
+		work := t.TempDir() // no initGitRepo -> gate skipped
+		makeFeatureDir(t, work, "feat")
+		runCase(t, work, "feat")
+	})
+}

package/engine/tests/parity_tickafk_test.go

@@ -0,0 +1,83 @@
+package main_test
+
+// Golden snapshot for tick-afk: a MUTATING, layout-agnostic command that takes a
+// state.md path as args[0]. Each fixture runs the Go binary against a fresh
+// state.md and snapshots two artifacts: the command's stdout+exit (under the
+// subtest name) and the resulting file bytes (under "<subtest>/state.md").
+//
+// The no-op / not-a-number messages embed the state.md PATH, which lives under a
+// per-run temp dir, so stdout is normalized (the path -> "<STATE>") before it is
+// snapshotted, keeping the golden deterministic across runs.
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParityTickAfk(t *testing.T) {
+	cases := []struct {
+		name    string
+		content string
+	}{
+		{
+			name:    "budget3",
+			content: "# state\n\nnotes\n- AFK slices remaining: 3\nfooter\n",
+		},
+		{
+			name:    "budget1",
+			content: "- AFK slices remaining: 1\n",
+		},
+		{
+			// Token before the first blank wins: "5 | none" -> "5" -> "4", and the
+			// whole line is rewritten so the "| none" suffix is dropped.
+			name:    "bulletPipe",
+			content: "- AFK slices remaining: 5 | none\n",
+		},
+		{
+			name:    "none",
+			content: "- AFK slices remaining: none\n",
+		},
+		{
+			name:    "missingField",
+			content: "# state\n\nno budget here\n",
+		},
+		{
+			name:    "nonNumeric",
+			content: "- AFK slices remaining: x\n",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			gw := t.TempDir()
+			state := filepath.Join(gw, "state.md")
+			if err := os.WriteFile(state, []byte(tc.content), 0o644); err != nil {
+				t.Fatal(err)
+			}
+
+			out, code := runArgv(t, gw, libEnv, "", binPath, "tick-afk", state)
+			// The no-op / not-a-number message embeds the state.md path (a per-run
+			// temp dir), so normalize it to a fixed token before snapshotting.
+			norm := strings.ReplaceAll(out, state, "<STATE>")
+			assertGolden(t, norm, code)
+
+			// Snapshot the rewritten (or untouched) file bytes under a per-file key.
+			got, err := os.ReadFile(state)
+			if err != nil {
+				t.Fatal(err)
+			}
+			assertGoldenKey(t, t.Name()+"/state.md", string(got))
+		})
+	}
+
+	// Missing file: no state.md to write; the command must exit non-zero with empty
+	// stdout. Only stdout+exit is snapshotted — there is no file to read.
+	t.Run("missingFile", func(t *testing.T) {
+		gw := t.TempDir()
+		state := filepath.Join(gw, "state.md")
+		out, code := runArgv(t, gw, libEnv, "", binPath, "tick-afk", state)
+		assertGolden(t, strings.ReplaceAll(out, state, "<STATE>"), code)
+	})
+}

package/engine/validatepack.go

@@ -0,0 +1,192 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// validate-pack lints the shipped pack's machine-readable surfaces so a
+// malformed hook wiring fails at author time, not silently at runtime. It is the
+// deterministic zero-token counterpart to spec-validate, but for DevRites' OWN
+// config rather than a user's spec. Two checks:
+//
+//  1. Structural — every settings.json / generated hooks.json parses, and each hook
+//     entry is a well-formed {type:"command", command:"…"} (mirrors
+//     schemas/hooks.schema.json, hand-checked to keep the engine dependency-free).
+//  2. Referential — every `devrites-engine hook <id>` in any JSON file names a
+//     hook the binary actually dispatches. A typo'd id (`hook stopgate`) would
+//     otherwise no-op forever; this is the highest-value catch.
+//  3. Markdown contracts (see validatepackskills.go) — SKILL.md / agent
+//     frontmatter is well-formed and the naming invariant holds, and every
+//     docs/command-map.md link into the pack resolves on disk.
+//
+// Exit: 0 clean · 1 violations found · 2 usage / unreadable dir.
+
+// hookCommandRe pulls the hook id out of a wired command, tolerating either
+// binary name and any surrounding shell guard.
+var hookCommandRe = regexp.MustCompile(`devrites(?:-engine)?\s+hook\s+([a-zA-Z0-9-]+)`)
+
+// cmdValidatePack validates the pack config tree rooted at the given dir
+// (default: ./pack/.claude, else ./.claude).
+func cmdValidatePack(args []string, stdout, stderr io.Writer) int {
+	if len(args) > 1 {
+		fmt.Fprintln(stderr, "usage: devrites-engine validate-pack [pack-dir]")
+		return exitUsage
+	}
+	dir := ""
+	if len(args) == 1 {
+		dir = args[0]
+	} else {
+		dir = defaultPackDir()
+	}
+	info, err := os.Stat(dir)
+	if err != nil || !info.IsDir() {
+		fmt.Fprintf(stderr, "devrites: validate-pack: not a directory: %s\n", dir)
+		return exitUsage
+	}
+
+	var issues []string
+	files := 0
+	err = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			rel, relErr := filepath.Rel(dir, path)
+			if relErr != nil {
+				rel = path
+			}
+			issues = append(issues, fmt.Sprintf("%s: cannot inspect: %v", rel, err))
+			return nil
+		}
+		if d.IsDir() || filepath.Ext(path) != ".json" {
+			return nil
+		}
+		rel, _ := filepath.Rel(dir, path)
+		data, err := os.ReadFile(path) // #nosec G122 -- validation walk over the pack dir the operator passed in; a symlink race requires an attacker already writing to that checkout
+		if err != nil {
+			issues = append(issues, fmt.Sprintf("%s: cannot read: %v", rel, err))
+			return nil
+		}
+		var doc any
+		if err := json.Unmarshal(data, &doc); err != nil {
+			issues = append(issues, fmt.Sprintf("%s: invalid JSON: %v", rel, err))
+			return nil
+		}
+		files++
+		// Referential: every wired hook id must be one the binary dispatches.
+		for _, id := range hookIDsInCommands(data) {
+			if _, ok := hookRegistry[id]; !ok {
+				issues = append(issues, fmt.Sprintf("%s: unknown hook id %q — not a command the engine dispatches", rel, id))
+			}
+		}
+		// Structural: only files that carry a `hooks` object in the .claude shape.
+		if base := filepath.Base(path); base == "settings.json" || base == "hooks.json" {
+			issues = append(issues, structuralIssues(rel, doc)...)
+		}
+		return nil
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "devrites: validate-pack: %v\n", err)
+		return exitUsage
+	}
+
+	// Markdown contracts: SKILL.md / agent frontmatter + naming invariant, then
+	// the docs/command-map.md → pack link claims. Same issues slice/format.
+	contractIssues, contracts := packContractIssues(dir)
+	issues = append(issues, contractIssues...)
+	issues = append(issues, docClaimIssues(dir)...)
+
+	if len(issues) > 0 {
+		sort.Strings(issues)
+		fmt.Fprintf(stderr, "validate-pack: %d issue(s):\n", len(issues))
+		for _, s := range issues {
+			fmt.Fprintf(stderr, "  - %s\n", s)
+		}
+		return 1
+	}
+	fmt.Fprintf(stdout, "validate-pack: OK (%d JSON file(s), %d known hook ids, %d skill/agent contract(s))\n", files, len(hookRegistry), contracts)
+	return exitOK
+}
+
+// defaultPackDir picks the conventional pack root relative to the working dir.
+func defaultPackDir() string {
+	for _, c := range []string{filepath.Join("pack", ".claude"), ".claude"} {
+		if info, err := os.Stat(c); err == nil && info.IsDir() {
+			return c
+		}
+	}
+	return filepath.Join("pack", ".claude")
+}
+
+// hookIDsInCommands returns every hook id referenced by a `devrites-engine hook
+// <id>` command anywhere in the raw JSON bytes. Scanning the bytes (not the
+// decoded tree) keeps it robust to harness-specific wiring shapes (Claude vs
+// Codex) that place commands at different nesting depths.
+func hookIDsInCommands(data []byte) []string {
+	var ids []string
+	for _, m := range hookCommandRe.FindAllSubmatch(data, -1) {
+		ids = append(ids, string(m[1]))
+	}
+	return ids
+}
+
+// structuralIssues checks the .claude hooks shape: hooks -> event -> [ {matcher?,
+// hooks:[ {type:"command", command:"…"} ]} ].
+func structuralIssues(rel string, doc any) []string {
+	var issues []string
+	top, ok := doc.(map[string]any)
+	if !ok {
+		return []string{fmt.Sprintf("%s: top level is not a JSON object", rel)}
+	}
+	hooksAny, present := top["hooks"]
+	if !present {
+		return nil // not a hooks file (e.g. a settings.json with only statusLine)
+	}
+	events, ok := hooksAny.(map[string]any)
+	if !ok {
+		return []string{fmt.Sprintf("%s: \"hooks\" is not an object", rel)}
+	}
+	for event, groupsAny := range events {
+		groups, ok := groupsAny.([]any)
+		if !ok {
+			issues = append(issues, fmt.Sprintf("%s: hooks.%s is not an array", rel, event))
+			continue
+		}
+		for i, gAny := range groups {
+			g, ok := gAny.(map[string]any)
+			if !ok {
+				issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d] is not an object", rel, event, i))
+				continue
+			}
+			entriesAny, ok := g["hooks"]
+			if !ok {
+				issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d] missing \"hooks\" array", rel, event, i))
+				continue
+			}
+			entries, ok := entriesAny.([]any)
+			if !ok || len(entries) == 0 {
+				issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d].hooks is empty or not an array", rel, event, i))
+				continue
+			}
+			for j, eAny := range entries {
+				e, ok := eAny.(map[string]any)
+				if !ok {
+					issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d].hooks[%d] is not an object", rel, event, i, j))
+					continue
+				}
+				if t, _ := e["type"].(string); t != "command" {
+					issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d].hooks[%d] type must be \"command\", got %q", rel, event, i, j, t))
+				}
+				if c, _ := e["command"].(string); strings.TrimSpace(c) == "" {
+					issues = append(issues, fmt.Sprintf("%s: hooks.%s[%d].hooks[%d] has an empty command", rel, event, i, j))
+				}
+			}
+		}
+	}
+	return issues
+}

package/engine/validatepack_test.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/devrites/devrites/internal/testutil"
+)
+
+const goodSettings = `{
+  "hooks": {
+    "SessionStart": [
+      { "hooks": [ { "type": "command", "command": "command -v devrites-engine >/dev/null 2>&1 && exec devrites-engine hook orient --harness=claude || exit 0" } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "exec devrites-engine hook allow --harness=claude" } ] }
+    ]
+  }
+}`
+
+func TestValidatePackGood(t *testing.T) {
+	dir := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(dir, "settings.json"), goodSettings)
+	var out, errb bytes.Buffer
+	if code := cmdValidatePack([]string{dir}, &out, &errb); code != exitOK {
+		t.Fatalf("expected OK, got %d; stderr=%s", code, errb.String())
+	}
+}
+
+func TestValidatePackUnknownHookID(t *testing.T) {
+	dir := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(dir, "settings.json"), `{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"devrites-engine hook stopgate --harness=claude"}]}]}}`)
+	var out, errb bytes.Buffer
+	if code := cmdValidatePack([]string{dir}, &out, &errb); code != 1 {
+		t.Fatalf("expected exit 1 for typo'd hook id, got %d", code)
+	}
+	if !bytes.Contains(errb.Bytes(), []byte("stopgate")) {
+		t.Errorf("expected the unknown id in the report, got: %s", errb.String())
+	}
+}
+
+func TestValidatePackStructural(t *testing.T) {
+	dir := t.TempDir()
+	// type is not "command", and an empty command.
+	testutil.WriteFile(t, filepath.Join(dir, "hooks.json"), `{"hooks":{"Stop":[{"hooks":[{"type":"prompt","command":""}]}]}}`)
+	var out, errb bytes.Buffer
+	if code := cmdValidatePack([]string{dir}, &out, &errb); code != 1 {
+		t.Fatalf("expected exit 1 for structural violations, got %d", code)
+	}
+}
+
+func TestValidatePackInvalidJSON(t *testing.T) {
+	dir := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(dir, "settings.json"), `{"hooks": `)
+	var out, errb bytes.Buffer
+	if code := cmdValidatePack([]string{dir}, &out, &errb); code != 1 {
+		t.Fatalf("expected exit 1 for invalid JSON, got %d", code)
+	}
+}
+
+func TestValidatePackReportsUnreadableJSON(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink fixture requires Unix semantics")
+	}
+	dir := t.TempDir()
+	if err := os.Symlink(filepath.Join(dir, "missing-target"), filepath.Join(dir, "unreadable.json")); err != nil {
+		t.Fatal(err)
+	}
+	var out, errb bytes.Buffer
+	if code := cmdValidatePack([]string{dir}, &out, &errb); code != 1 {
+		t.Fatalf("expected exit 1 for unreadable JSON, got %d", code)
+	}
+	if !bytes.Contains(errb.Bytes(), []byte("unreadable.json: cannot read")) {
+		t.Fatalf("expected unreadable path in report, got: %s", errb.String())
+	}
+}

package/engine/validatepackskills.go

@@ -0,0 +1,181 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// This file extends validate-pack (see validatepack.go) from linting the pack's
+// JSON hook wiring to linting its markdown *contracts* — the SKILL.md / agent
+// frontmatter that Claude and Codex parse, and the docs → pack links that drift
+// silently when a skill is renamed. Same output shape as the JSON pass
+// (`rel: message`, appended to the shared issues slice, sorted, exit 1 if any).
+//
+// It is deliberately stdlib-only: the frontmatter parser is a minimal
+// top-level-key scanner (no nesting, no YAML dependency), which is all the
+// contract needs — name/description/user-invocable are always scalar top-level
+// keys.
+//
+// Checks:
+//
+//	A. Frontmatter contract — every skills/*/SKILL.md and agents/*.md opens with
+//	   a terminated `---` block carrying non-empty name + description (skills also
+//	   user-invocable), and its name matches the directory (skills) or filename
+//	   (agents).
+//	B. Naming invariant (docs/command-map.md "Naming convention") — a devrites-*
+//	   skill is model-invoked only (never user-invocable:true); a user-invocable
+//	   skill lives under a rite-* directory (the bare `rite` router included).
+//	C. Doc-claims — every ../pack/.claude/... link in docs/command-map.md must
+//	   resolve to a file on disk, catching stale docs after a rename/move.
+
+// docLinkRe pulls the target out of any markdown link `](target)`. We filter to
+// pack/.claude targets afterwards rather than in the pattern so nested reference
+// links (e.g. devrites-lib/reference/…) are covered too.
+var docLinkRe = regexp.MustCompile(`\]\(([^)\s]+)\)`)
+
+// packContractIssues runs the frontmatter + naming contract over every skill and
+// agent markdown under the pack root. It returns the issues (already prefixed
+// with a dir-relative path) and the number of contract files inspected.
+func packContractIssues(dir string) (issues []string, checked int) {
+	skillFiles, _ := filepath.Glob(filepath.Join(dir, "skills", "*", "SKILL.md"))
+	for _, p := range skillFiles {
+		skillDir := filepath.Base(filepath.Dir(p))
+		if strings.HasPrefix(skillDir, ".") {
+			continue // tooling dirs like .impeccable are not shipped skills
+		}
+		rel, _ := filepath.Rel(dir, p)
+		checked++
+		issues = append(issues, frontmatterIssues(rel, p, skillDir, true)...)
+	}
+	agentFiles, _ := filepath.Glob(filepath.Join(dir, "agents", "*.md"))
+	for _, p := range agentFiles {
+		base := filepath.Base(p)
+		if strings.HasPrefix(base, ".") {
+			continue
+		}
+		name := strings.TrimSuffix(base, ".md")
+		rel, _ := filepath.Rel(dir, p)
+		checked++
+		issues = append(issues, frontmatterIssues(rel, p, name, false)...)
+	}
+	return issues, checked
+}
+
+// frontmatterIssues validates one markdown contract file. expectName is the
+// directory name (skills) or the filename sans .md (agents) that `name:` must
+// equal; isSkill toggles the skill-only checks (user-invocable key + the
+// rite-/devrites- naming invariant).
+func frontmatterIssues(rel, path, expectName string, isSkill bool) []string {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return []string{fmt.Sprintf("%s: unreadable: %v", rel, err)}
+	}
+	keys, opened, terminated := parseFrontmatter(data)
+	if !opened {
+		return []string{fmt.Sprintf("%s: missing YAML frontmatter (file must open with a --- block)", rel)}
+	}
+	if !terminated {
+		return []string{fmt.Sprintf("%s: unterminated frontmatter (no closing ---)", rel)}
+	}
+
+	var issues []string
+	required := []string{"name", "description"}
+	if isSkill {
+		required = append(required, "user-invocable")
+	}
+	for _, k := range required {
+		if strings.TrimSpace(keys[k]) == "" {
+			issues = append(issues, fmt.Sprintf("%s: missing or empty required frontmatter key %q", rel, k))
+		}
+	}
+
+	if got := keys["name"]; got != "" && got != expectName {
+		kind := "directory"
+		if !isSkill {
+			kind = "filename"
+		}
+		issues = append(issues, fmt.Sprintf("%s: name %q must equal the %s name %q", rel, got, kind, expectName))
+	}
+
+	if isSkill {
+		userInvocable := keys["user-invocable"] == "true"
+		// B4: a devrites-* skill is model-invoked only.
+		if strings.HasPrefix(expectName, "devrites-") && userInvocable {
+			issues = append(issues, fmt.Sprintf("%s: devrites-* skills are model-invoked only — must not set user-invocable: true", rel))
+		}
+		// B5: a user-invocable skill lives under rite-* (the bare `rite` router included).
+		if userInvocable && expectName != "rite" && !strings.HasPrefix(expectName, "rite-") {
+			issues = append(issues, fmt.Sprintf("%s: user-invocable skills must use the rite-* directory prefix (per docs/command-map.md naming convention)", rel))
+		}
+	}
+	return issues
+}
+
+// parseFrontmatter reads a leading `---` … `---` block and returns its top-level
+// scalar keys. opened is true when the file starts with a `---` line; terminated
+// is true when a closing `---` was found. Indented (nested), blank, and comment
+// lines are skipped, so an agent's `hooks:`/`tools:` sub-tree does not pollute
+// the top-level key map. Surrounding quotes on values are stripped.
+func parseFrontmatter(data []byte) (keys map[string]string, opened, terminated bool) {
+	text := strings.ReplaceAll(string(data), "\r\n", "\n")
+	text = strings.TrimPrefix(text, "\uFEFF") // tolerate a UTF-8 BOM
+	lines := strings.Split(text, "\n")
+	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
+		return nil, false, false
+	}
+	keys = map[string]string{}
+	for _, line := range lines[1:] {
+		if strings.TrimSpace(line) == "---" {
+			return keys, true, true
+		}
+		if line == "" || line[0] == ' ' || line[0] == '\t' || line[0] == '#' {
+			continue // blank / nested / comment — not a top-level key
+		}
+		idx := strings.Index(line, ":")
+		if idx <= 0 {
+			continue
+		}
+		k := strings.TrimSpace(line[:idx])
+		v := strings.TrimSpace(line[idx+1:])
+		v = strings.Trim(v, `"'`)
+		keys[k] = v
+	}
+	return keys, true, false // opened but never closed
+}
+
+// docClaimIssues verifies every markdown link into ../pack/.claude in
+// docs/command-map.md resolves to a real file. The doc is located relative to
+// the repo root (the pack dir's grandparent: <root>/pack/.claude → <root>);
+// if it is absent the pass is a silent no-op.
+func docClaimIssues(dir string) []string {
+	repoRoot := filepath.Dir(filepath.Dir(dir))
+	docPath := filepath.Join(repoRoot, "docs", "command-map.md")
+	data, err := os.ReadFile(docPath)
+	if err != nil {
+		return nil // no command-map to cross-check — skip silently
+	}
+	docDir := filepath.Dir(docPath)
+	seen := map[string]bool{}
+	var issues []string
+	for _, m := range docLinkRe.FindAllStringSubmatch(string(data), -1) {
+		link := m[1]
+		if i := strings.IndexByte(link, '#'); i >= 0 {
+			link = link[:i] // drop any anchor fragment
+		}
+		if link == "" || !strings.Contains(link, "pack/.claude") {
+			continue // only cross-check links that point into the pack
+		}
+		if seen[link] {
+			continue
+		}
+		seen[link] = true
+		resolved := filepath.Clean(filepath.Join(docDir, link))
+		if _, err := os.Stat(resolved); err != nil {
+			issues = append(issues, fmt.Sprintf("docs/command-map.md: stale link — %q does not exist on disk", link))
+		}
+	}
+	return issues
+}