devrites 3.0.3 → 3.0.5

package/engine/tests/migrate_cli_test.go

@@ -58,25 +58,26 @@ func TestMigrateNormalizesCanonicalWorkSchema(t *testing.T) {
 	}
 
 	feat := filepath.Join(root, "work", slug)
-	// evidence.md → proof.md, state.md → status.md, plus a generated feature.md.
-	for _, want := range []string{"feature.md", "spec.md", "plan.md", "decisions.md", "tasks.md", "proof.md", "status.md"} {
+	// Current canonical files stay canonical; migration adds only the missing map.
+	for _, want := range []string{"README.md", "state.md", "spec.md", "plan.md", "decisions.md", "tasks.md", "evidence.md"} {
 		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
 			t.Errorf("missing new-schema file %s: %v", want, err)
 		}
 	}
-	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	readme, err := os.ReadFile(filepath.Join(feat, "README.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(fm), "phase: temper") {
-		t.Errorf("feature.md phase not derived from state.md\n%s", fm)
+	if !strings.Contains(string(readme), "phase: temper") {
+		t.Errorf("README.md phase not derived from state.md\n%s", readme)
 	}
-	if !strings.Contains(string(fm), "schemaVersion: 1") {
-		t.Errorf("feature.md missing schemaVersion\n%s", fm)
+	if !strings.Contains(string(readme), "schemaVersion: 1") {
+		t.Errorf("README.md missing schemaVersion\n%s", readme)
 	}
-	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
-	if !strings.Contains(string(proof), "Tests green") {
-		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	for _, unwanted := range []string{"feature.md", "proof.md", "status.md"} {
+		if _, err := os.Stat(filepath.Join(feat, unwanted)); !os.IsNotExist(err) {
+			t.Errorf("migration created legacy alias %s: %v", unwanted, err)
+		}
 	}
 
 	// A backup of the pre-migration state must exist.
@@ -127,11 +128,12 @@ func TestMigrateNormalizesLiveFeatureInPlace(t *testing.T) {
 		t.Fatal(err)
 	}
 	files := map[string]string{
-		"state.md":     "# State\n\n- Phase: prove\n- Status: running\n",
+		"feature.md":   "# Legacy feature map\n",
+		"status.md":    "# State\n\n- Phase: prove\n- Status: running\n",
 		"spec.md":      "# Spec\n\nRotate tokens.\n",
 		"plan.md":      "# Plan\n\nStep 1, step 2.\n",
 		"tasks.md":     "# Tasks\n\n- [x] one\n",
-		"evidence.md":  "# Evidence\n\nTests green.\n",
+		"proof.md":     "# Evidence\n\nTests green.\n",
 		"decisions.md": "# Decisions\n\nUse HMAC.\n",
 	}
 	for name, body := range files {
@@ -147,25 +149,25 @@ func TestMigrateNormalizesLiveFeatureInPlace(t *testing.T) {
 	if !strings.Contains(out, "migrated 1 feature(s)") {
 		t.Errorf("unexpected migrate output\n%s", out)
 	}
-	for _, want := range []string{"feature.md", "proof.md", "status.md", "state.md", "evidence.md"} {
+	for _, want := range []string{"README.md", "feature.md", "proof.md", "status.md", "state.md", "evidence.md"} {
 		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
 			t.Errorf("missing normalized file %s: %v", want, err)
 		}
 	}
-	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	readme, err := os.ReadFile(filepath.Join(feat, "README.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(fm), "phase: prove") {
-		t.Errorf("feature.md phase not derived from ledger\n%s", fm)
+	if !strings.Contains(string(readme), "Legacy feature map") {
+		t.Errorf("README.md did not carry feature.md content\n%s", readme)
 	}
-	status, _ := os.ReadFile(filepath.Join(feat, "status.md"))
-	if !strings.Contains(string(status), "running") {
-		t.Errorf("status.md did not carry state.md content\n%s", status)
+	stateFile, _ := os.ReadFile(filepath.Join(feat, "state.md"))
+	if !strings.Contains(string(stateFile), "running") {
+		t.Errorf("state.md did not carry status.md content\n%s", stateFile)
 	}
-	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
-	if !strings.Contains(string(proof), "Tests green") {
-		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	evidence, _ := os.ReadFile(filepath.Join(feat, "evidence.md"))
+	if !strings.Contains(string(evidence), "Tests green") {
+		t.Errorf("evidence.md did not carry proof.md content\n%s", evidence)
 	}
 	if got := backupDirs(t, root); len(got) != 1 {
 		t.Errorf("want exactly one backup dir, got %v", got)

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

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

@@ -19,14 +19,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
 
 # 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):**
 
@@ -88,7 +87,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/codex/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/codex/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/codex/skills/rite/SKILL.md

@@ -82,12 +82,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) ·
@@ -118,9 +116,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/codex/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/codex/skills/rite-adopt/SKILL.md

@@ -91,9 +91,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",
@@ -54,6 +54,7 @@
     "test:fast": "node scripts/run-tests.mjs --fast",
     "test:parallel": "node scripts/run-tests.mjs",
     "test:serial": "node scripts/run-tests.mjs --serial",
+    "audit": "npm audit --audit-level=moderate",
     "size:baseline": "node scripts/check-instruction-size-baseline.mjs --write",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run --no-ci"

package/scripts/skills-inventory.mjs

@@ -7,6 +7,7 @@ const root = new URL('..', import.meta.url).pathname.replace(/\/$/, '');
 const skillsDir = join(root, 'pack', '.claude', 'skills');
 const docsSkills = join(root, 'docs', 'skills.md');
 const docsCommandMap = join(root, 'docs', 'command-map.md');
+const docsFlow = join(root, 'docs', 'flow.md');
 const readme = join(root, 'README.md');
 const arch = join(root, 'docs', 'architecture.md');
 
@@ -82,6 +83,17 @@ function assertPublicSkillLinks(path, label) {
   }
 }
 
+function assertPublicSkillMentions(path, label) {
+  const text = readFileSync(path, 'utf8');
+  for (const skill of skills.filter((s) => s.invocable === 'true')) {
+    const escaped = skill.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const token = new RegExp(`(^|[^a-z0-9-])${escaped}([^a-z0-9-]|$)`, 'im');
+    if (!token.test(text)) {
+      fail(`${relative(root, path)}: missing ${label} entry for ${skill.name}`);
+    }
+  }
+}
+
 assertDocContains(docsSkills, `# All ${total} skills`, 'total skill heading');
 assertDocContains(docsSkills, `**${total} skills total**`, 'total skill prose');
 assertDocContains(docsSkills, `${publicRiteCount} user-invocable \`rite-*\``, 'public rite-* count');
@@ -90,9 +102,15 @@ assertDocContains(docsSkills, 'npx devrites', 'npx distribution contract');
 assertDocContains(docsCommandMap, 'npx devrites', 'npx distribution contract');
 assertDocContains(readme, `**${total} skills total**`, 'README total skill prose');
 assertDocContains(readme, `# skills/  ${total} skills`, 'README layout total count');
+assertDocContains(readme, `— ${publicCount} public + ${internalCount} internal`, 'README public/internal count');
 assertDocContains(arch, `${publicRiteCount} public \`rite-*\` skills (${total} total)`, 'architecture surface count');
+assertDocContains(docsFlow, `— ${publicCount} skills`, 'flow public count');
+assertDocContains(docsFlow, `— ${internalCount} skills`, 'flow internal count');
 assertPublicSkillLinks(docsSkills, 'skills catalogue');
 assertPublicSkillLinks(docsCommandMap, 'command map');
+assertPublicSkillMentions(readme, 'README catalogue');
+assertPublicSkillMentions(docsFlow, 'flow namespace');
+assertPublicSkillMentions(arch, 'architecture surface');
 
 console.log(`skills total: ${total}`);
 console.log(`public skills: ${publicCount}`);