devrites 3.0.4 → 3.0.6

package/docs/usage.md

@@ -1,9 +1,10 @@
-# DevRites — usage
+# Using DevRites
 
-Worked workflows. Every feature starts with `/rite-spec` (it investigates,
-writes the spec, and creates the workspace). Every later phase reads the
-active workspace (`.devrites/ACTIVE` → `.devrites/work/<slug>/`) first; if
-none exists it tells you to run `/rite-spec <feature>`.
+These examples show the common DevRites workflows. A greenfield feature starts
+with `/rite-spec`; an existing codebase may enter through `/rite-adopt`.
+`/rite-quick` and `/rite-frame` handle bounded work outside the full feature arc.
+Workspace-operating phases read the active workspace (`.devrites/ACTIVE` →
+`.devrites/work/<slug>/`) first and report the appropriate on-ramp when none exists.
 
 - **Full command reference** → [`command-map.md`](command-map.md)
 - **Flow diagrams** → [`flow.md`](flow.md)
@@ -12,9 +13,10 @@ none exists it tells you to run `/rite-spec <feature>`.
 
 ## The workspace
 
-`/rite-spec` creates `.devrites/work/<slug>/` and writes the spec;
-`/rite-define` adds architecture, the plan, tasks, and traceability. All human-readable Markdown that
-survives compaction and new sessions:
+`/rite-spec` creates `.devrites/work/<slug>/` and writes the spec.
+`/rite-define` adds the architecture, plan, tasks, and traceability. Together,
+these human-readable Markdown files carry the work across compaction and new
+sessions:
 
 | File | Created by | Holds |
 |---|---|---|
@@ -23,16 +25,16 @@ survives compaction and new sessions:
 | `spec.md` | `/rite-spec` | product WHAT/WHY, requirements, acceptance, boundaries, measurable success |
 | `architecture.md` | `/rite-define` | owning module/layer, integration points, data/API/events, dependencies, risks |
 | `flows.md` | `/rite-spec` or `/rite-define` | optional Mermaid diagrams when sequence/state/data flow clarifies behavior |
-| `references/` + `references.md` | `/rite-spec` | saved design refs — screenshots, Figma, video, links |
+| `references/` + `references.md` | `/rite-spec` | saved design refs: screenshots, Figma, video, links |
 | `strategy.md` | `/rite-temper` | strategic spec review (optional): scope mode, pre-mortem, dimension scores |
 | `plan.md` | `/rite-define` | approach, dependency graph, checkpoints, rollback |
 | `tasks.md` | `/rite-define` | ordered `SLICE-###` vertical slices, each mapped to `AC-###` and tagged `Mode: AFK \| HITL` + gate fields |
 | `traceability.md` | `/rite-define` | AC/REQ → slices → tests/proofs → evidence → touched files matrix |
-| `eng-review.md` | `/rite-vet` | engineering plan review (optional): scope challenge, axis findings, failure modes, parallelization |
+| `eng-review.md` | `/rite-vet` | mandatory engineering plan review, light or full by stakes: scope challenge, axis findings, failure modes, parallelization |
 | `test-plan.md` | `/rite-vet` | build-readable coverage target: coverage diagram, per-gap test requirements, acceptance→test map (read by `/rite-build` + `/rite-prove`) |
-| `status.md` | every phase | canonical status checkpoint |
 | `state.md` | every phase | working ledger: phase, active slice + slice mode, risk, next step; plus `Awaiting human` block when paused (run mode is derived from `.devrites/AFK`, not stored here) |
-| `questions.md` | every phase | append-only Q&A — qid, slice, gate, status (`open` / `answered` / `dropped`), proposed answer, raised/answered timestamps |
+| `status.md` | every phase | compatibility alias for the canonical `state.md` cursor |
+| `questions.md` | every phase | append-only Q&A: qid, slice, gate, status (`open` / `answered` / `dropped`), proposed answer, raised/answered timestamps |
 | `decisions.md` / `assumptions.md` | every phase | running logs |
 | `drift.md` | Spec Drift Guard | drift events + resolutions |
 | `touched-files.md` | `/rite-build` | what files this feature touched |
@@ -43,17 +45,18 @@ survives compaction and new sessions:
 | `polish-report.md` | `/rite-polish` | Phase 1-4 findings + fixes |
 | `review.md` | `/rite-review` | Spec + Standards axes, severity-labelled findings |
 | `seal.md` | `/rite-seal` | GO/NO-GO verdict + acceptance walk + blockers |
