devrites 3.0.5 → 3.0.7

package/SECURITY.md

@@ -5,7 +5,7 @@
 If you believe you have found a security issue in DevRites, please report it
 **privately**. Do not open a public GitHub issue.
 
-- **Preferred channel:** open a private security advisory on GitHub —
+- **Preferred channel:** open a private security advisory on GitHub:
   <https://github.com/ViktorsBaikers/DevRites/security/advisories/new>.
 - **Alternate channel:** email the maintainer via the contact link on the
   GitHub profile <https://github.com/ViktorsBaikers>.
@@ -42,9 +42,9 @@ and install paths, generated host artifacts, hooks, and the local engine binary.
 Because the skill files **are** the attack surface, CI scans the shipped pack
 (`pack/.claude/`) on every PR and fails the build (blocking, not advisory) on:
 
-- **Prompt-injection patterns** — the "ignore previous instructions" family,
+- **Prompt-injection patterns**: the "ignore previous instructions" family,
   system-prompt overrides, permission-escalation, and data-exfiltration phrasing.
-- **Hidden unicode** — bidi controls, zero-width characters, and homoglyph
+- **Hidden unicode**: bidi controls, zero-width characters, and homoglyph
   confusables (a word mixing ASCII with look-alike Cyrillic/Greek letters) that a
   human reviewer can't see in a diff.
 
@@ -52,21 +52,22 @@ Run it locally with `python3 scripts/scan-pack-security.py pack/.claude`. A
 finding prints as `FINDING <file>:<line>: <class>: <excerpt>`. If the match is
 DevRites' own *defensive* content (e.g. a rule that quotes an attack string, or a
 QA checklist that demonstrates an adversarial character), add an auditable
-suppression on the line — `<!-- pack-scan-ignore: <reason> -->` — or opt a whole
-file out of one class with `<!-- pack-scan-ignore-file: injection -->`.
+suppression on the same line with `<!-- pack-scan-ignore: <reason> -->`. To opt
+an entire file out of one class, use
+`<!-- pack-scan-ignore-file: injection -->`.
 Suppressions live in the file, so every exception is visible in the diff and
 reviewable; never suppress a hidden-unicode finding you can't explain.
 
 ### State loading (engine subcommands, no `!` injection)
 
 `/rite-status` and workspace-operating skills load state by running a **read-only
-`devrites-engine` subcommand via the `Bash` tool** — *not* Claude Code's
+`devrites-engine` subcommand through the `Bash` tool**. It does not use Claude Code's
 preprocessing-only `` !`<command>` `` dynamic-context injection, which DevRites
 **removed** for cross-harness portability. The no-argument `/rite` menu runs
 `devrites-engine first-task` instead; a routed verb hands control to its owning skill.
 
 ```bash
-command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable — read state.md directly)"
+command -v devrites-engine >/dev/null 2>&1 && devrites-engine preamble || echo "(unavailable: read state.md directly)"
 ```
 
 `devrites-engine preamble` is a project-local read of DevRites' own `.devrites/`
@@ -76,10 +77,9 @@ side effects. The gate subcommands (`build-readiness`, `evidence-fresh`,
 scoped: for example, `resolve`, `tick-afk`, and `close-out` write only DevRites
 state, while `/rite use <slug>` deliberately repoints `.devrites/ACTIVE` inline.
 
-If your environment disallows skill-initiated shell execution, the commands simply
-don't run — each skill degrades gracefully to reading `state.md` directly (the
-`|| echo "(… unavailable …)"` fallback above), and the rest of the pack is
-unaffected.
+If your environment disallows shell commands started by skills, each skill reads
+`state.md` directly through the `|| echo "(… unavailable …)"` fallback above.
+The rest of the pack continues to work.
 
 ### Model invocation is per skill
 
@@ -98,8 +98,8 @@ nets for model-invocable rites are:
 - **Spec Drift Guard**: any deviation from the spec halts and routes to
   `rite-plan`.
 - **Interactive type-GO confirmation** in `rite-ship` before irreversible
