devrites 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.4.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.3.0...v4.4.0) (2026-08-26)
+
+### Added
+
+* **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)
 
 ### Added

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.2.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.2.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,9 +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` 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
@@ -82,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:
@@ -117,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/docs/orchestration.md

@@ -126,9 +126,12 @@ base before native transfer, then re-proves the reconciled candidate. Missing tr
 conflict, extra paths, moved base, or cleanup failure stops with worktree evidence
 preserved. No ad hoc copy/cherry-pick/merge occurs from the read-only root.
 
-Isolation does not authorize throughput. At most one writer runs across all linked
-worktrees for the workspace; parallel writers remain forbidden until serial transfer,
-conflict, proof, and review measurements justify a separate design.
+Isolation does not authorize same-worktree throughput. Parallel writers are allowed
+**only** under `/rite-build --parallel N` when path-disjoint eligibility, abort-batch,
+and a control `parallel-lease.md` apply (see
+[`parallel-batch.md`](../pack/.claude/skills/rite-build/reference/parallel-batch.md)).
+Same-worktree multi-writer and root-emulated worktrees remain forbidden; default
+`/rite-build` stays one writer across linked worktrees.
 
 ## Engine boundary
 

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

@@ -0,0 +1,66 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+// RunTaskGraphCheck validates tasks.md for one slug.
+func RunTaskGraphCheck(root, slug string, stdout, stderr io.Writer) int {
+	graph, err := CheckTaskGraph(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "task-graph: %v\n", err)
+		return 2
+	}
+	if len(graph.Problems) > 0 {
+		for _, problem := range graph.Problems {
+			fmt.Fprintf(stdout, "task-graph: BLOCKED: %s\n", problem)
+		}
+		return 3
+	}
+	fmt.Fprintf(stdout, "task-graph: ok (%d slices)\n", len(graph.Slices))
+	return 0
+}
+
+// RunSkillTrustCheck scans one Markdown path.
+func RunSkillTrustCheck(path string, stdout, stderr io.Writer) int {
+	result, err := ScanSkillTrust(path)
+	if err != nil {
+		fmt.Fprintf(stderr, "skill-trust: %v\n", err)
+		return 2
+	}
+	fmt.Fprint(stdout, FormatSkillTrust(result))
+	if SkillTrustBlocks(result.Findings) {
+		return 3
+	}
+	return 0
+}
+
+// RunObserveSummary emits JSON for one slug.
+func RunObserveSummary(root, slug string, stdout, stderr io.Writer) int {
+	if err := WriteObserveSummaryJSON(root, slug, stdout); err != nil {
+		fmt.Fprintf(stderr, "observe: %v\n", err)
+		return 2
+	}
+	return 0
+}
+
+// ActiveSlug resolves slug from args or ACTIVE pointer.
+func ActiveSlug(root string, args []string) (string, int, error) {
+	if len(args) == 1 {
+		return args[0], 0, nil
+	}
+	if len(args) != 0 {
+		return "", 2, fmt.Errorf("expected one slug argument")
+	}
+	slug, err := devritespaths.ActiveSlug(root)
+	if err != nil {
+		return "", 2, err
+	}
+	if slug == "" {
+		return "", 2, fmt.Errorf("no slug and ACTIVE is empty")
+	}
+	return slug, 0, nil
+}

package/engine/internal/lib/observe_summary.go

@@ -0,0 +1,79 @@
+package lib
+
+import (
+	"encoding/json"
+	"io"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+// 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"`
+}
+
+// ObserveSummaryFor builds a summary for one feature slug.
+func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
+	report, err := state.Status(root, slug)
+	if err != nil {
+		return ObserveSummary{}, err
+	}
+	summary := ObserveSummary{
+		Slug:              report.Slug,
+		Phase:             string(report.Phase),
+		Status:            report.Status,
+		NextAction:        report.NextAction,
+		PrinciplesPresent: report.PrinciplesPresent,
+		MissingFiles:      append([]string(nil), report.MissingFiles...),
+		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"`
+		}{
+			SliceCount: len(graph.Slices),
+			Cycle:      graph.Cycle,
+			Unknown:    graph.Unknown,
+			OK:         len(graph.Problems) == 0,
+		}
+	}
+	return summary, nil
+}
+
+func missingSectionNames(sections []state.Section) []string {
+	if len(sections) == 0 {
+		return nil
+	}
+	out := make([]string, len(sections))
+	for i, section := range sections {
+		out[i] = string(section)
+	}
+	return out
+}
+
+// WriteObserveSummaryJSON prints one JSON object to stdout.
+func WriteObserveSummaryJSON(root, slug string, stdout io.Writer) error {
+	summary, err := ObserveSummaryFor(root, slug)
+	if err != nil {
+		return err
+	}
+	enc := json.NewEncoder(stdout)
+	enc.SetIndent("", "  ")
+	return enc.Encode(summary)
+}

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