-| `ship.md` | `/rite-ship` | what shipped — commit SHA(s), branch, tag/PR, acceptance summary, follow-ups |
+| `ship.md` | `/rite-ship` | what shipped: commit SHA(s), branch, tag/PR, acceptance summary, follow-ups |
 
-When `/rite-ship` closes the task it **archives** the whole workspace —
-`.devrites/work/<slug>/` → `.devrites/archive/<slug>/` (every `.md` above is
-preserved, never deleted) — and clears `.devrites/ACTIVE`. The audit trail lives
-on under `.devrites/archive/<slug>/`.
+When `/rite-ship` closes the task, it archives the whole workspace from
+`.devrites/work/<slug>/` to `.devrites/archive/<slug>/` and clears
+`.devrites/ACTIVE`. It preserves every Markdown file, so the audit trail remains
+under `.devrites/archive/<slug>/`.
 
 Backward compatibility: older `.devrites/features/<slug>/` workspaces remain
 readable; migration should add the canonical `.devrites/work` shape without
 deleting the old files. `feature.md`/`index.md` can still act as the workspace
-map, and `proof.md` can still act as the proof alias for `evidence.md`.
+map, `status.md` as the cursor alias for `state.md`, and `proof.md` as the proof
+alias for `evidence.md`.
 
 Project-root sentinel (outside the workspace):
 