-  git actions (commit, push, tag) — present even after model invocation; `rite-seal`
-  only decides GO/NO-GO.
+  git actions such as commit, push, or tag. This prompt remains after model
+  invocation; `rite-seal` only decides GO/NO-GO.
 
 Claude documents the invocation controls in its official
 [skills reference](https://code.claude.com/docs/en/slash-commands). DevRites uses
@@ -160,7 +160,7 @@ project-local host artifacts (`.claude/settings.json` for Claude Code and
 `.codex/hooks.json` for Codex). They call `devrites-engine` behind an inline
 fail-open guard:
 
-- **`allow` (PreToolUse/Bash)** — auto-approves *only* the read-only engine
+- **`allow` (PreToolUse/Bash)**: auto-approves *only* the read-only engine
   orientation/gate subcommands (`check-acceptance`, `doubt-coverage`,
   `evidence-fresh`, `preamble`, `progress`, `readiness`, `review-integrity`),
   `footprint render|roster`, `ledger diff|validate|list|show`, and
@@ -170,10 +170,10 @@ fail-open guard:
   `curl`/`wget`, `sudo`, `chmod`, command substitution, `eval`, package managers,
   `git push/commit/reset`, etc.). Mutating subcommands (`resolve`, `tick-afk`,
   `close-out`) are deliberately excluded and still prompt.
-- **Context and continuity hooks** — `orient`, `cursor`, `subagent-orient`,
+- **Context and continuity hooks**: `orient`, `cursor`, `subagent-orient`,
   `statusline`, and `handoff-snapshot` inject bounded workspace context; `event`
   and `auq` append lifecycle/HITL events. They stay silent when no workspace is active.
-- **Local guards and caches** — `a1-guard`, `wright-scope`,
+- **Local guards and caches**: `a1-guard`, `wright-scope`,
   `reviewer-readonly`, `redwatch`, `stop-gate`, `source-cache-*`, and
   `refresh-indexes` run through the engine. Guard hooks are fail-open or
   observe-first unless explicitly enforced with the documented `DEVRITES_*`
@@ -187,25 +187,25 @@ so user permission rules remain intact.
 ### Third-party trust
 
 DevRites vendors no third-party code (see `NOTICE.md`). It depends on Claude
-Code itself and, optionally and at the user's choice, on codegraph /
-graphify / Playwright MCP — each of which is invoked through its own
-documented interface, not bundled.
+Code itself. Codegraph, graphify, and Playwright MCP are optional user-selected
+tools that DevRites calls through their documented interfaces rather than
+bundling them.
 
 ### Agentic trust boundaries
 
 Treat every instruction-bearing file as supply chain:
 
-1. **Shipped pack** — `pack/.claude/**`, generated host artifacts, hooks, and the
+1. **Shipped pack**: `pack/.claude/**`, generated host artifacts, hooks, and the
    engine are release-managed and scanned before publish.
-2. **Project-local state** — `.devrites/work/**`, learnings, principles, and
+2. **Project-local state**: `.devrites/work/**`, learnings, principles, and
    review artifacts are evidence, not authority. Live source and engine gates win
    over stale state.
-3. **User extensions/overrides** — `.devrites/extensions/**` and
+3. **User extensions/overrides**: `.devrites/extensions/**` and
    `.devrites/overrides/**` are untrusted until `devrites-engine extensions
    validate` / `overrides validate` pass. Extensions may add checks or reviewers;
    they must not weaken type-GO, seal/ship, AFK/HITL, security, or evidence
    gates.
-4. **External capability configs** — MCP/tool configs are optional and
+4. **External capability configs**: MCP/tool configs are optional and
    project-local. `/rite-doctor`/`devrites-engine doctor` reports readiness, but
    missing tools degrade to file-system/engine gates instead of silently changing
    workflow semantics.
@@ -218,11 +218,11 @@ visibly justified.
 
 ### Known non-issues
 
-- **Historical `!` injection in `/rite`** — no longer present; current state
+- **Historical `!` injection in `/rite`**: no longer present; current state
   orientation uses structurally bounded, read-only engine commands.
-- **`Write` / `Edit` tool allowance in `rite-*` skills** — required to
+- **`Write` / `Edit` tool allowance in `rite-*` skills**: required to
   author `.devrites/` and project files. No skill grants `Bash(*)`.
-- **Per-skill model invocation** — deliberate and frontmatter-controlled;
+- **Per-skill model invocation**: deliberate and frontmatter-controlled;
   model-invocable rites remain bounded by the gates above.
 
 ### CVE relevance

package/docs/adr/README.md

@@ -1,9 +1,8 @@
-# Architecture Decision Records
+# Architecture decision records
 
