devrites 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -2,12 +2,11 @@
 
 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`.
 
-## [4.3.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.2.0...v4.3.0) (2026-08-25)
+## [4.4.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.3.0...v4.4.0) (2026-08-26)
 
 ### Added
 
-* **devrites:** add skill-trust, task-graph, and observe commands ([#38](https://github.com/ViktorsBaikers/DevRites/issues/38)) ([2562355](https://github.com/ViktorsBaikers/DevRites/commit/2562355a970726fb95e57e2f328961ca136c9f81))
-* **rite-build:** opt-in parallel worktree slices (N≤3) ([#37](https://github.com/ViktorsBaikers/DevRites/issues/37)) ([fe71d67](https://github.com/ViktorsBaikers/DevRites/commit/fe71d672408559af030e95f700b18ead798f18fc))
+* **devrites:** add local visual HTML artifacts and open-visual ([#42](https://github.com/ViktorsBaikers/DevRites/issues/42)) ([577389e](https://github.com/ViktorsBaikers/DevRites/commit/577389ec3016312e51bbdcad918179b161386aed))
 
 ## [4.2.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.1.0...v4.2.0) (2026-08-23)
 

package/README.md

@@ -28,7 +28,7 @@ project-conventional push, tag, or PR action, and archive the workspace.
 Unattended runs may create local WIP checkpoint commits along the way, but they
 remain local unless Ship's disclosed plan includes an approved remote action.
 
-**Status:** [`v4.3.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.3.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v4.4.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.4.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 

package/docs/cli.md

@@ -24,6 +24,7 @@ devrites-engine state resolve <qid> "<answer>"
 devrites-engine state close <slug>
 
 devrites-engine secret-scan [--staged] [--stdin] [slug]
+devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
 devrites-engine version
 ```
 
@@ -69,10 +70,12 @@ with the self-contained updater.
 
 - `check candidate <slug>` validates the strict `touched-files.md` manifest and
   hashes its exact path/state/type/mode/content identity. A pass prints:
+
   ```text
   candidate-sha256: <64 lowercase hex>
   candidate-files: <manifest row count>
   ```
+
 - `check readiness <slug>` verifies the files required to leave the workspace's
   current phase and, once `eng-review.md` is required, its exact stable
   Build-input binding.
@@ -118,6 +121,18 @@ secret bytes. It accepts at most 4,096 entries, 64 MiB total captured input, and
 Findings include only severity, a redacted or escaped source label, category,
 and zero-based byte offset. HIGH findings exit `3`.
 
+## Open visual
+
+`open-visual` resolves a portable HTML visualization under the active or
+`--slug` workspace `visual/` directory, or an absolute/relative `.html` path.
+Unless `--no-open` is set, it launches the OS default browser for that local
+file only. A missing sibling `.outline.md` prints a stderr warning and still
+succeeds. When the outline exists, inventory ids missing from HTML also warn
+(non-fatal; HTML-only decorative ids are ignored). Stdout prints compact agent
+tips: absolute HTML path, outline path (or missing), the playbook index hint,
+and `ids=ok` / `ids=mismatch` when an inventory is present. The command never
+fetches remote hosts.
+
 ## Output and exits
 
 Lifecycle checks print stable line-oriented fields. `reason: DRV-...` identifies

package/docs/engine/commands.md

@@ -7,7 +7,7 @@ workflow strategy.
 ## Complete operational command inventory
 
 | Command | Deterministic responsibility |
-|---|---|
+| --- | --- |
 | `install [flags]` | Install manifest-owned host artifacts and the optional shared binary. |
 | `update [flags]` | Refresh an existing managed installation. |
 | `uninstall [flags]` | Remove managed artifacts while preserving runtime workspace state. |
@@ -15,13 +15,14 @@ workflow strategy.
 | `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, and the current stable Build-input binding when applicable. |
 | `check readiness --emit-binding <slug>` | Render the exact stable Build-input binding for Vet to record after review. |
 | `check seal <slug>` | Check files required by target Phase `seal`, open human gates, the stable Build-input binding, and exact candidate bindings. |
