devrites 3.0.4 → 3.0.5

package/engine/internal/lib/packageexistence_test.go

@@ -0,0 +1,343 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestPackageExistenceJavaScriptWorkspaces(t *testing.T) {
+	tests := []struct {
+		name        string
+		sourcePath  string
+		workingDir  string
+		importLine  string
+		files       map[string]string
+		wantCode    int
+		wantFinding string
+	}{
+		{
+			name:       "nested workspace",
+			sourcePath: "frontend/src/example.ts",
+			workingDir: "frontend",
+			importLine: `import { Dialog } from "@ark-ui/svelte/dialog";`,
+			files: map[string]string{
+				"frontend/package.json": `{"dependencies":{"@ark-ui/svelte":"^5.22.1"}}`,
+			},
+		},
+		{
+			name:       "scoped package subpath",
+			sourcePath: "app/src/example.ts",
+			importLine: `import value from "@scope/package/subpath";`,
+			files: map[string]string{
+				"app/package.json": `{"devDependencies":{"@scope/package":"1.0.0"}}`,
+			},
+		},
+		{
+			name:       "wildcard alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import Button from "$lib/components/button";`,
+			files: map[string]string{
+				"frontend/package.json":              `{}`,
+				"frontend/tsconfig.json":             "{\n  // SvelteKit generates the inherited aliases.\n  \"extends\": \"./.svelte-kit/tsconfig.json\"\n}",
+				"frontend/.svelte-kit/tsconfig.json": `{"compilerOptions":{"paths":{"$lib/*":["../src/lib/*"]}}}`,
+			},
+		},
+		{
+			name:       "exact alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import library from "$lib";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/tsconfig.json": `{"compilerOptions":{"paths":{"$lib":["./src/lib"]}}}`,
+			},
+		},
+		{
+			name:       "package shaped alias",
+			sourcePath: "frontend/src/example.svelte",
+			importLine: `import { css } from "styled-system/css";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/jsconfig.json": `{"compilerOptions":{"paths":{"styled-system/*":["./styled-system/*"]}}}`,
+			},
+		},
+		{
+			name:        "undeclared dependency",
+			sourcePath:  "frontend/src/example.ts",
+			importLine:  `import missing from "definitely-missing-package";`,
+			files:       map[string]string{"frontend/package.json": `{}`},
+			wantCode:    3,
+			wantFinding: "definitely-missing-package",
+		},
+		{
+			name:       "sibling isolation",
+			sourcePath: "workspace-a/src/example.ts",
+			importLine: `import sibling from "sibling-only-package";`,
+			files: map[string]string{
+				"workspace-a/package.json": `{}`,
+				"workspace-b/package.json": `{"dependencies":{"sibling-only-package":"1.0.0"}}`,
+			},
+			wantCode:    3,
+			wantFinding: "sibling-only-package",
+		},
+		{
+			name:       "malformed config does not allow alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import { css } from "styled-system/css";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/tsconfig.json": `{"compilerOptions":{"paths":{"styled-system/*":["./styled-system/*"]}}`,
+			},
+			wantCode:    3,
+			wantFinding: "styled-system",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			repo := t.TempDir()
+			writePackageExistenceFile(t, repo, "Cargo.toml", "[package]\nname = \"fixture\"\nversion = \"0.1.0\"\n")
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n")
+			for path, content := range test.files {
+				writePackageExistenceFile(t, repo, path, content+"\n")
+			}
+			gitPackageExistence(t, repo, "init", "-q")
+			gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+			gitPackageExistence(t, repo, "config", "user.name", "Test")
+			gitPackageExistence(t, repo, "add", ".")
+			gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+			if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n"+test.importLine+"\n")
+			t.Chdir(filepath.Join(repo, test.workingDir))
+
+			var stdout, stderr bytes.Buffer
+			gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+			if gotCode != test.wantCode {
+				t.Fatalf("code = %d, want %d\nstdout: %s\nstderr: %s", gotCode, test.wantCode, stdout.String(), stderr.String())
+			}
+			if test.wantFinding != "" && !strings.Contains(stderr.String(), test.wantFinding) {
+				t.Fatalf("stderr does not name %q: %s", test.wantFinding, stderr.String())
+			}
+		})
+	}
+}
+
+func TestPackageExistenceNonJavaScriptWorkspaces(t *testing.T) {
+	tests := []struct {
+		name        string
+		sourcePath  string
+		addedSource string
+		files       map[string]string
+		wantCode    int
+		wantFinding string
+	}{
+		{
+			name:        "go import block rejects undeclared module",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport (\n\t\"definitely.invalid/missing\"\n)\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+			wantCode:    3,
+			wantFinding: "definitely.invalid/missing",
+		},
+		{
+			name:        "go modules do not collide by hostname",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"github.com/evil/missing\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n\nrequire github.com/good/pkg v1.0.0\n"},
+			wantCode:    3,
+			wantFinding: "github.com/evil/missing",
+		},
+		{
+			name:        "nested go module declaration",
+			sourcePath:  "backend/main.go",
+			addedSource: "package main\n\nimport \"github.com/good/pkg/sub\"\n",
+			files: map[string]string{
+				"Cargo.toml":     "[package]\nname = \"root\"\nversion = \"0.1.0\"\n",
+				"backend/go.mod": "module example.com/backend\n\ngo 1.26\n\nrequire github.com/good/pkg v1.0.0\n",
+			},
+		},
+		{
+			name:        "go standard library subpackage",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"encoding/json\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+		},
+		{
+			name:        "go standard library typo remains undeclared",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"encoding/josn\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+			wantCode:    3,
+			wantFinding: "encoding/josn",
+		},
+		{
+			name:        "malformed go manifest does not declare import",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"github.com/missing/pkg\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n\nrequire (\n  github.com/missing/pkg v1.0.0\n"},
+			wantCode:    3,
+			wantFinding: "github.com/missing/pkg",
+		},
+		{
+			name:        "rust rejects undeclared crate",
+			sourcePath:  "src/main.rs",
+			addedSource: "use definitely_missing_crate::Thing;\n",
+			files:       map[string]string{"Cargo.toml": "[package]\nname = \"fixture\"\nversion = \"0.1.0\"\n\n[dependencies]\n"},
+			wantCode:    3,
+			wantFinding: "definitely_missing_crate",
+		},
+		{
+			name:        "nested rust dependency and hyphen normalization",
+			sourcePath:  "crates/app/src/main.rs",
+			addedSource: "use serde_json::Value;\n",
+			files: map[string]string{
+				"Cargo.toml":            "[workspace]\nmembers = [\"crates/app\"]\n",
+				"crates/app/Cargo.toml": "[package]\nname = \"app\"\nversion = \"0.1.0\"\n\n[dependencies.serde-json]\nversion = \"1\"\n",
+			},
+		},
+		{
+			name:        "python dotted import uses top-level module",
+			sourcePath:  "app.py",
+			addedSource: "from requests.sessions import Session\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+		},
+		{
+			name:        "python standard library module",
+			sourcePath:  "app.py",
+			addedSource: "import asyncio\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+		},
+		{
+			name:        "nested python manifest declaration",
+			sourcePath:  "backend/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"Cargo.toml":               "[package]\nname = \"root\"\nversion = \"0.1.0\"\n",
+				"backend/requirements.txt": "requests==2.32.0\n",
+			},
+		},
+		{
+			name:        "pyproject dependency declaration",
+			sourcePath:  "service/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"service/pyproject.toml": "[project]\ndependencies = [\n  \"requests[socks]>=2.32\",\n]\n",
+			},
+		},
+		{
+			name:        "pipfile dependency declaration",
+			sourcePath:  "service/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"service/Pipfile": "[packages]\nrequests = \"*\"\n",
+			},
+		},
+		{
+			name:        "malformed pyproject does not declare import",
+			sourcePath:  "service/app.py",
+			addedSource: "import definitely_missing\n",
+			files: map[string]string{
+				"service/pyproject.toml": "[project]\ndependencies = [\n  \"definitely_missing\"\n",
+			},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+		{
+			name:        "python multiple imports reject undeclared module",
+			sourcePath:  "app.py",
+			addedSource: "import requests, definitely_missing\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+		{
+			name:        "comments and other ecosystems do not declare python imports",
+			sourcePath:  "app.py",
+			addedSource: "import definitely_missing\n",
+			files: map[string]string{
+				"Cargo.toml":       "[package]\nname = \"definitely_missing\"\nversion = \"0.1.0\"\n",
+				"requirements.txt": "# definitely_missing is intentionally absent\n",
+			},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			repo := t.TempDir()
+			for path, content := range test.files {
+				writePackageExistenceFile(t, repo, path, content)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n")
+			gitPackageExistence(t, repo, "init", "-q")
+			gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+			gitPackageExistence(t, repo, "config", "user.name", "Test")
+			gitPackageExistence(t, repo, "add", ".")
+			gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+			if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, test.addedSource)
+			t.Chdir(repo)
+
+			var stdout, stderr bytes.Buffer
+			gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+			if gotCode != test.wantCode {
+				t.Fatalf("code = %d, want %d\nstdout: %s\nstderr: %s", gotCode, test.wantCode, stdout.String(), stderr.String())
+			}
+			if test.wantFinding != "" && !strings.Contains(stderr.String(), test.wantFinding) {
+				t.Fatalf("stderr does not name %q: %s", test.wantFinding, stderr.String())
+			}
+		})
+	}
+}
+
+func TestPackageExistenceGenericResolverFailsClosed(t *testing.T) {
+	repo := t.TempDir()
+	writePackageExistenceFile(t, repo, "package.json", `{"dependencies":{"definitely-missing-package":"1.0.0"}}`)
+	writePackageExistenceFile(t, repo, "src/example.custom", "// baseline\n")
+	gitPackageExistence(t, repo, "init", "-q")
+	gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+	gitPackageExistence(t, repo, "config", "user.name", "Test")
+	gitPackageExistence(t, repo, "add", ".")
+	gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+	if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writePackageExistenceFile(t, repo, "src/example.custom", "import \"definitely-missing-package\"\n")
+	t.Chdir(repo)
+
+	var stdout, stderr bytes.Buffer
+	gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+	if gotCode != 3 {
+		t.Fatalf("code = %d, want 3\nstdout: %s\nstderr: %s", gotCode, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "definitely-missing-package") {
+		t.Fatalf("stderr does not name unresolved import: %s", stderr.String())
+	}
+}
+
+func writePackageExistenceFile(t *testing.T, root, path, content string) {
+	t.Helper()
+	fullPath := filepath.Join(root, filepath.FromSlash(path))
+	if err := os.MkdirAll(filepath.Dir(fullPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(fullPath, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func gitPackageExistence(t *testing.T, root string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", root}, args...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+}

package/engine/internal/lib/util.go

@@ -14,7 +14,7 @@ func gitToplevel(dir string) string {
 	if err != nil {
 		return ""
 	}
-	return strings.TrimSpace(string(out))
+	return filepath.Clean(strings.TrimSpace(string(out)))
 }
 
 // gitDiffNames lists the paths that differ, relative to gitRoot. With one ref it

package/pack/.claude/skills/devrites-lib/SKILL.md

@@ -7,14 +7,13 @@ disable-model-invocation: true
 
 # devrites-lib — internal shared helpers (not a command)
 
-This is **not** a skill you run. It is the manifest for DevRites'
-cross-cutting helper operations, each exposed as a subcommand of the global
-`devrites` binary. A skill invokes one as `devrites <op>` — the same call from
-any workspace, with no install layout or script path to resolve.
+This is **not** a skill you run. It is DevRites' manifest for shared references
+and control-plane operations. Skills call `devrites-engine <command>` from any
+workspace; no pack script path is required.
 
 ## Operations
 
-Each is a subcommand of the global `devrites` binary, run as `devrites <op>`.
+These are selected `devrites-engine` contracts; `devrites-engine help` is exhaustive.
 
 **Read-only — orient / gate (never mutate the workspace):**
 
@@ -76,7 +75,6 @@ devrites-engine progress
 
 **Unified entrypoint (tool-agnostic):**
 
-- The `devrites` binary is that unified CLI, dispatching to all of the above (`orient` / `ready` /
-  `evidence-fresh` / `acceptance` / `spec-validate` / `tick-afk` / `resolve` / `close` /
-  `active` / `list` / `use`), so any agent or human can drive `.devrites/` without the skill
-  prose. See [`docs/cli.md`](../../../../docs/cli.md).
+- `devrites-engine` is the shared CLI for agents, CI, and humans. The npm
+  `devrites` shim acquires it, owns install/update/uninstall bootstrap, and
+  proxies other commands.

package/pack/.claude/skills/devrites-lib/reference/reply-contract.md

@@ -59,9 +59,17 @@ Rules:
 
 ```text
 Awaiting human: <qid> · <gate> · <slice/phase>
-Question: <one-line question>
-Recommended: <option 1 + short reason>
-Options: <2-4 compact choices, if already generated>
+
+Question
+  <question>
+
+Recommended
+  1. <option 1 + short reason>
+
+Other options
+  2. <option 2>
+  3. <option 3 if any>
+
 Resume: /rite-resolve <qid> "<answer>"
 Record: .devrites/work/<slug>/questions.md
 ↻ Hygiene: no /clear until the answer is persisted

package/pack/.claude/skills/devrites-lib/reference/standards/development-workflow.md

@@ -1,8 +1,7 @@
 # Development workflow
 
-Ship small, integrate often, keep the main branch releasable. This is the general
-engineering loop the DevRites feature lifecycle (spec → define → build → prove → polish →
-review → seal → ship) runs on top of.
+Ship small, integrate often, keep the main branch releasable. DevRites runs this
+lifecycle atop that loop: spec → define → vet → build → prove → polish → review → seal → ship.
 
 ## Work in small batches
 - Break work into thin, independently shippable slices and integrate them frequently —

package/pack/.claude/skills/rite/SKILL.md

@@ -70,12 +70,10 @@ Both forms hit the same skill — the menu form for discovery, the `/rite-<verb>
 the now-active feature. It is cheap context-switching only — no re-spec, no phase run. If
 the workspace is missing, list the slugs under `.devrites/work/` and stop.
 
-`guide` is also inline — a first-feature walkthrough that teaches the lifecycle by running
-it. Agree on one **real, genuinely small** change, then dispatch the normal phases in order
-(spec → define → build → prove → seal → ship). Per phase, exactly two narration beats:
-before, what it will decide; after, what it wrote in `.devrites/work/<slug>/` and why. Walk
-every phase — the small change is what makes the full ceremony affordable to watch. Pause
-at each boundary for the user's go-ahead. Teach without lecturing.
+`guide` is an inline first-feature walkthrough. Agree on one **real, genuinely small**
+change, then run spec → temper → define → vet → build → prove → polish → review → seal →
+ship. Before each phase, say what it decides; after, name what it wrote and why. Pause at
+every boundary. Teach without lecturing.
 
 Specialist triggers (model-invoked inside the above):
 `devrites-frontend-craft` (UI) · `devrites-browser-proof` (UI verify) ·
@@ -106,9 +104,10 @@ SPEC          /rite spec               ≡    /rite-spec        investigate deep
 ADOPT         /rite adopt              ≡    /rite-adopt       onboard existing code → reverse-derive spec.md + seed conventions
 TEMPER        /rite temper             ≡    /rite-temper      optional — strategic review: scope mode + pre-mortem, harden the spec
 PLAN          /rite define             ≡    /rite-define      turn the spec into plan + task slices + state
-VET           /rite vet                ≡    /rite-vet         optional — engineering plan review: scope · architecture · tests · perf, harden the plan
+VET           /rite vet                ≡    /rite-vet         mandatory every plan — light/full engineering review by stakes
 REPLAN        /rite plan               ≡    /rite-plan        decompose / reslice / repair an active plan
 BUILD         /rite build              ≡    /rite-build       implement exactly one verified vertical slice, then stop
+CONVERGE      /rite converge           ≡    /rite-converge    recovery — append work needed to meet intent
 PROVE         /rite prove              ≡    /rite-prove       tests + build + runtime + browser evidence
 POLISH        /rite polish             ≡    /rite-polish      code polish always; UI normalize + polish if UI
 REVIEW        /rite review             ≡    /rite-review      feature-scoped multi-axis review

package/pack/.claude/skills/rite/reference/menu.md

@@ -7,11 +7,11 @@ what each command does or how phases connect.
 
 | Phase | Command | Use when |
 |---|---|---|
-| Spec | `/rite-spec <feature>` | **Start here.** Investigate deeply → write spec.md. Asks you with options; gathers any design references you attach (optional). |
+| Spec | `/rite-spec <feature>` | **New feature.** Investigate deeply → write spec.md. Asks with options; gathers attached design references (optional). |
 | Adopt | `/rite-adopt` | Onboard an existing codebase instead of starting fresh — reverse-derive spec.md + seed the conventions ledger. |
 | Temper | `/rite-temper` | _Optional, before define._ Strategic review of the spec — scope mode (expand/selective/hold-rigor/reduce) + pre-mortem; hardens the spec. Best on big/risky features; mandatory in `/rite-autocomplete`. |
 | Plan | `/rite-define` | Turn the approved spec into plan + vertical task slices + state. |
-| Vet | `/rite-vet` | _Optional, before build._ Engineering review of the plan — scope · architecture · tests · perf; hardens the plan. Best on big/risky features; mandatory in `/rite-autocomplete`. |
+| Vet | `/rite-vet` | _Required before build._ Review every plan — scope · architecture · tests · perf; light for simple/reversible, full for high stakes. |
 | Re-plan | `/rite-plan` | The active plan is too big, wrong, stale, ambiguous, or blocked. |
 | Build | `/rite-build` | Implement the next single vertical slice. Stops after one slice. |
 | Converge | `/rite-converge` | _Recovery._ Code drifted from / falls short of intent (resumed cold, adopted, stalled build) — assess live code vs spec/plan/tasks and append the remaining work as new slices for `/rite-build`. |
@@ -27,10 +27,10 @@ what each command does or how phases connect.
 ## Typical orderings
 
 - **Every feature**: `/rite-spec` (spec) → *(big feature? `/rite-temper` — strategic review)* →
-  `/rite-define` (plan) → *(big feature? `/rite-vet` — engineering review)* →
+  `/rite-define` (plan) → `/rite-vet` (engineering review; light or full) →
   `/rite-build` ×N (all slices) → `/rite-prove` (once all built) →
   `/rite-polish` (always: code + UI if UI) → `/rite-review` → `/rite-seal` → `/rite-ship`.
-- **Existing codebase**: `/rite-adopt` (onboard → spec.md + conventions) → continue at `/rite-define`.
+- **Existing codebase**: `/rite-adopt` → `/rite-define` → `/rite-vet` → build.
 - **Drift mid-build**: stop → drift question → `/rite-plan` (repair) → resume build.
 - **Resumed / adopted / stalled**: `/rite-converge` (assess live code vs intent → append the
   remaining slices) → `/rite-build` ×N → continue at `/rite-prove`.
@@ -38,5 +38,5 @@ what each command does or how phases connect.
 ## Rules this menu obeys
 
 - `/rite` never edits code or runs a phase workflow.
-- It reads `.devrites/ACTIVE` and `state.md` for status only.
+- Menu mode runs `devrites-engine first-task`; `/rite-status` owns workspace status.
 - It suggests; the user (or Claude, when appropriate) invokes the real skill.

package/pack/.claude/skills/rite-adopt/SKILL.md

@@ -79,9 +79,8 @@ upholds invariants worth proposing as project principles (step 4a).
    ([`principles.md`](../devrites-lib/reference/standards/principles.md)). Propose, don't impose — an unratified candidate
    stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common — a
    fresh adopt may declare zero principles, and that's valid).
-5. **Hand off.** The project is now in the lifecycle with a spec and a head-start ledger.
-   Point the user at `/rite-temper` (big/risky) or `/rite-define` (straightforward) — do not
-   plan or build here.
+5. **Hand off.** Spec and ledger are ready. Next: `/rite-temper` if big/risky,
+   else `/rite-define`; every plan then runs `/rite-vet` before build. Do not plan/build here.
    **Completion:** one next rite is reported and no plan or application code was written.
 
 > **Mid-flight discipline.** Don't invent conventions the code doesn't actually follow, don't

package/pack/generated/claude/skills/devrites-lib/SKILL.md

@@ -7,14 +7,13 @@ disable-model-invocation: true
 
 # devrites-lib — internal shared helpers (not a command)
 
-This is **not** a skill you run. It is the manifest for DevRites'
-cross-cutting helper operations, each exposed as a subcommand of the global
-`devrites` binary. A skill invokes one as `devrites <op>` — the same call from
-any workspace, with no install layout or script path to resolve.
+This is **not** a skill you run. It is DevRites' manifest for shared references
+and control-plane operations. Skills call `devrites-engine <command>` from any
+workspace; no pack script path is required.
 
 ## Operations
 
-Each is a subcommand of the global `devrites` binary, run as `devrites <op>`.
+These are selected `devrites-engine` contracts; `devrites-engine help` is exhaustive.
 
 **Read-only — orient / gate (never mutate the workspace):**
 
@@ -76,7 +75,6 @@ devrites-engine progress
 
 **Unified entrypoint (tool-agnostic):**
 
-- The `devrites` binary is that unified CLI, dispatching to all of the above (`orient` / `ready` /
-  `evidence-fresh` / `acceptance` / `spec-validate` / `tick-afk` / `resolve` / `close` /
-  `active` / `list` / `use`), so any agent or human can drive `.devrites/` without the skill
-  prose. See [`docs/cli.md`](../../../../docs/cli.md).
+- `devrites-engine` is the shared CLI for agents, CI, and humans. The npm
+  `devrites` shim acquires it, owns install/update/uninstall bootstrap, and
+  proxies other commands.

package/pack/generated/claude/skills/devrites-lib/reference/reply-contract.md

@@ -59,9 +59,17 @@ Rules:
 
 ```text
 Awaiting human: <qid> · <gate> · <slice/phase>
-Question: <one-line question>
-Recommended: <option 1 + short reason>
-Options: <2-4 compact choices, if already generated>
+
+Question
+  <question>
+
+Recommended
+  1. <option 1 + short reason>
+
+Other options
+  2. <option 2>
+  3. <option 3 if any>
+
 Resume: /rite-resolve <qid> "<answer>"
 Record: .devrites/work/<slug>/questions.md
 ↻ Hygiene: no /clear until the answer is persisted

package/pack/generated/claude/skills/devrites-lib/reference/standards/development-workflow.md

@@ -1,8 +1,7 @@
 # Development workflow
 
-Ship small, integrate often, keep the main branch releasable. This is the general
-engineering loop the DevRites feature lifecycle (spec → define → build → prove → polish →
-review → seal → ship) runs on top of.
+Ship small, integrate often, keep the main branch releasable. DevRites runs this
+lifecycle atop that loop: spec → define → vet → build → prove → polish → review → seal → ship.
 
 ## Work in small batches
 - Break work into thin, independently shippable slices and integrate them frequently —

package/pack/generated/claude/skills/rite/SKILL.md

@@ -70,12 +70,10 @@ Both forms hit the same skill — the menu form for discovery, the `/rite-<verb>
 the now-active feature. It is cheap context-switching only — no re-spec, no phase run. If
 the workspace is missing, list the slugs under `.devrites/work/` and stop.
 
-`guide` is also inline — a first-feature walkthrough that teaches the lifecycle by running
-it. Agree on one **real, genuinely small** change, then dispatch the normal phases in order
-(spec → define → build → prove → seal → ship). Per phase, exactly two narration beats:
-before, what it will decide; after, what it wrote in `.devrites/work/<slug>/` and why. Walk
-every phase — the small change is what makes the full ceremony affordable to watch. Pause
-at each boundary for the user's go-ahead. Teach without lecturing.
+`guide` is an inline first-feature walkthrough. Agree on one **real, genuinely small**
+change, then run spec → temper → define → vet → build → prove → polish → review → seal →
+ship. Before each phase, say what it decides; after, name what it wrote and why. Pause at
+every boundary. Teach without lecturing.
 
 Specialist triggers (model-invoked inside the above):
 `devrites-frontend-craft` (UI) · `devrites-browser-proof` (UI verify) ·
@@ -106,9 +104,10 @@ SPEC          /rite spec               ≡    /rite-spec        investigate deep
 ADOPT         /rite adopt              ≡    /rite-adopt       onboard existing code → reverse-derive spec.md + seed conventions
 TEMPER        /rite temper             ≡    /rite-temper      optional — strategic review: scope mode + pre-mortem, harden the spec
 PLAN          /rite define             ≡    /rite-define      turn the spec into plan + task slices + state
-VET           /rite vet                ≡    /rite-vet         optional — engineering plan review: scope · architecture · tests · perf, harden the plan
+VET           /rite vet                ≡    /rite-vet         mandatory every plan — light/full engineering review by stakes
 REPLAN        /rite plan               ≡    /rite-plan        decompose / reslice / repair an active plan
 BUILD         /rite build              ≡    /rite-build       implement exactly one verified vertical slice, then stop
+CONVERGE      /rite converge           ≡    /rite-converge    recovery — append work needed to meet intent
 PROVE         /rite prove              ≡    /rite-prove       tests + build + runtime + browser evidence
 POLISH        /rite polish             ≡    /rite-polish      code polish always; UI normalize + polish if UI
 REVIEW        /rite review             ≡    /rite-review      feature-scoped multi-axis review

package/pack/generated/claude/skills/rite/reference/menu.md

@@ -7,11 +7,11 @@ what each command does or how phases connect.
 
 | Phase | Command | Use when |
 |---|---|---|
-| Spec | `/rite-spec <feature>` | **Start here.** Investigate deeply → write spec.md. Asks you with options; gathers any design references you attach (optional). |
+| Spec | `/rite-spec <feature>` | **New feature.** Investigate deeply → write spec.md. Asks with options; gathers attached design references (optional). |
 | Adopt | `/rite-adopt` | Onboard an existing codebase instead of starting fresh — reverse-derive spec.md + seed the conventions ledger. |
 | Temper | `/rite-temper` | _Optional, before define._ Strategic review of the spec — scope mode (expand/selective/hold-rigor/reduce) + pre-mortem; hardens the spec. Best on big/risky features; mandatory in `/rite-autocomplete`. |
 | Plan | `/rite-define` | Turn the approved spec into plan + vertical task slices + state. |
-| Vet | `/rite-vet` | _Optional, before build._ Engineering review of the plan — scope · architecture · tests · perf; hardens the plan. Best on big/risky features; mandatory in `/rite-autocomplete`. |
+| Vet | `/rite-vet` | _Required before build._ Review every plan — scope · architecture · tests · perf; light for simple/reversible, full for high stakes. |
 | Re-plan | `/rite-plan` | The active plan is too big, wrong, stale, ambiguous, or blocked. |
 | Build | `/rite-build` | Implement the next single vertical slice. Stops after one slice. |
 | Converge | `/rite-converge` | _Recovery._ Code drifted from / falls short of intent (resumed cold, adopted, stalled build) — assess live code vs spec/plan/tasks and append the remaining work as new slices for `/rite-build`. |
@@ -27,10 +27,10 @@ what each command does or how phases connect.
 ## Typical orderings
 
 - **Every feature**: `/rite-spec` (spec) → *(big feature? `/rite-temper` — strategic review)* →
-  `/rite-define` (plan) → *(big feature? `/rite-vet` — engineering review)* →
+  `/rite-define` (plan) → `/rite-vet` (engineering review; light or full) →
   `/rite-build` ×N (all slices) → `/rite-prove` (once all built) →
   `/rite-polish` (always: code + UI if UI) → `/rite-review` → `/rite-seal` → `/rite-ship`.
-- **Existing codebase**: `/rite-adopt` (onboard → spec.md + conventions) → continue at `/rite-define`.
+- **Existing codebase**: `/rite-adopt` → `/rite-define` → `/rite-vet` → build.
 - **Drift mid-build**: stop → drift question → `/rite-plan` (repair) → resume build.
 - **Resumed / adopted / stalled**: `/rite-converge` (assess live code vs intent → append the
   remaining slices) → `/rite-build` ×N → continue at `/rite-prove`.
@@ -38,5 +38,5 @@ what each command does or how phases connect.
 ## Rules this menu obeys
 
 - `/rite` never edits code or runs a phase workflow.
-- It reads `.devrites/ACTIVE` and `state.md` for status only.
+- Menu mode runs `devrites-engine first-task`; `/rite-status` owns workspace status.
 - It suggests; the user (or Claude, when appropriate) invokes the real skill.

package/pack/generated/claude/skills/rite-adopt/SKILL.md

@@ -79,9 +79,8 @@ upholds invariants worth proposing as project principles (step 4a).
    ([`principles.md`](../devrites-lib/reference/standards/principles.md)). Propose, don't impose — an unratified candidate
    stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common — a
    fresh adopt may declare zero principles, and that's valid).
-5. **Hand off.** The project is now in the lifecycle with a spec and a head-start ledger.
-   Point the user at `/rite-temper` (big/risky) or `/rite-define` (straightforward) — do not
-   plan or build here.
+5. **Hand off.** Spec and ledger are ready. Next: `/rite-temper` if big/risky,
+   else `/rite-define`; every plan then runs `/rite-vet` before build. Do not plan/build here.
    **Completion:** one next rite is reported and no plan or application code was written.
 
 > **Mid-flight discipline.** Don't invent conventions the code doesn't actually follow, don't