devrites 4.3.0 → 4.4.1

package/docs/engine/commands.md

@@ -7,21 +7,22 @@ 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. |
 | `check candidate <slug>` | Validate the strict manifest and compute the content-bound project-candidate identity. |
-| `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, and the current stable Build-input binding when applicable. |
+| `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, the `tasks.md` slice graph when that artifact is required, 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 task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles and unknown dependencies. |
+| `check seal <slug>` | Check files required by target Phase `seal`, open human gates, the `tasks.md` slice graph, the stable Build-input binding, and exact candidate bindings. |
+| `check path-disjoint [--root <dir>] [<json-file> | -]` | Verify slice path sets are pairwise disjoint. |
+| `check task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles, unknown deps, malformed tokens, duplicate IDs, missing `Dependencies`, and `depends_on` mismatch. |
 | `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. |
+| `observe summary <slug>` | Emit sanitized JSON workspace summary from one retained observation. `task_graph.ok` is true iff `task_graph.problems` is empty; `problems` lists cycle, unknown-dep, malformed-token, duplicate-id, and missing-`Dependencies` blockers. |
 | `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
@@ -35,8 +36,9 @@ not to the engine command namespace.
 The candidate gate validates and hashes path/state/type/mode/content identity;
 it does not infer scope from Git. The readiness gate checks target-Phase
 structure and applies open-question blocking only when that target is Clarify
-or later, plus the exact stable Build-input binding after Vet. The seal gate
-always targets Phase `seal`, repeats that binding, and checks exact candidate
+or later, plus the exact `tasks.md` slice graph when `tasks.md` is required,
+plus the exact stable Build-input binding after Vet. The seal gate
+always targets Phase `seal`, repeats that graph and binding, and checks exact candidate
 bindings in evidence, optional browser evidence, review, and seal. None judges
 the meaning of `CLEAR`/`READY` prose,
 parses reviewer narratives, infers acceptance coverage, counts assertions,
@@ -86,6 +88,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 +136,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/docs/engine/workspace-schema.md

@@ -166,11 +166,11 @@ The engine provides only:
 - `check candidate`: strict candidate-manifest validation and content-bound
   identity;
 - `check readiness`: phase-relative file completeness, open-human-gate check,
-  and the stable vetted Build-input binding whenever `eng-review.md` is
-  required;
-- `check seal`: final file completeness and open-human-gate checks, then the
-  readiness-binding recheck, then exact candidate bindings after that aggregate
-  gate passes;
+  the `tasks.md` slice graph when that artifact is required, and the stable
+  vetted Build-input binding whenever `eng-review.md` is required;
+- `check seal`: final file completeness and open-human-gate checks, the
+  `tasks.md` slice graph, then the readiness-binding recheck, then exact
+  candidate bindings after that aggregate gate passes;
 - atomic `state resolve` answer/drop/batch and transactional `state close`;
 - secret scanning, version reporting, and local install lifecycle primitives.
 

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/gate/gate.go

@@ -94,6 +94,15 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			blocked = true
 		}
 	}
+	if len(missingFiles) == 0 && phaseRequiresTasks(policy) {
+		if fact, ok := observation.Fact("tasks.md"); ok && fact.State() == state.ArtifactPresent {
+			graph := state.ParseTaskGraph(fact.Bytes())
+			for _, problem := range graph.Problems {
+				stateProblems = append(stateProblems, "task-graph: "+problem)
+				blocked = true
+			}
+		}
+	}
 	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(policy) {
 		expected, bindingErr := verifyReadinessBinding(observation)
 		if bindingErr != nil {

package/engine/internal/gate/gate_test.go

@@ -12,6 +12,114 @@ import (
 	"github.com/devrites/devrites/internal/testutil"
 )
 
+func TestCheckBlocksCyclicTaskGraphWhenTasksAreRequired(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "cyclic", "build")
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), `# Tasks
+
+## SLICE-001 A
+Dependencies: SLICE-002
+
+## SLICE-002 B
+Dependencies: SLICE-001
+`)
+	binding := mustReadinessBinding(t, root, "cyclic")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	res, err := Check(Readiness, root, "cyclic")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked || res.ReasonID != reason.GateReadinessMissing {
+		t.Fatalf("blocked=%v reason=%q, want blocked missing", res.Blocked, res.ReasonID)
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !strings.Contains(joined, "task-graph: dependency cycle:") {
+		t.Fatalf("StateProblems=%q", joined)
+	}
+	if !strings.Contains(res.Render(), "result: blocked (state invariant)") {
+		t.Fatalf("Render()=\n%s", res.Render())
+	}
+}
+
+func TestCheckBlocksCyclicTaskGraphAtSeal(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "cyclic-seal", state.PhaseSeal, state.PhaseSeal, "none\n")
+	workspace := filepath.Join(root, "work", "cyclic-seal")
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), `# Tasks
+
+## SLICE-001 A
+Dependencies: SLICE-002
+
+## SLICE-002 B
+Dependencies: SLICE-001
+`)
+	binding := mustReadinessBinding(t, root, "cyclic-seal")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	res, err := Check(Seal, root, "cyclic-seal")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked || res.ReasonID != reason.GateSealMissing {
+		t.Fatalf("blocked=%v reason=%q, want blocked %s", res.Blocked, res.ReasonID, reason.GateSealMissing)
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !strings.Contains(joined, "task-graph: dependency cycle:") {
+		t.Fatalf("StateProblems=%q", joined)
+	}
+	if !strings.Contains(res.Render(), "result: blocked (state invariant)") {
+		t.Fatalf("Render()=\n%s", res.Render())
+	}
+}
+
+func TestCheckBlocksMalformedTaskGraphInsteadOfDroppingTokens(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "malformed", "define")
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), `# Tasks
+
+## SLICE-001 Ready
+Dependencies: none
+
+## SLICE-002 Next
+Dependencies: SLICE-001 and later
+`)
+
+	res, err := Check(Readiness, root, "malformed")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked {
+		t.Fatal("expected malformed dependency to block readiness")
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !strings.Contains(joined, `malformed dependency "and"`) || !strings.Contains(joined, `malformed dependency "later"`) {
+		t.Fatalf("StateProblems=%q", joined)
+	}
+}
+
+func TestCheckBlocksMissingDependenciesInsteadOfTreatingSliceAsIndependent(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "nodeps", "define")
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), `# Tasks
+
+## SLICE-001 Ready
+Goal: looks complete without an ordering field
+`)
+
+	res, err := Check(Readiness, root, "nodeps")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked {
+		t.Fatal("expected missing Dependencies to block readiness")
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !strings.Contains(joined, "SLICE-001 is missing Dependencies") {
+		t.Fatalf("StateProblems=%q", joined)
+	}
+}
+
 func TestCheckAndRenderReadiness(t *testing.T) {
 	root := t.TempDir()
 	writeFeature(t, root, "alpha", map[string]string{
@@ -505,6 +613,8 @@ func writeCompleteGateFeature(t *testing.T, root, slug string, current, required
 		case "questions.md":
 			questionsRequired = true
 			content = questions
+		case "tasks.md":
+			content = testutil.CanonicalTasksMarkdown
 		}
 		testutil.WriteFile(t, filepath.Join(root, "work", slug, name), content)
 	}

package/engine/internal/gate/readiness_binding.go

@@ -148,6 +148,15 @@ func readinessDiagnosticError(diagnostic state.ArtifactDiagnostic) error {
 	return errors.New(prefix + repair)
 }
 
+func phaseRequiresTasks(policy state.PhasePolicy) bool {
+	for _, artifact := range policy.RequiredArtifacts {
+		if artifact == "tasks.md" {
+			return true
+		}
+	}
+	return false
+}
+
 func phaseRequiresReadinessBinding(policy state.PhasePolicy) bool {
 	for _, artifact := range policy.RequiredArtifacts {
 		if artifact == "eng-review.md" {

package/engine/internal/gate/readiness_binding_test.go

@@ -91,7 +91,7 @@ func TestReadinessBindingBindsOnlyStableBuildInputs(t *testing.T) {
 func TestReadinessBindingGoldenDigest(t *testing.T) {
 	root := t.TempDir()
 	writeReadinessFixture(t, root, "golden", "build")
-	const want = "Readiness inputs SHA-256: d84b9050bd8db742c6a379a966bd7457cde04a69d6811130817729776d976ebe"
+	const want = "Readiness inputs SHA-256: c4a073e85373f5fd9f9302c61b6772e766e4fa2a3da2ccc77bad23756c9f412d"
 	if got := mustReadinessBinding(t, root, "golden"); got != want {
 		t.Fatalf("ReadinessBinding()=%q, want %q", got, want)
 	}
@@ -374,7 +374,7 @@ func writeReadinessFixture(t *testing.T, root, slug, phase string) string {
 		"decision-coverage.md": "# Decision coverage\n\nCLEAR\n",
 		"architecture.md":      "# Architecture\n\nReady.\n",
 		"plan.md":              "# Plan\n\nReady.\n",
-		"tasks.md":             "# Tasks\n\nReady.\n",
+		"tasks.md":             testutil.CanonicalTasksMarkdown,
 		"traceability.md":      "# Traceability\n\nReady.\n",
 		"eng-review.md":        "# Engineering review\n\nREADY\n",
 		"test-plan.md":         "# Test plan\n\nReady.\n",

package/engine/internal/lib/observe_summary.go

@@ -7,21 +7,25 @@ import (
 	"github.com/devrites/devrites/internal/state"
 )
 
+// ObserveTaskGraph is the slice-graph subset of ObserveSummary.
+type ObserveTaskGraph struct {
+	SliceCount int      `json:"slice_count"`
+	Cycle      []string `json:"cycle,omitempty"`
+	Unknown    []string `json:"unknown_dependencies,omitempty"`
+	Problems   []string `json:"problems,omitempty"`
+	OK         bool     `json:"ok"`
+}
+
 // ObserveSummary is a sanitized, machine-readable workspace snapshot.
 type ObserveSummary struct {
-	Slug              string   `json:"slug"`
-	Phase             string   `json:"phase,omitempty"`
-	Status            string   `json:"status,omitempty"`
-	NextAction        string   `json:"next_action,omitempty"`
-	MissingSections   []string `json:"missing_sections,omitempty"`
-	MissingFiles      []string `json:"missing_files,omitempty"`
-	PrinciplesPresent bool     `json:"principles_present"`
-	TaskGraph         *struct {
-		SliceCount int      `json:"slice_count"`
-		Cycle      []string `json:"cycle,omitempty"`
-		Unknown    []string `json:"unknown_dependencies,omitempty"`
-		OK         bool     `json:"ok"`
-	} `json:"task_graph,omitempty"`
+	Slug              string            `json:"slug"`
+	Phase             string            `json:"phase,omitempty"`
+	Status            string            `json:"status,omitempty"`
+	NextAction        string            `json:"next_action,omitempty"`
+	MissingSections   []string          `json:"missing_sections,omitempty"`
+	MissingFiles      []string          `json:"missing_files,omitempty"`
+	PrinciplesPresent bool              `json:"principles_present"`
+	TaskGraph         *ObserveTaskGraph `json:"task_graph,omitempty"`
 }
 
 // ObserveSummaryFor builds a summary for one feature slug.
@@ -40,16 +44,12 @@ func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
 		MissingSections:   missingSectionNames(report.Missing),
 	}
 
-	if graph, graphErr := CheckTaskGraph(root, slug); graphErr == nil && len(graph.Slices) > 0 {
-		summary.TaskGraph = &struct {
-			SliceCount int      `json:"slice_count"`
-			Cycle      []string `json:"cycle,omitempty"`
-			Unknown    []string `json:"unknown_dependencies,omitempty"`
-			OK         bool     `json:"ok"`
-		}{
+	if graph, graphErr := CheckTaskGraph(root, slug); graphErr == nil && (len(graph.Slices) > 0 || len(graph.Problems) > 0) {
+		summary.TaskGraph = &ObserveTaskGraph{
 			SliceCount: len(graph.Slices),
-			Cycle:      graph.Cycle,
-			Unknown:    graph.Unknown,
+			Cycle:      append([]string(nil), graph.Cycle...),
+			Unknown:    append([]string(nil), graph.Unknown...),
+			Problems:   append([]string(nil), graph.Problems...),
 			OK:         len(graph.Problems) == 0,
 		}
 	}

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
+}