-| `check path-disjoint [--root <dir>] [<json-file>|-]` | Verify slice path sets are pairwise disjoint. |
+| `check path-disjoint` with optional `--root DIR` and optional `JSON-FILE` or `-` | Verify slice path sets are pairwise disjoint. |
 | `check task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles and unknown dependencies. |
 | `check skill-trust <path>` | Scan one skill/agent Markdown file for structural trust violations. |
 | `observe summary <slug>` | Emit sanitized JSON workspace summary from one retained observation. |
 | `state resolve <qid> "<answer>"` | Resolve an open question and update `questions.md` plus `state.md` atomically. |
 | `state close <slug>` | Archive a shipped workspace and clear matching `ACTIVE`. |
 | `secret-scan [--staged] [--stdin] [slug]` | Scan exact staged blobs, stdin, or touched regular files for credential material. |
+| `open-visual <path-or-name> [--slug <slug>] [--no-open]` | Resolve a local visual HTML file, optionally open it in the OS browser, warn if the sibling outline is missing or inventory ids are absent from HTML, and print agent path tips. No network. |
 | `version` | Print the engine version. |
 
 `help`, `-h`, and `--help` print this operational inventory. `version` and
@@ -86,6 +87,19 @@ Each invocation accepts at most 4,096 entries, 64 MiB total captured input, and
 4,096 findings. Findings never include matched bytes, excerpts, or value hashes.
 Input, limit, and output errors exit `2`; HIGH findings exit `3`.
 
+## Open visual
+
+`open-visual` resolves `<path-or-name>` to a local `.html` file under the
+active/`DEVRITES_WORKSPACE`/`--slug` workspace `visual/` directory, or via an
+absolute/relative path. Missing sibling `.outline.md` warns on stderr but does
+not hard-fail. When the outline exists, the engine compares `## ID inventory`
+ids to HTML `id="..."` attributes and warns (non-fatal) for inventory ids
+missing from HTML; HTML-only decorative ids are ignored. Unless `--no-open`,
+the engine starts the OS opener (`open`, `xdg-open`, or Windows `start`) for
+the local file only — never a network fetch. Stdout prints the absolute HTML
+path, outline path tip, playbook index hint, and an `ids=ok` / `ids=mismatch`
+summary when an inventory is present.
+
 ## Output and exit contracts
 
 `check candidate` passes with exactly:
@@ -121,7 +135,7 @@ artifact is classified as `absent`, `empty`, `malformed`, `unsafe`,
 The closed diagnostic codes and recoveries are:
 
 | Code | Exact Gate recovery | Exact standalone readiness-binding payload |
-|---|---|---|
+| --- | --- | --- |
 | `malformed_markdown` | `next: repair <logical-path>: replace invalid Markdown with valid Markdown; required artifacts need substantive content` | `readiness input <logical-path> is malformed (malformed_markdown); replace invalid Markdown with valid Markdown` |
 | `parent_symlink` | `next: repair <logical-path>: replace the symlinked parent with a real directory` | `readiness input <logical-path> is unsafe (parent_symlink); replace the symlinked parent with a real directory` |
 | `final_symlink` | `next: repair <logical-path>: replace the symlink with a regular file` | `readiness input <logical-path> is unsafe (final_symlink); replace the symlink with a regular file` |

package/engine/commands.go