@@ -65,7 +68,7 @@ Project-root sentinel (outside the workspace):
 The shape of this directory is also documented in
 [`flow.md` § Workspace state model](flow.md#7-workspace-state-model).
 
-## 1) Start a feature — spec then plan
+## 1) Start a feature: spec then plan
 
 ```text
 You: I want some kind of reporting thing for admins.
@@ -82,13 +85,18 @@ You: I want some kind of reporting thing for admins.
   → reads the approved spec
   → writes plan.md + vertical task slices + state
   → stops for confirmation
+
+/rite-vet
+  → reviews every defined plan; uses a light or full pass based on stakes
+  → writes eng-review.md + test-plan.md before build
 ```
 
-## 2) Normal feature — the build loop
+## 2) Normal feature: the build loop
 
 ```text
 /rite-spec add-csv-export    # investigate → spec.md
 /rite-define                 # spec → plan + vertical slices + state
+/rite-vet                    # mandatory plan review; light or full based on stakes
 /rite-build                  # slice 1 ("export endpoint returns CSV"); stops with evidence
 /rite-build                  # slice 2 ("download button + states"); repeat for each slice
 /rite-prove                  # ONCE all slices built: full tests + browser proof
@@ -98,7 +106,7 @@ You: I want some kind of reporting thing for admins.
 /rite-ship                   # type-GO + irreversible git ladder + close the task (archive + clear ACTIVE)
 ```
 
-`/rite-build` never auto-advances — you decide when the next slice runs.
+`/rite-build` never auto-advances: you decide when the next slice runs.
 `/rite-seal` **decides**; `/rite-ship` **executes + closes**. To run the whole
 sequence unattended, see `/rite-autocomplete` (§11).
 
@@ -139,6 +147,9 @@ You: 2
 /rite-define
   → spec → slices; UI slice marked frontend-craft + browser-proof
 
+/rite-vet
+  → hardens the UI plan + acceptance-to-test coverage before code
+
 /rite-build
   → UI slice → devrites-frontend-craft: register = product surface, **match
     the saved references**, shape the states (default/loading/empty/error/
@@ -160,13 +171,14 @@ You: 2
 ```
 
 If no browser tooling is available, proof is recorded as **pending (manual)**
-with exact steps — the seal then weighs the UI risk.
+with exact steps: the seal then weighs the UI risk.
 
 ## 5) Backend-only feature
 
 ```text
 /rite-spec rate-limit-api    # investigate → spec.md (no UI)
 /rite-define                 # spec → plan + slices
+/rite-vet                    # mandatory plan review; checks architecture, tests, perf
 /rite-build                  # no UI → no frontend craft / browser proof
 /rite-prove                  # targeted tests + build/typecheck; runtime check of the limiter
 /rite-polish                 # reference/code.md only (no UI scope detected)
@@ -175,7 +187,7 @@ with exact steps — the seal then weighs the UI risk.
 /rite-ship                   # type-GO + commit/push/tag + close the task
 ```
 
-## 6) UI-direction prompt — refinement modes
+## 6) UI-direction prompt: refinement modes
 
 ```text
 /rite-polish bolder
@@ -215,16 +227,16 @@ Other modes: `quieter` · `distill` · `harden`.
 
 Run before `/clear` if leaving for > a few hours.
 
-## 9) HITL gate — pre-code pause and resume
+## 9) HITL gate: pre-code pause and resume
 
 ```text
 /rite-build
   → reads tasks.md slice 03; Mode: HITL, Gate: blocking
   → STOPS before writing any code:
 
-    SLICE-003 — list endpoint is HITL (blocking, SLA 15m).
+    SLICE-003: list endpoint is HITL (blocking, SLA 15m).
     Checkpoint: Composite (user_id, created_at) index, or two single-col indexes?
-    Proposed approach: composite — single read path, both columns used together
+    Proposed approach: composite: single read path, both columns used together
     in the most common filter; downside is rebuild cost on bulk updates.
     Decision needed before this slice can build.
     Resume: /rite-resolve q-2026-05-28-001 "<answer>"
@@ -232,7 +244,7 @@ Run before `/clear` if leaving for > a few hours.
   → appends q-...-001 to questions.md (status: open, gate: blocking)
   → writes `Awaiting human` block to state.md, sets Status: awaiting_human
 
-You: /rite-resolve q-2026-05-28-001 "composite — single-col is fine for now"
+You: /rite-resolve q-2026-05-28-001 "composite: single-col is fine for now"
 
 /rite-resolve
   → flips q-...-001 status → answered (with answered_at + answer)
@@ -249,7 +261,7 @@ If the answer changes acceptance criteria or scope, `/rite-resolve` recommends
 ## 10) AFK overnight run
 
 ```text
-# Drop the sentinel before bed. Keys are optional — empty file works.
+# Drop the sentinel before bed. Keys are optional: empty file works.
 cat > .devrites/AFK <<'EOF'
 max_slices: 10
 notify: "curl -d \"$DEVRITES_QID: $DEVRITES_QUESTION\" ntfy.sh/my-topic"
@@ -276,13 +288,13 @@ EOF
 /rite-build                    # continue
 ```
 
-The loop refuses to mark a slice `built` if tests / types / lint go red — it
+The loop refuses to mark a slice `built` if tests / types / lint go red: it
 writes a blocking question and stops regardless of `allow_gates`. AFK never
 silently accepts irreversible risk; see
 [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the
 full list.
 
-## 11) Full unattended lifecycle — `/rite-autocomplete`
+## 11) Full unattended lifecycle: `/rite-autocomplete`
 
 ```text
 /rite-autocomplete "add CSV export for admins" --max-slices 8
@@ -300,39 +312,38 @@ You: GO                        # → commit · push · tag, then archive + clear
 ```
 
 Add `--ship` (alias `--yolo`) to auto-confirm the final type-`GO` for a
-zero-touch push — autocomplete then proceeds straight to `/rite-ship`. It still
+zero-touch push: autocomplete then proceeds straight to `/rite-ship`. It still
 pauses on hard irreversible-risk (auth / migration / public-API / red tests),
 blocking / escalating gates, an open `gate: validating`, a NO-GO, exhausted
-`max_slices`, or low confidence — writing `state.md` and surfacing *why* before
+`max_slices`, or low confidence: writing `state.md` and surfacing *why* before
 it stops. Args: `[idea] [--ship|--yolo] [--max-slices N]`.
 
 ## Checking in
 
-- `/rite` — compact menu + suggested next command. **Does not** read state.
-- `/rite-status` — detailed status: phase, **run mode (AFK / HITL)**, status
+- `/rite`: compact menu + suggested next command. **Does not** read state.
+- `/rite-status`: detailed status: phase, **run mode (AFK / HITL)**, status
   (`running` / `awaiting_human` / `blocked` / `done`), next action, evidence,
   open questions broken down by gate, drift, risks, **handoff readiness**.
-- `/rite-resolve <qid> "<answer>"` — answer / `--drop` / `--batch`-resolve an
+- `/rite-resolve <qid> "<answer>"`: answer / `--drop` / `--batch`-resolve an
   open question; the canonical writer for `status: open → answered` and the
   only thing that clears `Awaiting human`.
 
 ## Tips
 
 - Commit `.devrites/` so the team and future sessions share feature state.
-- **`.devrites/AFK` is per-developer, not per-repo** — gitignore it (or commit
+- **`.devrites/AFK` is per-developer, not per-repo**: gitignore it (or commit
   it deliberately if the team agrees on AFK defaults). The sentinel is
   read-only config: it toggles your local session mode and sets the initial
   `max_slices` budget; nothing else. The mutable remaining-slice count lives
   in `state.md` (`AFK slices remaining`), never in the sentinel.
-- One feature active at a time (`ACTIVE`). To start or switch, run
-  `/rite-spec <other>` (it creates/selects that workspace and writes its
-  spec).
+- One feature active at a time (`ACTIVE`). Start a new workspace with
+  `/rite-spec <feature>`; switch to an existing one with `/rite use <slug>`.
 - **Recommended AFK progression**: HITL first to refine the prompt and plan,
   then drop the sentinel for the bulk stretch. Always cap iterations
   (`max_slices: 10` is a reasonable default).
-- Let the specialists fire on their triggers — you don't invoke `devrites-*`
-  directly. The exceptions are the three public utilities: `/rite-zoom-out`,
-  `/rite-prototype`, `/rite-handoff`.
-- The `devrites-` prefix is a namespace, not a privacy marker — whether a
-  skill is public is the `user-invocable:` flag, documented for each in
-  [`command-map.md`](command-map.md).
+- Invoke public `rite` / `rite-*` skills directly; let the model-invocable
+  `devrites-*` specialists fire from their documented triggers. `devrites-lib`
+  is an internal reference library, not a workflow.
+- Prefixes are namespaces, not invocation policy. `user-invocable` and
+  `disable-model-invocation` frontmatter are authoritative; the effective policy
+  for every skill is catalogued in [`command-map.md`](command-map.md).

package/engine/Makefile

@@ -22,7 +22,7 @@ fmt-check:
 test:
 	go test ./...
 
-# Race-enabled run — the engine has concurrent index/source-cache paths; the
+# Race-enabled run. The engine has concurrent index/source-cache paths; the
 # detector is free signal on every test that touches them.
 test-race:
 	go test -race -count=1 ./...
@@ -30,7 +30,7 @@ test-race:
 vet:
 	go vet ./...
 
-# quality is the full local gate — mirror it in CI so a green `make quality`
+# quality is the full local gate. Mirror it in CI so a green `make quality`
 # means a green pipeline (the date-sensitive parity golden aside; see ADR-0006).
 quality: fmt-check vet staticcheck govulncheck gosec test-race
 

package/engine/commands.go

@@ -81,7 +81,7 @@ func cmdDoctor(args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "devrites: %v\n", err)
 		return exitUsage
 	}
-	// The project directory is the parent of the .devrites root — that is where
+	// The project directory is the parent of the .devrites root: that is where
 	// an installed pack's version marker (.claude/devrites.version, package.json)
 	// lives.
 	projectDir := filepath.Dir(root)
@@ -92,7 +92,7 @@ func cmdDoctor(args []string, stdout, stderr io.Writer) int {
 	}
 	fmt.Fprint(stdout, report.Render())
 	if op := gitOperation(projectDir); op != "" {
-		fmt.Fprintf(stdout, "git-state: %s in progress — resolve with .claude/skills/devrites-lib/reference/standards/git-workflow.md#merge-conflict-recovery\n", op)
+		fmt.Fprintf(stdout, "git-state: %s in progress: resolve with .claude/skills/devrites-lib/reference/standards/git-workflow.md#merge-conflict-recovery\n", op)
 	}
 	for _, warning := range extensionProvenanceWarnings(root) {
 		fmt.Fprintf(stdout, "warning: %s\n", warning)
@@ -105,7 +105,7 @@ func cmdDoctor(args []string, stdout, stderr io.Writer) int {
 			fmt.Fprintf(stdout, "  evidence: %s\n", snap.Evidence.Status)
 			fmt.Fprintf(stdout, "  drift: %s\n", snap.Drift.Status)
 			fmt.Fprintf(stdout, "  review: %s\n", snap.Review.Status)
-			fmt.Fprintf(stdout, "  harness: %s — %s\n", snap.Harness.Status, snap.Harness.Detail)
+			fmt.Fprintf(stdout, "  harness: %s: %s\n", snap.Harness.Status, snap.Harness.Detail)
 			fmt.Fprintf(stdout, "  extensions: %s (%d)\n", snap.Extensions.Status, snap.Extensions.Count)
 			fmt.Fprintf(stdout, "  worktree: %s (%d changed)\n", snap.DirtyWorkspace.Status, snap.DirtyWorkspace.Changed)
 			fmt.Fprintln(stdout, "  capabilities:")

package/engine/harnessmatrix.go

@@ -12,7 +12,7 @@ import (
 // cmdHarnessMatrix renders the harness adapter-compliance matrix, or (with
 // --check FILE) verifies the generated block committed in FILE still matches the
 // engine's frozen matrix. The check is the drift guard: an edit to the matrix
-// data without regenerating the doc — or vice versa — fails CI.
+// data without regenerating the doc (or vice versa) fails CI.
 //
 // Exit: 0 rendered / in-sync · 2 usage · 3 drift (regenerate + commit).
 func cmdHarnessMatrix(args []string, stdout, stderr io.Writer) int {
@@ -38,7 +38,7 @@ func cmdHarnessMatrix(args []string, stdout, stderr io.Writer) int {
 		return exitBlocked
 	}
 	if strings.TrimSpace(got) != strings.TrimSpace(block) {
-		fmt.Fprintf(stderr, "harness-matrix: %s is out of date — run `devrites-engine harness-matrix` and commit the regenerated block.\n", path)
+		fmt.Fprintf(stderr, "harness-matrix: %s is out of date: run `devrites-engine harness-matrix` and commit the regenerated block.\n", path)
 		return exitBlocked
 	}
 	fmt.Fprintf(stdout, "harness-matrix: %s is in sync.\n", path)

package/engine/hookpolicy.go

@@ -7,7 +7,7 @@ import (
 
 // Hook control plane.
 //
-// Every wired hook has a canonical id — its `hook <name>` CLI verb (allow,
+// Every wired hook has a canonical id: its `hook <name>` CLI verb (allow,
 // orient, stop-gate, …). That id is the addressable handle for two orthogonal
 // runtime controls, both read from the environment so an operator tunes safety
 // vs speed without editing any JSON:
@@ -17,7 +17,7 @@ import (
 //
 // The profile is a floor: a hook runs when its tier is at or below the active
 // profile AND it is not in the kill list. Everything else short-circuits to a
-// clean fail-open no-op in cmdHook — identical to the inline `command -v … ||
+// clean fail-open no-op in cmdHook: identical to the inline `command -v … ||
 // exit 0` guard, so a disabled hook is indistinguishable from an absent binary.
 //
 // A SEPARATE axis is enforce-vs-observe: the OBSERVE-by-default guards (a1-guard,
@@ -31,23 +31,23 @@ type hookTier int
 
 const (
 	tierMinimal  hookTier = iota // orientation-only; never blocks or mutates flow
-	tierStandard                 // the default working set — gates, guards, caches
+	tierStandard                 // the default working set: gates, guards, caches
 	tierStrict                   // reserved for experimental/aggressive hooks
 )
 
 // hookRegistry maps each canonical hook id to the profile tier that first
 // activates it. A name absent from the registry is treated as tierMinimal
-// (always active) — fail-open: an unrecognised hook is never silently disabled
+// (always active): fail-open: an unrecognised hook is never silently disabled
 // by the profile mechanism.
 var hookRegistry = map[string]hookTier{
-	// minimal — orientation and auto-approval, which never interrupt work.
+	// minimal: orientation and auto-approval, which never interrupt work.
 	"allow":           tierMinimal,
 	"orient":          tierMinimal,
 	"subagent-orient": tierMinimal,
 	"cursor":          tierMinimal,
 	"statusline":      tierMinimal,
 
-	// standard — the default gates, guards, sentinels and caches.
+	// standard: the default gates, guards, sentinels and caches.
 	"a1-guard":          tierStandard,
 	"stop-gate":         tierStandard,
 	"reviewer-readonly": tierStandard,
@@ -62,7 +62,7 @@ var hookRegistry = map[string]hookTier{
 }
 
 // hookProfileTier resolves DEVRITES_HOOK_PROFILE to a tier, defaulting to
-// standard on empty or unrecognised input (fail-open — a typo never silently
+// standard on empty or unrecognised input (fail-open: a typo never silently
 // strips the working set below default).
 func hookProfileTier() hookTier {
 	switch strings.ToLower(strings.TrimSpace(os.Getenv("DEVRITES_HOOK_PROFILE"))) {
@@ -83,7 +83,7 @@ func hookActive(name string) bool {
 	}
 	tier, known := hookRegistry[name]
 	if !known {
-		return true // unknown id — never disabled by profile
+		return true // unknown id: never disabled by profile
 	}
 	return tier <= hookProfileTier()
 }
@@ -105,7 +105,7 @@ func hookDisabled(name string) bool {
 
 // hookEnforce reports whether an OBSERVE-default guard should block rather than
 // log. It is true when the guard's own DEVRITES_*=enforce var is set, OR when
-// the strict profile is active — strict enforces every guard at once.
+// the strict profile is active: strict enforces every guard at once.
 func hookEnforce(specificVar string) bool {
 	if os.Getenv(specificVar) == "enforce" {
 		return true

package/engine/hooks.go

@@ -22,13 +22,13 @@ import (
 // The engine's inline shell guard handles a missing binary; this handles a
 // present binary run outside a workspace.
 func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
-	// The SessionStart payload is drained but unused — orientation is a pure read
+	// The SessionStart payload is drained but unused: orientation is a pure read
 	// of the workspace files, not a function of the harness's stdin.
 	_, _ = io.Copy(io.Discard, stdin)
 
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
-		return exitOK // not a DevRites workspace — silent no-op
+		return exitOK // not a DevRites workspace: silent no-op
 	}
 	text, has, err := orient.Digest(root)
 	if err != nil {
@@ -58,7 +58,7 @@ func hookOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) in
 func hookStopGate(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	in := h.ParseStopInput(stdin)
 	if in.StopHookActive {
-		return exitOK // already re-entered this stop cycle — let it stop
+		return exitOK // already re-entered this stop cycle: let it stop
 	}
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
 	if err != nil {
@@ -89,7 +89,7 @@ func hookStopGate(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer)
 }
 
 // allowReason is the auto-approval message the allow hook emits.
-const allowReason = "DevRites read-only orientation/gate command — auto-approved by the devrites-allow hook"
+const allowReason = "DevRites read-only orientation/gate command: auto-approved by the devrites-allow hook"
 
 var allowReadonlyCommands = map[string]bool{
 	"check-acceptance": true,
@@ -213,10 +213,10 @@ func safeAllowArg(arg string) bool {
 // reviewerReadonlyDenyReason is the exact denial message
 // devrites-reviewer-readonly.sh emits. It must stay byte-identical to keep the
 // parity oracle green.
-const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash command can mutate or exfiltrate; inspect with Read/Grep/Glob and return findings — do not modify the tree or reach the network. (devrites-reviewer-readonly)"
+const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash command can mutate or exfiltrate; inspect with Read/Grep/Glob and return findings: do not modify the tree or reach the network. (devrites-reviewer-readonly)"
 
 // reviewerMutateRe matches a Bash command that could mutate the tree or reach the
-// network — the deny-list ported verbatim from devrites-reviewer-readonly.sh. A
+// network: the deny-list ported verbatim from devrites-reviewer-readonly.sh. A
 // fresh-context reviewer reads untrusted source, so a silent write/exfil path is
 // a prompt-injection surface (standards/security.md). pack-scan-ignore: this is
 // the hook's own defensive deny-list, not a payload.
@@ -225,7 +225,7 @@ const reviewerReadonlyDenyReason = "DevRites: reviewers are read-only. This Bash
 // this matches against the WHOLE command, while the bash hook's
 // `read -r tool cmd agent_type` truncates the command at its first newline and so
 // only ever scans line 1. A reviewer running a multi-line Bash whose later lines
-// mutate (e.g. `cat x\nsed -i …`) slips past the bash hook but is denied here —
+// mutate (e.g. `cat x\nsed -i …`) slips past the bash hook but is denied here:
 // intentional hardening of a latent bash bug, not a parity regression. (RE2's
 // `[[:space:]]` already matches `\n`, so no `(?m)` flag is needed for the `-i$`
 // alternative to fire at an interior line break.)
@@ -240,7 +240,7 @@ func hookReviewerReadonly(h harness.Harness, stdin io.Reader, stdout, stderr io.
 	if err != nil {
 		return exitOK
 	}
-	// Fast path: a payload with no tool call is not ours — mirrors the script's
+	// Fast path: a payload with no tool call is not ours: mirrors the script's
 	// `case "$input" in *'"tool_name"'*`.
 	if !bytes.Contains(data, []byte(`"tool_name"`)) {
 		return exitOK
@@ -300,19 +300,19 @@ var subagentOrientContext string
 // hookSubagentOrient injects the DevRites discipline into every devrites-* subagent
 // at spawn: a spawned subagent starts in a fresh context and neither auto-loads the
 // rite-* framework nor discovers skills the way the main thread does. It mirrors
-// devrites-subagent-orient.sh — fire only for devrites-* agents, emit a fixed
+// devrites-subagent-orient.sh: fire only for devrites-* agents, emit a fixed
 // context envelope, stay silent + fail-open otherwise.
 func hookSubagentOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
 	agentType := h.SubagentAgentType(stdin)
 	if !strings.HasPrefix(agentType, "devrites-") {
-		return exitOK // not a DevRites subagent (or no identity) — silent no-op
+		return exitOK // not a DevRites subagent (or no identity): silent no-op
 	}
 	out, err := h.SubagentStartContext(strings.ReplaceAll(subagentOrientContext, "\r\n", "\n"))
 	if err != nil {
 		debugf(stderr, "subagent-orient: %v", err)
 		return exitOK
 	}
-	// No trailing newline — matches the script's `node ... process.stdout.write`.
+	// No trailing newline: matches the script's `node ... process.stdout.write`.
 	fmt.Fprint(stdout, out)
 	return exitOK
 }

package/engine/hooks_workspace.go

@@ -41,7 +41,7 @@ func resolveWorkspaceDir(root, slug string) string {
 }
 
 // resolveWorkspace resolves the active feature's directory.
-// ok is false — a silent no-op — when there is no .devrites root or no active
+// ok is false (a silent no-op) when there is no .devrites root or no active
 // feature, keeping the hooks fail-open outside a DevRites workspace.
 func resolveWorkspace() (root, slug, dir string, ok bool) {
 	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
@@ -74,8 +74,8 @@ type auqEventJSON struct {
 // bloats the timeline.
 const auqFieldMax = 300
 
-// hookAUQ deterministically captures an AskUserQuestion exchange — every
-// question with the user's chosen answer — into the session trace, so HITL
+// hookAUQ deterministically captures an AskUserQuestion exchange: every
+// question with the user's chosen answer: into the session trace, so HITL
 // decisions are recorded at the substrate rather than trusted to the model's
 // bookkeeping. Capture only: it never tunes, blocks, or replies. Fail-open like
 // every workspace hook: unparseable payload, unknown response shape, or no
@@ -192,7 +192,7 @@ func hookHandoffSnapshot(stdin io.Reader, stdout, stderr io.Writer) int {
 	next, _ := state.CursorField(stateLines, state.CursorNextAction)
 	stamp := time.Now().UTC().Format(time.RFC3339)
 	var b strings.Builder
-	fmt.Fprintf(&b, "\n## Handoff snapshot — %s\n", stamp)
+	fmt.Fprintf(&b, "\n## Handoff snapshot: %s\n", stamp)
 	fmt.Fprintf(&b, "- Feature: %s\n", slug)
 	if phase != "" {
 		fmt.Fprintf(&b, "- Phase: %s\n", phase)
@@ -229,7 +229,7 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 		afk, _ = state.CursorField(stateLines, state.CursorAFKSlicesRemaining)
 	}
 
-	fmt.Fprintf(stdout, "DevRites cursor — active feature: %s\n", slug)
+	fmt.Fprintf(stdout, "DevRites cursor: active feature: %s\n", slug)
 	if status != "" {
 		fmt.Fprintf(stdout, "  status: %s\n", status)
 	}
@@ -241,7 +241,7 @@ func hookCursor(stdin io.Reader, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stdout, "  AFK slices remaining: %s\n", afk)
 	}
 	if wsIsFile(filepath.Join(dir, ".red")) {
-		fmt.Fprintln(stdout, "  ⚠ tests/build RED — resolve before stopping")
+		fmt.Fprintln(stdout, "  ⚠ tests/build RED: resolve before stopping")
 	}
 	return exitOK
 }
@@ -281,7 +281,7 @@ var (
 	redPassRe    = regexp.MustCompile(`(?im)PASS(ED)?|0[[:space:]]+(failed|failing|errors?)|all tests passed|BUILD SUCC(ESS|EEDED)|succeeded|no (errors|problems|issues)|(^|[^a-z])ok([^a-z]|$)|✓`)
 )
 
-const redReasonFmt = "DevRites: tests/build are RED (%s). Fix to green or record the failure + next step in state.md before stopping — the Stop gate blocks an end-of-turn while .red is set."
+const redReasonFmt = "DevRites: tests/build are RED (%s). Fix to green or record the failure + next step in state.md before stopping: the Stop gate blocks an end-of-turn while .red is set."
 
 // hookRedwatch is the fail-on-red sentinel (PostToolUse Bash). After a test / build
 // / lint command it sets or clears <featureDir>/.red so the Stop gate can refuse to
@@ -339,7 +339,7 @@ func redwatchSafe(cmd string) string {
 // node regex the shell guards use.
 var patchPathRe = regexp.MustCompile(`(?m)^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$`)
 
-// isEditTool reports whether a tool can write source — the Edit family plus
+// isEditTool reports whether a tool can write source: the Edit family plus
 // Codex's apply_patch.
 func isEditTool(tool string) bool {
 	switch tool {
@@ -364,10 +364,10 @@ func underDevrites(abs, root string) bool {
 	return strings.HasPrefix(abs, root+string(filepath.Separator))
 }
 
-const a1DenyReason = "DevRites A1: the orchestrator must not edit source mid-build — the slice-wright is the only writer. Re-dispatch the wright (continue it once) or stop + escalate; do not patch the code yourself. (devrites-a1-guard)"
+const a1DenyReason = "DevRites A1: the orchestrator must not edit source mid-build: the slice-wright is the only writer. Re-dispatch the wright (continue it once) or stop + escalate; do not patch the code yourself. (devrites-a1-guard)"
 
 // hookA1Guard keeps the /rite-build orchestrator from editing source while a slice
-// is mid-build — the slice-wright (a subagent) is the only sanctioned writer of
+// is mid-build: the slice-wright (a subagent) is the only sanctioned writer of
 // code. Ported from devrites-a1-guard.sh onto the new schema: FAIL-OPEN, OBSERVE by
 // default (logs to .a1-guard.log), blocking only when the build window is open, the
 // edit is source from the MAIN thread, and enforce mode is on.
@@ -451,7 +451,7 @@ func hookA1Guard(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) i
 	return exitOK
 }
 
-const wrightDenyReason = "DevRites scope: this path is not in touched-files.md. Build only the slice contract; if the slice genuinely needs this file, return an Escalation so the orchestrator routes it through the Spec Drift Guard — do not widen scope yourself. (devrites-wright-scope)"
+const wrightDenyReason = "DevRites scope: this path is not in touched-files.md. Build only the slice contract; if the slice genuinely needs this file, return an Escalation so the orchestrator routes it through the Spec Drift Guard: do not widen scope yourself. (devrites-wright-scope)"
 
 // hookWrightScope fences the slice-wright to its slice: it denies an Edit/Write to a
 // path not listed in the feature's touched-files.md. Ported from

package/engine/internal/doctor/doctor.go

@@ -1,5 +1,5 @@
-// Package doctor reports the version triangle — the engine binary, the installed
-// DevRites pack, and the on-disk .devrites state schema — and a clear skew
+// Package doctor reports the version triangle: the engine binary, the installed
+// DevRites pack, and the on-disk .devrites state schema, and a clear skew
 // verdict. Version skew is a leading cause of silent breakage; doctor turns it
 // into one legible line. Everything here is a read; doctor never mutates state.
 package doctor
@@ -16,7 +16,7 @@ import (
 )
 
 // Unknown is the pack value reported when the installed pack version can't be
-// discovered — skew against an unknown pack is not asserted.
+// discovered: skew against an unknown pack is not asserted.
 const Unknown = "unknown"
 
 // Report is the resolved version triangle plus its verdict.
@@ -45,7 +45,7 @@ func Diagnose(projectDir, root string) (*Report, error) {
 		return nil, fmt.Errorf("read state schema: %w", err)
 	}
 	if stateSchema == 0 {
-		// Nothing on disk declares a version — treat it as the current schema;
+		// Nothing on disk declares a version: treat it as the current schema;
 		// undeclared state is read as the engine's own version.
 		stateSchema = state.SchemaVersion
 	}
@@ -61,10 +61,10 @@ func Diagnose(projectDir, root string) (*Report, error) {
 	switch {
 	case r.StateSchema > r.BinarySchema:
 		r.Refuse = true
-		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d) — update devrites",
+		r.Verdict = fmt.Sprintf("REFUSE: state schema v%d is newer than this binary supports (v%d): update devrites",
 			r.StateSchema, r.BinarySchema)
 	case r.packSkew():
-		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s — update the devrites-engine binary",
+		r.Verdict = fmt.Sprintf("WARN: binary %s is older than the installed pack %s: update the devrites-engine binary",
 			r.Binary, r.Pack)
 	default:
 		r.Verdict = "ok: binary, pack, and state schema are compatible"
@@ -131,7 +131,7 @@ func driftChecks(projectDir string) []string {
 			checks = append(checks, "WARN: .claude/settings.json exists but does not reference devrites-engine hooks")
 		}
 	} else if isDir(filepath.Join(projectDir, ".claude")) {
-		checks = append(checks, "WARN: .claude/settings.json missing — Claude hooks/statusline may be absent")
+		checks = append(checks, "WARN: .claude/settings.json missing: Claude hooks/statusline may be absent")
 	}
 	if isDir(filepath.Join(projectDir, ".claude", "skills")) && !isDir(filepath.Join(projectDir, ".agents", "skills")) {
 		checks = append(checks, "WARN: Claude skills installed but Codex skill mirror .agents/skills is missing")