-An ADR captures **one** load-bearing decision: the context that forced it, the
-decision itself, the alternatives that were rejected and *why*, and the
-consequences accepted. The rejected-alternatives table is the point — it keeps
-the "why not X" from being re-litigated every quarter.
+An ADR records one architectural decision, the context behind it, the options
+that were rejected, and the consequences the team accepted. Recording why an
+option lost prevents the same debate from starting again later.
 
 `CLAUDE.md` points every agent here (`CONTEXT.md` + `docs/adr/` are the
 single-context domain record). Keep this directory the source of truth for
@@ -17,9 +16,8 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 - Sections: **Context** → **Decision** → **Alternatives considered** (a table:
   option · why rejected) → **Consequences**.
 - **Guard test:** an accepted ADR that asserts a runtime invariant SHOULD have a
-  named regression test — `engine/tests/adr_NNNN_*_test.go` — so the decision
-  has an executable proof it still holds. Reference the ADR number in the test's
-  doc comment.
+  named regression test such as `engine/tests/adr_NNNN_*_test.go`. Reference the
+  ADR number in the test's doc comment so the decision has executable proof.
 
 ## Template
 
@@ -48,7 +46,7 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 
 | ADR | Title | Status | Guard test |
 |-----|-------|--------|-----------|
-| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | — |
+| [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted | none |
 | [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `tests/parity_*_test.go` |
 | [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `tests/adr_0003_gate_exit_code_test.go` |
 | [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `tests/adr_0004_required_by_phase_test.go` |

package/docs/agents/domain.md

@@ -1,12 +1,12 @@
-# Domain Docs
+# Domain documentation
 
 How the engineering skills should consume this repo's domain documentation when exploring the codebase.
 
 ## Before exploring, read these
 
 - **`CONTEXT.md`** at the repo root, or
-- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
 
 If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. DevRites creates or updates domain records lazily when a feature resolves a durable term, ambiguity, or decision.
 
@@ -42,7 +42,7 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
 
 When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
 
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap. Update `CONTEXT.md` only when the term is durable enough to help future work.
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap. Update `CONTEXT.md` only when the term is durable enough to help future work.
 
 ## Maintain domain records only when they earn it
 
@@ -55,4 +55,4 @@ If the concept you need isn't in the glossary yet, that's a signal — either yo
 
 If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
 
-> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
+> _Contradicts ADR-0007 (event-sourced orders). Reopen it because…_

package/docs/agents/issue-driven-rites.md

@@ -7,5 +7,5 @@ Local issue files are the source of truth; external trackers are references only
 1. Create `.scratch/<slug>/PRD.md` when product detail is needed and one or more numbered implementation issues under `.scratch/<slug>/issues/<NN>-<issue-slug>.md`, starting at `01`.
 2. Start `/rite-spec <slug>` from the relevant PRD/issues; copy lifecycle decisions into `.devrites/work/<slug>/`, while tracker status/comments remain in the local issue files.
 3. Run the normal lifecycle: `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
-4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference actually exists.
+4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference exists.
 5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope.

package/docs/agents/issue-tracker.md

@@ -1,4 +1,4 @@
-# Issue tracker: Local Markdown
+# Issue tracker: local Markdown
 
 Issues and PRDs for this repo live as markdown files in `.scratch/`. For the end-to-end local issue → rites flow, see [issue-driven-rites.md](issue-driven-rites.md).
 

package/docs/agents/triage-labels.md

@@ -1,4 +1,4 @@
-# Triage Labels
+# Triage labels
 
 The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
 
@@ -12,4 +12,4 @@ The skills speak in terms of five canonical triage roles. This file maps those r
 
 When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
 
-Edit the right-hand column to match whatever vocabulary you actually use.
+Edit the right-hand column to match the vocabulary you use.

package/docs/architecture.md

@@ -1,4 +1,4 @@
-# DevRites Architecture
+# DevRites architecture
 
 DevRites is a **distributed but coordinated** set of project-local Claude Code
 and Codex skill surfaces backed by one Go control plane. It makes an AI coding
@@ -13,7 +13,7 @@ traceability rules, and phase-relative completeness model, see
 
 ## Layers
 
-1. **Public lifecycle and workspace skills** — `.claude/skills/rite-*`,
+1. **Public lifecycle and workspace skills**: `.claude/skills/rite-*`,
    `user-invocable: true`. Each owns one bounded phase or workspace transition.
    Sequence: `rite-spec`, optional `rite-temper`, `rite-define`, mandatory
    `rite-vet`, `rite-build`, recovery `rite-converge`, `rite-prove`,
@@ -27,11 +27,11 @@ traceability rules, and phase-relative completeness model, see
    irreversible git ladder and **closes** the task (archives the workspace,
    clears `ACTIVE`). Keeping the decision and the irreversible action as two
    separately-auditable steps is the point.
-2. **Public utility and on-ramp skills** — `rite-adopt`, `rite-quick`,
+2. **Public utility and on-ramp skills**: `rite-adopt`, `rite-quick`,
    `rite-frame`, `rite-status`, `rite-doctor`, `rite-learn`, `rite-explain`,
    `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
    `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
-   `rite-autocomplete` — public commands. `rite-autocomplete` is the
+   `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
    unattended orchestrator: it drives the whole lifecycle (spec → … → seal →
    ship) end-to-end, choosing the best option at each soft gate, pausing only
    on hard irreversible-risk / blocking / escalating gates or a NO-GO. The
@@ -39,7 +39,7 @@ traceability rules, and phase-relative completeness model, see
    Claude Code skill names like `prototype`, `handoff`, `triage`, `diagnose`),
    not a visibility marker; `rite-pressure-test` carries no prefix because it
    doesn't collide.
-3. **Internal specialist skills** — `.claude/skills/devrites-*` with
+3. **Internal specialist skills**: `.claude/skills/devrites-*` with
    `user-invocable: false`: `devrites-interview`, `-source-driven`,
    `-doubt`, `-ux-shape` (plans UX/UI into `design-brief.md` at `/rite-spec`),
    `-frontend-craft`, `-browser-proof`, `-debug-recovery`,
@@ -55,21 +55,21 @@ traceability rules, and phase-relative completeness model, see
    files on demand; compact utilities keep a narrower local contract. Parallel
    reviewer fan-out at `/rite-seal` is the shared reference file
    `devrites-lib/reference/parallel-dispatch.md`, not a skill.
-4. **Supporting references** — `reference/*.md` inside each skill. Long checklists,
+4. **Supporting references**: `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
-5. **Agents** — `.claude/agents/devrites-*` fresh-context subagents: **13 read-only + 1
-   write-capable**. The read-only set is twelve reviewers — the post-build fan-out used by
+5. **Agents**: `.claude/agents/devrites-*` fresh-context subagents: **13 read-only + 1
+   write-capable**. The read-only set is twelve reviewers: the post-build fan-out used by
    `/rite-seal` and the doubt loop (`devrites-spec-reviewer`, `-code-reviewer`, `-test-analyst`,
    `-frontend-reviewer`, `-security-auditor`, `-performance-reviewer`, `-devex-reviewer`,
    `-doubt-reviewer`, `-simplifier-reviewer`), the **pre-plan** `devrites-strategy-reviewer`
    (`/rite-temper`), the **pre-build** `devrites-plan-reviewer` (`/rite-vet`), and the
    **build-time** `devrites-forge-judge` (scores competing candidate builds on a `Forge: yes`
-   slice) — plus the cross-feature `devrites-retrospector` (mines the shipped archive at
+   slice), plus the cross-feature `devrites-retrospector` (mines the shipped archive at
    `/rite-ship` close). The one **write-capable** executor, `devrites-slice-wright`, is
    dispatched by `/rite-build` to write one slice in a clean context (the write-side mirror of
    the reviewers).
-6. **Engineering rules** — DevRites' own stack-agnostic rules installed to
+6. **Engineering rules**: DevRites' own stack-agnostic rules installed to
    `.claude/skills/devrites-lib/reference/standards/`. Workspace-operating lifecycle
    skills read `core.md` in step 0; compact utilities load only their local or conditional
    rules. On-demand files load by the phase that needs them:
@@ -96,8 +96,8 @@ capabilities belong.
 ## Design rationale
 
 ### Why the engine owns shared orientation (`devrites-lib`)
-Every workspace-operating skill's first move is the same: orient on the active feature —
-slug, phase, artifacts present, run mode, open-question tally — before acting. Re-deriving
+Every workspace-operating skill starts by reading the active feature's slug,
+phase, present artifacts, run mode, and open-question tally. Re-deriving
 that from raw Markdown in each skill was duplicated (step-0 prose across ~20 skills),
 token-heavy (counting open gates meant re-reading the append-only `questions.md`, which
 only grows), and error-prone (a missed AFK sentinel or a miscounted gate changes behavior).
@@ -143,7 +143,7 @@ Built-in / bundled Claude Code commands include `/plan`, `/review`, `/run`, `/ve
 recommended-start guidance from `devrites-engine first-task`, and dispatches a
 named verb to its owning skill. Menu mode does not read raw workspace state;
 `/rite-status` owns detailed status. `/rite` deliberately does **not** duplicate
-workflow logic — that would recreate the mega-command problem. DevRites keeps
+workflow logic. Doing so would recreate the mega-command problem. DevRites keeps
 selection thin and lets each phase own its context.
 
 ### Why internal skills exist
@@ -156,8 +156,9 @@ skills they:
 - keep each public `SKILL.md` small by housing the heavy process elsewhere.
 
 ### Why spec, architecture, plan, tasks, and traceability are separate artifacts
-Doing investigation, spec, plan, and slicing in one batch lets things slip — a gap goes
-unasked, placement is guessed, a slice misses a requirement. DevRites splits them so each
+Combining investigation, specification, planning, and slicing makes it easier
+to miss a question, guess at placement, or leave a requirement out of a slice.
+DevRites splits them so each
 is focused and gated. `/rite-spec` **investigates deeply and writes `spec.md`** (product
 what/why, requirements, acceptance, non-goals, measurable success) and must pass its
 readiness gate. `/rite-define` then turns that **approved spec** into `architecture.md`
@@ -168,14 +169,14 @@ is the separate repair/reslice/re-order tool for an *active* plan when it goes s
 drifts.
 
 ### Why `/rite-polish` is one skill with two progressive-disclosure halves
-Polish has two natural halves — **code** (simplify, dead code, naming, plus
+Polish has two natural halves: **code** (simplify, dead code, naming, plus
 backend if BE was touched) and **UI** (normalize to the design system, then
 ship-quality detail). The earlier design split them into `rite-polish-code`
 and `rite-polish-ui` sub-skills, but a skill-on-skill dispatch is fragile
 (the caller has to re-discover the callee by description) and the two halves
 share the same operating rules. They now live as `reference/code.md` and
 `reference/ui.md` inside the same skill, loaded only when their phase
-trigger fires — the supporting-files pattern from Claude Code's current
+trigger fires. This follows the supporting-files pattern from Claude Code's current
 [skills reference](https://code.claude.com/docs/en/slash-commands#add-supporting-files).
 `/rite-polish` is the orchestrator: always reads `reference/code.md`
 (Phase 1 + 2), detects UI scope from the diff and reads `reference/ui.md`
@@ -183,19 +184,19 @@ trigger fires — the supporting-files pattern from Claude Code's current
 `quieter`, `distill`, `harden`, `normalize-only`) that pass through to
 Phase 4.
 
-Normalization remains the entry gate of UI polish — polishing UI that hasn't
-been aligned to the project's design system is "decoration on drift," and
-the UI reference refuses to run Phase 4 before Phase 3.
+Normalization remains the entry gate for UI polish. The UI reference refuses
+to run Phase 4 before Phase 3 because detail work would otherwise reinforce
+patterns that do not match the project's design system.
 
 ### Why seal and ship are separate phases (`/rite-seal`, `/rite-ship`)
-Deciding "is this safe to ship" and *actually shipping* are different acts with
+Deciding "is this safe to ship" and *shipping it* are different acts with
 different blast radii. `/rite-seal` is a **pure decision gate**: it walks acceptance
 against evidence, fans out the fresh-context reviewers, and writes the GO / NO-GO
-verdict to `seal.md` — it runs no git. On GO it sets `state.md` `Next step:
+verdict to `seal.md` and runs no git. On GO it sets `state.md` `Next step:
 /rite-ship` and stops. `/rite-ship` is the eighth core lifecycle rite: it refuses to run
 without a GO recorded in `seal.md`, renders the type-`GO` prompt, runs the irreversible
 git ladder (commit → push → tag/PR per the project's convention), writes `ship.md`,
-then **closes the task** — sets phase `done` and archives `.devrites/work/<slug>/` →
+then **closes the task** by setting phase `done` and archiving `.devrites/work/<slug>/` →
 `.devrites/archive/<slug>/` (every `.md` preserved, never deleted) and clears
 `.devrites/ACTIVE`. A GO seal is a verdict, not an authorization to push; keeping the
 decision and the irreversible action as two separately-auditable steps is the point.
@@ -206,8 +207,8 @@ Some features are routine enough to run end-to-end without per-phase human itera
 build×N → prove → polish → review → seal → ship) by reading each phase's
 `SKILL.md` and executing its
 workflow, carrying state through the workspace files rather than chat. A vague prompt
-triggers an up-front `devrites-interview` — the only interactive window — after which it
-runs unattended, choosing the best option at each soft gate and recording the rationale
+triggers an up-front `devrites-interview`, which is the only interactive window.
+After that it runs unattended, choosing the best option at each soft gate and recording the rationale
 in `decisions.md`. It does **not** weaken the safety gates: 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 all still pause.
@@ -215,44 +216,43 @@ By default it stops at the final type-`GO`; the `--ship` flag (alias `--yolo`)
 auto-confirms it for a zero-touch push.
 
 ### Why persistent `.devrites/` state
-Long features outlive a single context window. Durable Markdown (spec/plan/tasks/
-state/evidence/drift/decisions) lets any phase — in any session, after any compaction
-— reload exactly where work stands. This is the main thing DevRites adds over typical
+Long features outlive a single context window. Durable Markdown for the spec,
+plan, tasks, state, evidence, drift, and decisions lets any phase reload the
+current position in any session, even after compaction. This is the main thing DevRites adds over typical
 session-scoped workflows, which don't persist feature state.
 
-### Run modes — HITL & AFK
+### Run modes: HITL & AFK
 
 DevRites runs the same lifecycle two ways, configured at two levels:
 
-- **Per-slice** (planning-time) — each `tasks.md` slice declares `Mode: AFK | HITL`.
+- **Per-slice** (planning-time): each `tasks.md` slice declares `Mode: AFK | HITL`.
   HITL slices add `Gate: advisory | validating | blocking | escalating`, `SLA`, and
   `Checkpoint` so the agent knows how disruptive the pause should be.
-- **Per-session** (run-time) — the presence of `.devrites/AFK` flips the session-level
+- **Per-session** (run-time): the presence of `.devrites/AFK` flips the session-level
   default. Empty file = AFK with safe defaults; YAML body widens behavior
   (`max_slices`, `notify`, `allow_gates`).
 
-The pause primitive is a **pre-action interrupt**, not a post-action review queue —
-inspired by LangGraph's `interrupt()` / `Command(resume=)` model. `/rite-build` writes
+The pause primitive is a **pre-action interrupt**, not a post-action review queue.
+It follows LangGraph's `interrupt()` / `Command(resume=)` model. `/rite-build` writes
 an `Awaiting human` block to `state.md` and a question to `questions.md`, then stops.
 `/rite-resolve` is the canonical resume verb. Restarting a session reads the workspace
 back into a consistent state because the pause is durable Markdown, not chat memory.
 
 Why a four-gate taxonomy (instead of a single "ask the user" pause): a single gate
 becomes a queue under load. Mixing `advisory` (audit-only log) with `validating`
-(async — build continues, merge blocks) and reserving `blocking` for synchronous halts
-keeps the loop alive when the answer can wait, and pauses hard when it can't. The
-"AFK never silently accepts irreversible risk" rule — destructive migrations,
-auth/authz boundaries, public API breaks, red tests/types/lint — always pauses
-regardless of the sentinel. See
+(async: build continues, merge blocks) and reserving `blocking` for synchronous halts
+keeps the loop alive when the answer can wait, and pauses hard when it cannot.
+AFK always pauses for destructive migrations, auth/authz boundaries, public API
+breaks, and failed tests, type checks, or lint, regardless of the sentinel. See
 [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md) for the full
 contract.
 
 ## Design choices at a glance
 
-- **Surface**: 29 public `rite-*` skills (42 total) — the thin `/rite` menu
+- **Surface**: 29 public `rite-*` skills (42 total): the thin `/rite` menu
   (carries the routing) + 8 lifecycle phases (`rite-spec`, `rite-define`,
   `rite-build`, `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`,
-  `rite-ship` — seal **decides**, ship **executes + closes**) + the
+  `rite-ship`: seal **decides**, ship **executes + closes**) + the
   `rite-temper` (strategic, optional) and `rite-vet` (engineering, every plan)
   reviews + the `rite-quick` express lane and `rite-frame` pre-flight/self-audit
   lens + `rite-adopt` (onboard an existing codebase) + `rite-learn` (cross-feature
@@ -265,9 +265,9 @@ contract.
   resume verb + 4 ideation /
   handoff utilities (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
   `rite-pressure-test`) + `rite-autocomplete` (the unattended full-lifecycle
-  orchestrator) — plus 11 internal model-invoked `devrites-*` specialists and the
+  orchestrator), plus 11 internal model-invoked `devrites-*` specialists and the
   `devrites-lib` library, not one mega-command. The `devrites-` prefix is a
-  namespace (collision avoidance), not a public/internal marker —
+  namespace (collision avoidance), not a public/internal marker.
   `user-invocable:` is. The 11 specialists are model-invoked;
   `devrites-lib` explicitly disables model invocation.
 - **Selection**: the `/rite` menu skill carries the routing table; every
@@ -278,13 +278,13 @@ contract.
 - **Run modes**: same lifecycle runs HITL (default; pause at typed gate) or AFK
   (drop `.devrites/AFK`; loop continues, discretionary pauses downgrade to
   advisory log, irreversible risk always pauses).
-- **Slice rule**: build **one vertical slice, then stop** — no auto-continue.
+- **Slice rule**: build **one vertical slice, then stop**. There is no automatic continuation.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
 - **Review**: **feature-scoped** multi-axis review with severity labels +
   fresh-context subagents at the seal.
-- **Scope**: clarify → seal (decide) → ship (the irreversible git ladder —
-  commit → push → tag/PR — per the project's own convention) → close; the CI
+- **Scope**: clarify → seal (decide) → ship (commit → push → tag or PR,
+  following the project's convention) → close. The CI
   pipeline stays with the project.
 - **Install**: project-local, manifest-managed host artifacts; the optional
   shared engine binary is the sole sanctioned global artifact.

package/docs/cli.md

@@ -1,9 +1,9 @@
-# Tool-agnostic state core — the `devrites-engine` CLI
+# Tool-agnostic state core: the `devrites-engine` CLI
 
-DevRites' discipline lives in `.devrites/` Markdown files and the `devrites-engine`
-engine binary, not in one chat harness. Any tool — Claude Code, Codex, Cursor,
-Gemini CLI, CI, or a human — can drive the same deterministic gates from the
-project root.
+DevRites stores its workflow in `.devrites/` Markdown files and the
+`devrites-engine` binary rather than tying it to one chat harness. Claude Code,
+Codex, Cursor, Gemini CLI, CI, and human operators can all run the same
+deterministic gates from the project root.
 
 ## The `devrites-engine` CLI
 
@@ -19,7 +19,7 @@ devrites-engine build-readiness [slug]   # build-readiness gate      (exit 0 rea
 devrites-engine evidence-fresh [slug]    # proof freshness gate      (exit 0 fresh · 3 stale)
 devrites-engine check-acceptance <dir>   # acceptance gate           (exit 0 proven · 1 gap)
 devrites-engine ledger sync <dir>        # fold a feature's spec deltas into the living capability ledger
-devrites-engine ledger list|show <cap>   # read the ledger — what the system already does
+devrites-engine ledger list|show <cap>   # read the ledger: what the system already does
 devrites-engine context show --json      # report root, active workspace, and host command forms
 devrites-engine timeline log|list        # append/list session events, decisions, and state moves
 devrites-engine health run               # run known project checks + record a code-health dashboard
@@ -34,7 +34,7 @@ devrites-engine help
 
 The AFK-parsed read commands (`status`, `readiness`, `seal`, `spec-validate`,
 `evidence-fresh`, `preamble`, `coverage`, `analyze`, `doctor`, `ledger`) accept
-`--json`, which wraps the result in a stable envelope — see
+`--json`, which wraps the result in a stable envelope: see
 [`engine/agent-contract.md`](engine/agent-contract.md). `snapshot` is already a
 structured JSON contract and emits `schemaVersion: devrites.workspace.v1`
 directly rather than wrapping human text. Snapshot consumers should read
@@ -54,7 +54,7 @@ in an agent loop, a local script, or pre-merge CI.
 
 ## Why this exists
 
-DevRites workspaces and standards are tool-agnostic data. The CLI makes that
-workflow drivable from agent loops, local scripts, CI, and humans without
-reimplementing the discipline. A verdict from the CLI or a `rite-*` workflow
-should agree because they run the same engine gates.
+DevRites workspaces and standards are tool-agnostic data. The CLI lets agent
+loops, local scripts, CI, and humans use that data without rebuilding the
+workflow. CLI verdicts and `rite-*` verdicts agree because both run the same
+engine gates.