@@ -26,7 +26,7 @@ const (
 func rootModeFor(command string, args []string) rootMode {
 	subcommand := firstRootOperand(args)
 	switch command {
-	case "secret-scan":
+	case "secret-scan", "open-visual":
 		return rootLenient
 	case "state":
 		switch subcommand {

package/engine/internal/lib/open_visual.go

@@ -0,0 +1,254 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/safepath"
+)
+
+const openVisualPlaybookHint = "pack/.claude/skills/devrites-lib/reference/visual-playbooks/index.md"
+
+// openVisualOpener launches a local file in the OS default browser.
+// Tests replace this to assert --no-open and avoid spawning a browser.
+var openVisualOpener = openLocalFile
+
+// OpenVisual resolves a workspace visual HTML file, optionally opens it in the
+// OS browser, warns when the sibling outline is missing or inventory ids are
+// absent from HTML, and prints an agent tip. It never performs network I/O.
+//
+// Usage: open-visual <path-or-name> [--slug <slug>] [--no-open]
+func OpenVisual(root string, args []string, stdout, stderr io.Writer) int {
+	operand, slug, noOpen, err := parseOpenVisualArgs(args)
+	if err != nil {
+		fmt.Fprintf(stderr, "open-visual: %v\n", err)
+		fmt.Fprintln(stderr, "usage: devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]")
+		return 2
+	}
+
+	htmlPath, nameMode, err := resolveOpenVisualHTML(root, slug, operand)
+	if err != nil {
+		fmt.Fprintf(stderr, "open-visual: %v\n", err)
+		return 2
+	}
+
+	info, err := os.Stat(htmlPath)
+	if err != nil {
+		fmt.Fprintf(stderr, "open-visual: cannot open %s: %v\n", htmlPath, err)
+		return 2
+	}
+	if info.IsDir() {
+		fmt.Fprintf(stderr, "open-visual: %s is a directory, not an HTML file\n", htmlPath)
+		return 2
+	}
+	if resolved, err := filepath.EvalSymlinks(htmlPath); err == nil {
+		htmlPath = resolved
+	}
+	if !strings.EqualFold(filepath.Ext(htmlPath), ".html") {
+		fmt.Fprintf(stderr, "open-visual: require a .html file, got %s\n", htmlPath)
+		return 2
+	}
+	if nameMode {
+		feature, err := resolveOpenVisualFeatureDir(root, slug)
+		if err != nil {
+			fmt.Fprintf(stderr, "open-visual: %v\n", err)
+			return 2
+		}
+		visualDir := filepath.Join(feature, "visual")
+		if !safepath.WithinResolved(htmlPath, visualDir) {
+			fmt.Fprintf(stderr, "open-visual: refused: resolved path escapes workspace visual/\n")
+			return 2
+		}
+	}
+
+	outlinePath := strings.TrimSuffix(htmlPath, filepath.Ext(htmlPath)) + ".outline.md"
+	outlineMissing := false
+	if st, err := os.Stat(outlinePath); err != nil || st.IsDir() {
+		outlineMissing = true
+		fmt.Fprintf(stderr, "open-visual: warning: missing outline companion %s\n", outlinePath)
+	}
+
+	var idReport VisualIDConsistency
+	idsChecked := false
+	if !outlineMissing {
+		htmlBody, herr := os.ReadFile(htmlPath)
+		outlineBody, oerr := os.ReadFile(outlinePath)
+		switch {
+		case herr != nil:
+			fmt.Fprintf(stderr, "open-visual: warning: cannot read HTML for id check: %v\n", herr)
+		case oerr != nil:
+			fmt.Fprintf(stderr, "open-visual: warning: cannot read outline for id check: %v\n", oerr)
+		default:
+			idReport = CheckVisualIDConsistency(string(htmlBody), string(outlineBody))
+			idsChecked = true
+			if len(idReport.MissingInHTML) > 0 {
+				fmt.Fprintf(stderr, "open-visual: warning: %d outline inventory id(s) missing from HTML: %s\n",
+					len(idReport.MissingInHTML), strings.Join(idReport.MissingInHTML, ", "))
+			}
+		}
+	}
+
+	// Print tips before OS open so agents still get paths if the opener fails.
+	fmt.Fprintf(stdout, "open-visual: html=%s\n", htmlPath)
+	if outlineMissing {
+		fmt.Fprintf(stdout, "open-visual: outline=(missing) %s\n", outlinePath)
+	} else {
+		fmt.Fprintf(stdout, "open-visual: outline=%s\n", outlinePath)
+	}
+	fmt.Fprintf(stdout, "open-visual: playbooks=%s\n", openVisualPlaybookHint)
+	if idsChecked {
+		switch {
+		case len(idReport.MissingInHTML) > 0:
+			fmt.Fprintf(stdout, "open-visual: ids=mismatch missing=%d inventory=%d\n",
+				len(idReport.MissingInHTML), len(idReport.Inventory))
+		case len(idReport.Inventory) > 0:
+			fmt.Fprintf(stdout, "open-visual: ids=ok (%d inventory)\n", len(idReport.Inventory))
+		}
+	}
+
+	if !noOpen {
+		if err := openVisualOpener(htmlPath); err != nil {
+			fmt.Fprintf(stderr, "open-visual: warning: failed to open browser: %v\n", err)
+			// Tips already printed; HTML is local and resolved — warn-and-continue.
+		}
+	}
+	return 0
+}
+
+func parseOpenVisualArgs(args []string) (operand, slug string, noOpen bool, err error) {
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "--no-open":
+			noOpen = true
+		case arg == "--slug":
+			if i+1 >= len(args) {
+				return "", "", false, fmt.Errorf("--slug requires a value")
+			}
+			i++
+			slug = strings.TrimSpace(args[i])
+			if slug == "" {
+				return "", "", false, fmt.Errorf("--slug requires a value")
+			}
+		case strings.HasPrefix(arg, "--slug="):
+			slug = strings.TrimSpace(strings.TrimPrefix(arg, "--slug="))
+			if slug == "" {
+				return "", "", false, fmt.Errorf("--slug requires a value")
+			}
+		case strings.HasPrefix(arg, "-"):
+			return "", "", false, fmt.Errorf("unknown flag %q", arg)
+		default:
+			if operand != "" {
+				return "", "", false, fmt.Errorf("unexpected argument %q", arg)
+			}
+			operand = arg
+		}
+	}
+	if strings.TrimSpace(operand) == "" {
+		return "", "", false, fmt.Errorf("path or visual name required")
+	}
+	return operand, slug, noOpen, nil
+}
+
+// resolveOpenVisualHTML returns the HTML path and whether the operand was a
+// workspace visual name (nameMode). Absolute/relative path operands open any
+// local .html; name operands resolve under the feature visual/ tree.
+func resolveOpenVisualHTML(root, slug, operand string) (string, bool, error) {
+	if isOpenVisualPathOperand(operand) {
+		abs, err := filepath.Abs(operand)
+		if err != nil {
+			retErr := fmt.Errorf("resolve path: %w", err)
+			return "", false, retErr
+		}
+		cleaned := filepath.Clean(abs)
+		return cleaned, false, nil
+	}
+
+	name := operand
+	if !strings.EqualFold(filepath.Ext(name), ".html") {
+		name += ".html"
+	}
+	if filepath.Base(name) != name {
+		retErr := fmt.Errorf("visual name must not contain path separators")
+		return "", true, retErr
+	}
+
+	feature, err := resolveOpenVisualFeatureDir(root, slug)
+	if err != nil {
+		return "", true, err
+	}
+	htmlPath := filepath.Join(feature, "visual", name)
+	return htmlPath, true, nil
+}
+
+// isOpenVisualPathOperand reports whether operand is a filesystem path rather
+// than a workspace visual name. Absolute paths and operands with separators are
+// paths. Leading "./" or "../" (and bare "." / "..") are relative paths; a
+// leading-dot basename alone (e.g. ".draft") is still a visual name.
+func isOpenVisualPathOperand(operand string) bool {
+	if filepath.IsAbs(operand) {
+		return true
+	}
+	if operand == "." || operand == ".." {
+		return true
+	}
+	if strings.HasPrefix(operand, "./") || strings.HasPrefix(operand, "../") {
+		return true
+	}
+	if strings.HasPrefix(operand, `.\`) || strings.HasPrefix(operand, `..\`) {
+		return true
+	}
+	return strings.ContainsAny(operand, `/\`)
+}
+
+func resolveOpenVisualFeatureDir(root, slug string) (string, error) {
+	if root == "" {
+		retErr := fmt.Errorf("DevRites root required to resolve a visual name")
+		return "", retErr
+	}
+	if slug == "" {
+		active, err := devritespaths.ActiveSlug(root)
+		if err != nil {
+			return "", err
+		}
+		if active == "" {
+			retErr := fmt.Errorf("no slug: pass --slug or set ACTIVE / DEVRITES_WORKSPACE")
+			return "", retErr
+		}
+		slug = active
+	}
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		if os.IsNotExist(err) {
+			retErr := fmt.Errorf("no workspace for slug %q", slug)
+			return "", retErr
+		}
+		return "", err
+	}
+	return dir, nil
+}
+
+func openLocalFile(path string) error {
+	var cmd *exec.Cmd
+	switch runtime.GOOS {
+	case "darwin":
+		// argv only — no shell.
+		cmd = exec.Command("open", path)
+	case "windows":
+		// Avoid cmd.exe /c shell composition; FileProtocolHandler takes one path argv.
+		cmd = exec.Command("rundll32.exe", "url.dll,FileProtocolHandler", path)
+	default:
+		// argv only — no shell.
+		cmd = exec.Command("xdg-open", path)
+	}
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("open local file: %w", err)
+	}
+	return nil
+}

package/engine/internal/lib/open_visual_test.go

@@ -0,0 +1,280 @@
+package lib
+
+import (
+	"bytes"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+func TestOpenVisualResolvesNameUnderWorkspace(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	var opens atomic.Int32
+	restore := swapOpenVisualOpener(func(path string) error {
+		opens.Add(1)
+		if path != html {
+			t.Fatalf("opened %q, want %q", path, html)
+		}
+		return nil
+	})
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if opens.Load() != 1 {
+		t.Fatalf("opener calls = %d, want 1", opens.Load())
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "open-visual: html="+html) {
+		t.Fatalf("stdout missing html tip:\n%s", out)
+	}
+	if !strings.Contains(out, "open-visual: outline="+strings.TrimSuffix(html, ".html")+".outline.md") {
+		t.Fatalf("stdout missing outline tip:\n%s", out)
+	}
+	if !strings.Contains(out, "open-visual: playbooks="+openVisualPlaybookHint) {
+		t.Fatalf("stdout missing playbook tip:\n%s", out)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty", stderr.String())
+	}
+}
+
+func TestOpenVisualAbsolutePathAndNoOpen(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	if root == "" {
+		t.Fatal("empty fixture root")
+	}
+
+	var opens atomic.Int32
+	restore := swapOpenVisualOpener(func(string) error {
+		opens.Add(1)
+		return nil
+	})
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual("", []string{html, "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if opens.Load() != 0 {
+		t.Fatalf("opener calls = %d, want 0 with --no-open", opens.Load())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: html="+html) {
+		t.Fatalf("stdout = %q", stdout.String())
+	}
+}
+
+func TestOpenVisualWarnsMissingOutline(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, false)
+	t.Setenv("DEVRITES_ROOT", root)
+
+	restore := swapOpenVisualOpener(func(string) error { return nil })
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo", "--slug", "feature", "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d", code)
+	}
+	if !strings.Contains(stderr.String(), "warning: missing outline companion") {
+		t.Fatalf("stderr = %q, want missing-outline warning", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: outline=(missing)") {
+		t.Fatalf("stdout = %q, want missing outline tip", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: html="+html) {
+		t.Fatalf("stdout = %q, want html tip for %s", stdout.String(), html)
+	}
+}
+
+func TestOpenVisualUsageErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "missing operand", args: nil, want: "path or visual name required"},
+		{name: "unknown flag", args: []string{"demo", "--poll"}, want: `unknown flag "--poll"`},
+		{name: "slug without value", args: []string{"demo", "--slug"}, want: "--slug requires a value"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := OpenVisual("", test.args, &stdout, &stderr)
+			if code != 2 {
+				t.Fatalf("code = %d, want 2", code)
+			}
+			if stdout.Len() != 0 {
+				t.Fatalf("stdout = %q", stdout.String())
+			}
+			if !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("stderr = %q, want %q", stderr.String(), test.want)
+			}
+		})
+	}
+}
+
+func TestOpenVisualRejectsNonHTML(t *testing.T) {
+	dir := t.TempDir()
+	path := writeBasenameFile(t, dir, "notes.md", "# hi\n")
+	restore := swapOpenVisualOpener(func(string) error {
+		t.Fatal("opener must not run for non-html")
+		return nil
+	})
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual("", []string{path, "--no-open"}, &stdout, &stderr)
+	if code != 2 || !strings.Contains(stderr.String(), "require a .html file") {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+}
+
+func TestOpenVisualRefusesNameModeSymlinkEscape(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	outside := writeBasenameFile(t, t.TempDir(), "escape.html", "<!doctype html><title>escape</title>\n")
+	removeBasename(t, filepath.Dir(html), filepath.Base(html))
+	if err := os.Symlink(outside, html); err != nil {
+		t.Fatal(err)
+	}
+
+	restore := swapOpenVisualOpener(func(string) error {
+		t.Fatal("opener must not run for escaped symlink")
+		return nil
+	})
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo"}, &stdout, &stderr)
+	if code != 2 {
+		t.Fatalf("code = %d, want 2", code)
+	}
+	if !strings.Contains(stderr.String(), "escapes workspace visual/") {
+		t.Fatalf("stderr = %q, want symlink escape refusal", stderr.String())
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("stdout = %q, want empty on refuse", stdout.String())
+	}
+}
+
+func TestOpenVisualPrintsTipsWhenOpenerFails(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	restore := swapOpenVisualOpener(func(string) error {
+		return errors.New("xdg-open: not found")
+	})
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d, want 0 (warn-and-continue)", code)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "open-visual: html="+html) {
+		t.Fatalf("stdout missing html tip:\n%s", out)
+	}
+	if !strings.Contains(out, "open-visual: outline=") {
+		t.Fatalf("stdout missing outline tip:\n%s", out)
+	}
+	if !strings.Contains(out, "open-visual: playbooks="+openVisualPlaybookHint) {
+		t.Fatalf("stdout missing playbook tip:\n%s", out)
+	}
+	if !strings.Contains(stderr.String(), "warning: failed to open browser") {
+		t.Fatalf("stderr = %q, want opener warning", stderr.String())
+	}
+}
+
+func TestIsOpenVisualPathOperandLeadingDotName(t *testing.T) {
+	if isOpenVisualPathOperand(".draft") {
+		t.Fatal(".draft should be a visual name, not a path operand")
+	}
+	if !isOpenVisualPathOperand("./demo.html") {
+		t.Fatal("./demo.html should be a path operand")
+	}
+	if !isOpenVisualPathOperand("../other.html") {
+		t.Fatal("../other.html should be a path operand")
+	}
+}
+
+func writeOpenVisualFixture(t *testing.T, withOutline bool) (root, html string) {
+	t.Helper()
+	project := t.TempDir()
+	root = filepath.Join(project, ".devrites")
+	visual := filepath.Join(root, "work", "feature", "visual")
+	if err := os.MkdirAll(visual, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	html = writeBasenameFile(t, visual, "demo.html", "<!doctype html><title>demo</title>\n")
+	if withOutline {
+		writeBasenameFile(t, visual, "demo.outline.md", "# Title\n\ndemo\n")
+	}
+	writeBasenameFile(t, filepath.Join(root, "work", "feature"), "state.md", "# state\n")
+	if resolved, err := filepath.EvalSymlinks(html); err == nil {
+		html = resolved
+	}
+	if resolved, err := filepath.EvalSymlinks(root); err == nil {
+		root = resolved
+	}
+	return root, html
+}
+
+// writeBasenameFile writes contents under dir using only filepath.Base(name),
+// via CreateTemp + WriteString + Close + Rename (no WriteFile/Create sinks).
+func writeBasenameFile(t *testing.T, dir, name, contents string) string {
+	t.Helper()
+	base := filepath.Base(name)
+	dst := filepath.Join(dir, base)
+	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	written, werr := tmp.WriteString(contents)
+	if werr != nil {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("write: %v; close: %v", werr, cerr)
+		}
+		t.Fatal(werr)
+	}
+	if written != len(contents) {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("short write %d/%d; close: %v", written, len(contents), cerr)
+		}
+		t.Fatalf("short write %d/%d", written, len(contents))
+	}
+	if err := tmp.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Rename(tmp.Name(), dst); err != nil {
+		t.Fatal(err)
+	}
+	return dst
+}
+
+// removeBasename moves dir/filepath.Base(name) out of dir via Rename (no Remove sink).
+func removeBasename(t *testing.T, dir, name string) {
+	t.Helper()
+	src := filepath.Join(dir, filepath.Base(name))
+	dst := filepath.Join(t.TempDir(), filepath.Base(name))
+	if err := os.Rename(src, dst); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func swapOpenVisualOpener(fn func(string) error) func() {
+	prev := openVisualOpener
+	openVisualOpener = fn
+	return func() { openVisualOpener = prev }
+}