devrites 4.2.0 → 4.4.0

package/pack/generated/codex/skills/rite-build/reference/checkpoint-protocol.md

@@ -1,29 +1,22 @@
 # Checkpoint protocol: what `$rite-build` does when a slice is HITL
 
-When `$rite-build` reaches a slice with `Mode: HITL`, it does **not** start writing code. It
-surfaces the checkpoint as a ranked **option set** and resolves it **before** any code lands:
+HITL slices pause **pre-action** as a ranked **option set** before any code:
 
-- **Human present (interactive):** ask inline via `AskUserQuestion` (the option set below).
-  The human picks; record the pick to `questions.md` (`answered`) + `decisions.md`, clear the
-  gate, and **continue building in place**: no STOP, no `$rite-resolve` round-trip.
-- **Human absent / AFK-pausing / notify-only:** persist the checkpoint (`questions.md` open +
-  `state.md` `Awaiting human`), fire the `notify:` hook, and **stop**. Resume later via
-  `$rite-resolve` (or `--batch`).
-
-Either way the pause is **pre-action**, not post-action: code never lands before the gate.
+- **Interactive:** `AskUserQuestion`; record to `questions.md`/`decisions.md`; clear gate;
+  continue in place (no `$rite-resolve` round-trip).
+- **Absent / AFK / notify-only:** persist open question + `Awaiting human`, notify, **stop**.
+  Resume via `$rite-resolve` (or `--batch`).
 
 ## Render contract
 
-The checkpoint must be rendered in user-facing output **and** persisted to the workspace.
-Both are required: the output is for the human in the room (or the notification target),
-the persisted form is for the next session or the AFK observer.
+Render the checkpoint in user-facing output **and** persist it for the next session / AFK
+observer.
 
 ### User-facing render: the option set
 
-Present the checkpoint as an `AskUserQuestion` with a ranked **option set**
-(`afk-hitl.md` → "Option set"): 2-4 options, **recommended first** + labelled `(Recommended)`,
-each option's description carrying the dimension-tagged rationale + the trade-off it accepts,
-plus the escape hatch. The header names the slice + gate:
+Present as `AskUserQuestion` ranked **option set** (`afk-hitl.md`): 2–4 options,
+recommended first + `(Recommended)`, dimension-tagged trade-offs, plus escape hatch.
+Header names slice + gate:
 
 ```
 Slice <N — name> — HITL (<gate>, SLA <SLA>). <Checkpoint text from tasks.md>
@@ -35,12 +28,9 @@ Slice <N — name> — HITL (<gate>, SLA <SLA>). <Checkpoint text from tasks.md>
   4. Something else — I'll describe it
 ```
 
-The recommended option (#1) is **required**: a checkpoint without a recommendation is a worse
-interrupt than one with shape; the human reacts to a ranked draft faster than to a blank prompt
-(the "give the human something to approve" rule). The recommendation reflects *this* project
-(its conventions, stack, scale), not a generic default. On an interactive pick, resolve in
-place; when persisting a pause instead, the same set is written to `questions.md` `options:`
-and the resume line is `$rite-resolve <qid> "<answer>"` (or `--drop <qid> "<reason>"`).
+Option #1 (recommended) is **required** and must reflect *this* project. Interactive pick →
+resolve in place; pause → persist the same set to `questions.md` `options:` with resume
+`$rite-resolve <qid> "<answer>"` (or `--drop <qid> "<reason>"`).
 
 ### Workspace mutations
 
@@ -93,9 +83,7 @@ rewrite; do not claim cross-file atomicity):
    sh -c "$notify_cmd"
    ```
 
-   The hook fires after the workspace write so the notification target sees a workspace
-   that already records the pause. Failures in the hook **do not** roll back the pause:
-   the gate is authoritative; the notification is best-effort.
+   Fire after workspace write. Hook failure does **not** roll back the pause (best-effort).
 
 ## qid generation
 
@@ -109,42 +97,24 @@ reservation or engine command for qids.
 
 ## When AFK is active
 
-If `.devrites/AFK` exists and the slice's `Gate` is in `allow_gates`, `$rite-build` does
-**not** invoke the checkpoint protocol. Instead:
-
-- For `advisory`: log a `gate: advisory` entry to `questions.md`, record the trade-off in
-  `decisions.md`, and **dispatch the wright** to build the slice (workflow step 3).
-- For `validating` (only when `allow_gates` includes it): **dispatch the wright** (step 3); on
-  return, write a `gate: validating` entry to `questions.md`, mark the slice
-  `built (pending review)` in `state.md`, and continue. A slice's only states are `pending` and `built`:
-  acceptance is proven at the **feature** level by `$rite-prove` (recorded in
-  `evidence.md`), not per slice. The `built (pending review)` slice is not done until the
-  open `validating` gate resolves via `$rite-resolve`; an open `validating` gate is a
-  NO-GO at seal.
-
-For gates in `allow_gates`, AFK **auto-picks the recommended option** (option 1 of the set)
-instead of pausing, recording it as above. For `blocking` and `escalating` (and every
-irreversible-risk item), AFK **always** invokes the checkpoint protocol: the sentinel does
-not unlock these gates and no AFK key can override them. See `afk-discipline.md`
-for the irreversible-risk list.
+If `.devrites/AFK` exists and the slice `Gate` is in `allow_gates`, skip this protocol and
+auto-pick recommended option 1:
+
+- `advisory`: log `gate: advisory` + `decisions.md`, then dispatch wright.
+- `validating` (only if allowed): dispatch wright; on return log `gate: validating`, mark
+  `built (pending review)`, continue. Slice states remain `pending|built`; feature
+  acceptance is `$rite-prove`. Open `validating` is NO-GO at seal until `$rite-resolve`.
+
+`blocking` / `escalating` / irreversible-risk always use this protocol (`afk-discipline.md`).
 
 ## Multi-question pauses
 
-The current protocol is **one question per pause**. If a slice has multiple HITL
-checkpoints, split it into sub-slices via `$rite-plan reslice` so each pause is
-single-question. Multi-question pauses are reserved future shape; `Awaiting human` is
-written as a single block.
+**One question per pause.** Multiple HITL checkpoints → `$rite-plan reslice`.
 
 ## What NOT to do
 
-- **Don't write code first and pause after.** The pre-action rule is the whole point.
-- **Don't render the checkpoint without persisting.** Output without `state.md` + `questions.md`
-  updates means the workspace lies on `/clear`.
-- **Don't self-answer a question that *paused* for a human.** When a gate stopped the session
-  (an AFK queue, or a HITL pause the human walked away from), `$rite-resolve` requires an
-  explicit answer: the agent doesn't confirm its own `proposed:` on resume. This is distinct
-  from the two legitimate auto-resolutions: an interactive `AskUserQuestion` pick the human
-  just made, and an AFK auto-pick of the recommended option on a gate `allow_gates` permits.
-- **Don't bundle the `notify:` hook output into chat.** Fire-and-forget; the chat already
-  has the user-facing render.
-- **Don't fire `notify:` on `advisory`-downgraded entries.** It's reserved for true pauses.
+- Don't write code then pause — pre-action only.
+- Don't render without persisting `state.md` + `questions.md`.
+- Don't self-answer a human pause via `proposed:` — `$rite-resolve` needs an explicit
+  answer (distinct from interactive pick / AFK auto-pick on `allow_gates`).
+- Don't put `notify:` output in chat; don't fire `notify:` on advisory-only entries.

package/pack/generated/codex/skills/rite-build/reference/one-slice-cycle.md

@@ -3,11 +3,14 @@
 One wright dispatch builds one thin, proven slice. HITL stops; only explicit
 `.devrites/AFK` lets the controlling root chain another pending slice under the
 green-proof, cap, and pause rules. Each wright returns after exactly one slice.
+Opt-in fan-out: [`parallel-batch.md`](parallel-batch.md) (`--parallel N`); this is default.
 
 ## The cycle
+
 The orchestrator (`$rite-build`) gates and records; the **wright** writes. See
 [`wright-dispatch.md`](wright-dispatch.md).
-```
+
+```text
 SELECT    → orchestrator: restate slice goal + acceptance + scope boundary; HITL gate (pause pre-code)
 (SHAPE)   → orchestrator: missing UI design-brief.md → shape it, then $rite-vet before dispatch
 DISPATCH  → hand the slice contract to devrites-slice-wright (fresh context). Inside the wright:
@@ -25,14 +28,16 @@ NEXT      → HITL root reports and stops; AFK root may repeat only under afk-di
 ```
 
 ## Why the boundary matters
-- Keeps diffs reviewable and reveals integration or drift early.
-- Preserves a HITL decision point and prevents unproven pile-ups.
+
+Reviewable diffs, early drift signal, HITL decision point, no unproven pile-ups.
 
 ## Restate the scope boundary
+
 Before coding, write what this slice will and will **not** touch. This is the contract
 you check yourself against: anything outside it is scope creep or a drift event.
 
 ## When the slice can't be completed cleanly
+
 - Discovered the plan is wrong → **Spec Drift Guard** (stop, record, classify, maybe
   ask, `$rite-plan` repair).
 - Slice is bigger than one cycle → stop and `$rite-plan reslice`.

package/pack/generated/codex/skills/rite-build/reference/output.md

@@ -1,6 +1,7 @@
 # rite-build output
 
 **Slices remain:**
+
 ```text
 Done: built slice <n> — <name>.
 Changed: <files>; state.md, touched-files.md, evidence.md
@@ -12,6 +13,7 @@ Record: .devrites/work/<slug>/evidence.md
 ```
 
 **All built:**
+
 ```text
 Done: built slice <n> — <name>; all slices built.
 Changed: <files>; state.md, touched-files.md, evidence.md

package/pack/generated/codex/skills/rite-build/reference/parallel-batch.md

@@ -0,0 +1,64 @@
+# Parallel batch (`--parallel N`)
+
+Opt-in only. Default `$rite-build` stays [`one-slice-cycle.md`](one-slice-cycle.md).
+
+## Entry
+
+| Input | Behavior |
+| --- | --- |
+| omitted / `--parallel 1` | Serial one-slice |
+| `--parallel N` (**2≤N≤3**) | Parallel when eligible + host pass |
+| non-integer / `N≤0` / `N>3` | Hard refuse (no silent clamp) |
+
+AFK caps `N` by remaining budget. Charge **only after successful integrate**
+(once per integrated green sibling). Abort / integrate-failed → **0**. Running
+lease blocks another `$rite-build`.
+
+## Path-disjoint
+
+Exact project-relative source/test paths only. Normalize `\`→`/`. Reject `..`,
+duplicates, absolutes, `.devrites/**`. Empty pairwise intersection required.
+
+**SSOT:** `devrites-engine check path-disjoint [--root <dir>] [<json-file>|-]`
+(N≥2 only; pass `--root`). Exit `0` → fan-out; else force serial. Inspect-time
+overlap → sibling **gap** → abort.
+
+## Control vs workers
+
+Control owns `.devrites/work/<slug>/` (`parallel-lease.md` + bookkeeping).
+Workers: `.scratch/parallel-wt/<batch>/<slice>/` on
+`devrites/parallel/<slug>/<batch>/<slice>` @ base `B`. Wrights never write
+`.devrites/**`.
+
+Lease: `batch_id`, `created_at`, `base_sha`, `n`,
+`status` (`running|aborted|integrate-failed|complete`), `control_pid_or_session`,
+`slices[]` (`id`, `paths`, `worktree_path`, `branch`, `wright_status`,
+`transfer_commit`).
+
+## Lifecycle
+
+1. Orient/gate; parse N; select ≤N path-disjoint pending slices.
+2. Write lease; freeze `B=HEAD`; `parallel create` worktrees.
+3. Dispatch ≤3 wrights in parallel (cwd=worktree; allowlist; prove `HEAD==B`).
+4. Inspect + fail-on-red → `green|red|gap`.
+5. Any red/gap → **abort** (no partial integrate). All green → serial integrate.
+6. Integrate: `transfer_commit` descends from `B`; `` `<base>..<transfer>` ``
+   path-exact; apply in plan order. Conflict → reset to `B`, `integrate-failed`.
+7. Success: FF control; union `touched-files.md`; update state/evidence; AFK +1
+   per integrated sibling; optional `check candidate`.
+8. Cleanup: success removes worktrees/branches; abort keeps until acknowledged.
+
+## Engine verbs
+
+```text
+devrites-engine parallel create|record-green|abort|integrate|cleanup|status
+devrites-engine parallel lease-write|lease-read|lease-clear
+```
+
+Go is SSOT. Skill calls the engine — never ad-hoc git/bash orchestration.
+
+## Host
+
+Claude: N concurrent spawn_agent wrights (`acceptEdits`, cwd=worktree). Codex: require
+host-explicit concurrent worktree writers + native reconcile; else force serial.
+Never two writers in one worktree; never root-emulated concurrency.

package/pack/generated/codex/skills/rite-build/reference/phase-contract.md

@@ -2,6 +2,7 @@
 
 See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
 [`candidate-integrity.md`](../../devrites-lib/reference/candidate-integrity.md).
+Opt-in `--parallel N` uses [`parallel-batch.md`](parallel-batch.md) instead of steps 2–8.
 
 1. **Orient and gate.** Read core, `.devrites/ACTIVE`, `state.md`, and required
    slice artifacts. Require `Implementation readiness: READY`, its current
@@ -24,14 +25,14 @@ See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
    dispatch the exact `devrites-slice-wright` fresh. Root never writes those product
    paths, wright never widens, and a missing profile stops.
 <!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"Build gate enters or resumes transaction","action":"invoke canonical operation table; reconcile exact result","return":"same slice/checkpoint cursor or Plan/Vet route"} -->
-4. **Inspect the return.** Wait; compare its file list and `git diff --name-only`
+1. **Inspect the return.** Wait; compare its file list and `git diff --name-only`
    with the contract. Reject stale, partial, malformed, or out-of-scope work.
    Preserve user work; source restoration uses the same bounded wright.
-5. **Challenge stood decisions.** For each stood decision, run exact
+2. **Challenge stood decisions.** For each stood decision, run exact
    `devrites-doubt-reviewer` fresh/read-only and record accepted or resolved-rejected
    in `decisions.md`. A missing verdict, principle breach, scope change, or
    irreversible risk blocks.
-6. **Prove without guessing.** Against the frozen pre-slice candidate, inspect
+3. **Prove without guessing.** Against the frozen pre-slice candidate, inspect
    test hunks for deletion, skipping/focus, tautology, or weaker expectations. Dispatch exact
    `devrites-test-analyst` on that immutable diff; missing account or adverse criterion
    verdict is Critical. Run only `test-plan.md` repository/CI commands, capture output,
@@ -47,14 +48,14 @@ See [`one-slice-cycle.md`](one-slice-cycle.md); candidate lifecycle is
    is progress; a different Critical/Important invariant gets its own fingerprint.
    Ask humans only for product decisions,
    irreversible risk, or genuinely human-only access.
-7. **Record.** After green proof, upsert `touched-files.md`'s authoritative candidate
+4. **Record.** After green proof, upsert `touched-files.md`'s authoritative candidate
    manifest from the actual scoped diff with explicit `present`/`deleted` rows;
    update `state.md`, `evidence.md`, and applicable UI/browser evidence. The manifest
    stays mutable until Polish closes it.
    Record stood decisions/dead ends in `decisions.md`; update checked assumptions'
    status/evidence, never leaving a disproved row live. If code reveals a durable
    project rule, propose a reviewed `AGENTS.md`/nearest-doc update, not a scored ledger.
-8. **AFK and reply.** Under `afk-discipline.md`, root charges
+5. **AFK and reply.** Under `afk-discipline.md`, root charges
    exactly once after each green built slice, never below zero; stop before another dispatch at zero, and fail closed
    on malformed budget. Use the reply contract; name the next pending slice or, only
    when all slices are built, `$rite-prove`. Emit no decorative progress renderer or

package/pack/generated/codex/skills/rite-build/reference/wright-dispatch.md

@@ -26,8 +26,8 @@ supported. Regardless of host defaults, the wright's first command must prove ac
 `worktree_base`. Mismatch returns a gap with no write before project reads or baseline proof.
 
 The isolated wright returns one local unpushed `transfer_commit`, its `worktree_base`,
-and exact files. Root proves descendant base, exact `git diff --name-only
-<base>..<transfer>`, no `.devrites/**`/submodule/symlink/unrelated delta, unchanged
+and exact files. Root proves descendant base, exact `git diff --name-only`
+`` `<base>..<transfer>` ``, no `.devrites/**`/submodule/symlink/unrelated delta, unchanged
 source base, and no user-work overwrite. Use only host-native explicit reconciliation;
 never ad hoc copy, cherry-pick, or merge from read-only root. Compare transferred bytes,
 run approved proof, record evidence, then let host remove worktree.
@@ -35,7 +35,10 @@ run approved proof, record evidence, then let host remove worktree.
 Conflict, extra/missing commit, moved base, or cleanup failure is `gap`/STOP:
 preserve the worktree and commit. Without explicit reconciliation, use same-worktree serial.
 Parallel writer work remains forbidden until this serial pilot measures transfer,
-conflict, proof, and review outcomes on both hosts.
+conflict, proof, and review outcomes on both hosts. Opt-in `$rite-build --parallel N`
+(2≤N≤3) is the only exception: path-disjoint fan-out, abort-batch, and control
+`parallel-lease.md` under [`parallel-batch.md`](parallel-batch.md). Same-worktree multi-writer / root-emulated
+worktrees stay forbidden.
 
 ## Prepare
 
@@ -60,6 +63,7 @@ conflict, proof, and review outcomes on both hosts.
 Ask the host for the exact writer in fresh context and wait. Use at most one writer
 across all linked worktrees for this workspace. Never run two writers in one worktree,
 run isolated and same-worktree writers concurrently, or substitute a generic agent.
+Opt-in `$rite-build --parallel N` fans out only under [`parallel-batch.md`](parallel-batch.md).
 
 ## Inspect and prove
 

package/pack/generated/codex/skills/rite-clarify/reference/anti-patterns.md

@@ -0,0 +1,24 @@
+# $rite-clarify anti-patterns
+
+Load this when tempted to skip clarify, assume product choices, or write
+`Decision coverage: CLEAR` before every material row has an owner.
+
+Pack-wide rationalizations: see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+| --- | --- |
+| "We already discussed this in chat." | Chat is not durable decision coverage. Scan topology and record owners in workspace artifacts. |
+| "The answer is obvious — assume it." | Product, scope, policy, and irreversible-risk choices are human-owned unless already recorded in an accepted decision. |
+| "Most rows are clear — good enough for AFK." | Partial/Missing material rows block CLEAR and block AFK arming. |
+| "Skip clarify for this small change." | Clarify is mandatory and adaptive; it may ask no questions, but it still runs the scan. |
+| "I'll clarify during build if needed." | Unowned decisions discovered in build are expensive drift. Close them before plan/vet. |
+
+## Red flags in your own output
+
+- `Decision coverage: CLEAR` with Partial/Missing material rows still open.
+- Product/policy choices recorded without a human packet or cited prior decision.
+- AFK armed or `$rite-define` started before CLEAR is durable.
+- Clarify skipped because the user said they were "in a hurry".

package/pack/generated/codex/skills/rite-customize/SKILL.md

@@ -16,8 +16,9 @@ standalone token occurs in current `$ARGUMENTS`; earlier context cannot activate
 1. Map policy→instruction, reusable work→skill, specialist→agent, external capability→plugin/MCP.
 2. Inspect target/host docs; reuse before copying.
 3. Draft smallest nearest-scope change; do not restate safeguards.
-4. Show path/exact diff; wait.
-5. Write approved artifacts, validate natively, keep no mirror.
+4. For any new or edited skill/agent Markdown, run `devrites-engine check skill-trust <path>` before showing the diff. HIGH findings block; MEDIUM findings need explicit human acknowledgment in the proposal.
+5. Show path/exact diff; wait.
+6. Write approved artifacts, validate natively, keep no mirror.
 
 Here, edit canonical source and generate; never edit derived artifacts.
 

package/pack/generated/codex/skills/rite-define/SKILL.md

@@ -11,7 +11,9 @@ Turn `spec.md` into architecture, vertical slices, traceability, and state. Spec
 what/why; Define owns how. **Do not write code.**
 
 ## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+
 Pull these via `Read` when shaping the plan:
+
 - `development-workflow.md`: small batches, trunk-always-green, definition of done.
 - `principles.md`: the project invariants (`.devrites/principles.md`) the chosen approach must conform to.
 - `documentation.md`: record plan-time decisions and rationale.
@@ -20,6 +22,7 @@ Pull these via `Read` when shaping the plan:
 - `../workspace-artifact-schema.md`: artifact purposes, budgets, IDs, and read triggers.
 
 ## Operating rules
+
 - **Requires a readied spec.** Missing workspace/spec/readiness or open CRITICAL checklist →
   `$rite-spec`; missing/non-`CLEAR` decision coverage → `$rite-clarify`. Never plan it.
 - Apply `afk-hitl.md` ownership. Prefer conventions; source-check new dependencies/design
@@ -40,6 +43,7 @@ Pull these via `Read` when shaping the plan:
   ([`agents.md`](../devrites-lib/reference/standards/agents.md)); root owns choices and canonical files.
 
 ## Workflow
+
 0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`:** the always-on operating rules and anti-rationalizations.
    Resolve the active slug from `.devrites/ACTIVE`, require its `state.md`, and
    re-open `spec.md` and apply `spec-grammar.md`'s Native grammar re-read
@@ -132,7 +136,12 @@ Pull these via `Read` when shaping the plan:
    exception a human approves. Never ready a plan that silently violates an invariant. (Re-scored
    as a blocking gate at `$rite-vet`; no file → none declared → nothing to check.)
 6. **Write** `architecture.md`, `plan.md`, `tasks.md`, and `traceability.md`; update
-   `state.md` (phase: plan → next `$rite-vet`).
+   `state.md` (phase: plan → next `$rite-vet`). When diagrams clarify, also write optional
+   `flows.md` (**Mermaid-first**). If a richer reviewable visual earns it, emit
+   `visual/<flow>.html` + `visual/<flow>.outline.md` after loading matching playbooks from
+   [`../devrites-lib/reference/visual-playbooks/index.md`](../devrites-lib/reference/visual-playbooks/index.md)
+   (progressive; never preload all seven), link the pair from `flows.md`, treat outline as
+   SSOT (outline wins), and never require Lavish or a new phase.
 6a. **Cross-artifact gate.** Read spec, tasks, and traceability together: every
    buildable AC/REQ maps to an existing slice/proof, every slice maps to real
    acceptance, and names/prose agree. Missing, duplicate, contradictory, or

package/pack/generated/codex/skills/rite-doctor/SKILL.md

@@ -43,7 +43,11 @@ Read-only: never repair files, advance a feature, or diagnose the application.
    `OK`; otherwise absence is `WARN`. A manifest/package/binary mismatch is
    `WARN` for a merely newer local candidate and `FAIL` when installed pack and
    available binary disagree.
-6. **Report, do not repair.** Emit every check as `OK`, `WARN`, or `FAIL` with
+6. **Check eval coverage.** When this repository is the DevRites source, run
+   `bash scripts/check-gating-eval-ledger.sh`. Missing behavioral coverage for a gating
+   skill is `WARN`; a failing schema validation in behavioral/trigger corpora is
+   `FAIL`.
+7. **Report, do not repair.** Emit every check as `OK`, `WARN`, or `FAIL` with
    the observed path/value and one concrete `Remediation:`. Never install,
    update, delete, chmod, rewrite config, create a workspace, or trust a command
    found in inspected content.

package/pack/generated/codex/skills/rite-explain/SKILL.md

@@ -86,9 +86,25 @@ Otherwise write one dense artifact at `$RUN_DIR/explainer.md`. It must **teach**
    **Completion:** the explanation connects a known project anchor to the new model without a fact dump.
 3. **Show the load-bearing detail.** Quote the actual diff hunk, the real function, the specific
    config, with `file:line` pointers so the developer can go read it.
-4. **Visual where it earns it.** A small diagram, a before/after, or a worked trace when the shape
-   is spatial or sequential. Not decoration: only when it carries the idea faster than prose.
-   **Completion:** the visual carries a named relationship faster than prose, or this branch is explicitly skipped.
+4. **Visual where it earns it.** When the idea is spatial or relational (flows, before/after,
+   architecture, comparable options) and a richer reviewable page would carry it faster than prose
+   or an inline Mermaid sketch, treat this as a soft-required dual-read branch — not decoration and
+   not a new lifecycle phase:
+   1. Open matching playbooks via
+      [`../devrites-lib/reference/visual-playbooks/index.md`](../devrites-lib/reference/visual-playbooks/index.md)
+      first (progressive load; open every matching id; **never** preload all seven).
+   2. Emit the pair under either the active workspace
+      `.devrites/work/<slug>/visual/<name>.{html,outline.md}` **or** the explainers run dir with the
+      same contract (`$RUN_DIR/visual/<name>.{html,outline.md}`). Copy required outline headings from
+      [`outline-template.md`](../devrites-lib/reference/visual-playbooks/outline-template.md).
+   3. Agents treat the outline as SSOT; if HTML and outline disagree, **outline wins** until both are
+      regenerated. No Lavish runtime (`window.lavish.*`, `data-lavish-*`, poll/queue/share/ht-ml.app).
+   4. In the reply, `Changed` / `Record` may cite the HTML+outline pair. Optionally tip the human to
+      run `devrites-engine open-visual <path-or-name>` (T4 opener; document the tip only).
+   Skip the branch when prose (or a tiny Mermaid/SVG sketch inside `explainer.md`) already carries
+   the named relationship.
+   **Completion:** matching playbooks loaded when taken; dual-read pair written with outline-wins /
+   no-Lavish / no-new-phase; or the branch is explicitly skipped because prose won.
 5. **Human voice.** Follow [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md):
    no throat-clearing, no false-binary contrast, no marketing adjectives. One senior engineer
    explaining to another.
@@ -123,10 +139,10 @@ not force it; offer once.
 
 ```
 Done: explained <the one thing> as a <concept|diff|idea|recap> explainer OR walked through <change> for human review.
-Changed: .devrites/explainers/<date>-<slug>/<explainer.md|walkthrough.md>
-Evidence: grounded in <artifacts/files quoted>; check-in <offered+result | skipped>; walkthrough stops <count>
+Changed: .devrites/explainers/<date>-<slug>/<explainer.md|walkthrough.md>[; visual/<name>.html + visual/<name>.outline.md]
+Evidence: grounded in <artifacts/files quoted>; check-in <offered+result | skipped>; walkthrough stops <count>; visual <pair|skipped>
 Open: <none | next-time topics deferred | check-in awaiting the user>
-Next: <single command — usually back to the calling phase, or $rite-learn if a repo rule surfaced>
-Record: .devrites/explainers/<date>-<slug>/explainer.md
+Next: <single command — usually back to the calling phase, or $rite-learn if a repo rule surfaced; optional tip: devrites-engine open-visual …>
+Record: .devrites/explainers/<date>-<slug>/explainer.md | walkthrough.md | visual/<name>.outline.md
 ↻ Hygiene: /clear after reading; the explainer is on disk
 ```

package/pack/generated/codex/skills/rite-explain/reference/intake.md

@@ -7,7 +7,7 @@ source for classification; the SKILL improvises none of it.
 ## The four shapes
 
 | Shape | The input is… | Grounds in | Composes as | Check-in |
-|---|---|---|---|---|
+| --- | --- | --- | --- | --- |
 | **concept** | a named idea / pattern / technology ("explain optimistic locking", "how does our gate engine work") | this repo's footprint of the concept (codegraph first) + external sources only if they sharpen it | build the mental model from a known part of *this* codebase outward | **checked exercise** |
 | **diff** | a specific change: a ref, a slice, a PR, "this diff" | `git diff` / the hunks + `decisions.md` + `seal.md` for the *why* + `touched-files.md` `Review trail` when present | explainer, or **walkthrough** when the user asks to review/approve/checkpoint the change | **predict-then-reveal** |
 | **idea** | a hypothesis or "what if" with no code yet | the user's framing + prior art (external, date-weighted; year is 2026) | steelman the idea, name its hinge and its failure mode | **checked exercise** |
@@ -18,7 +18,7 @@ source for classification; the SKILL improvises none of it.
 If the user's input carries any of these tokens, they **override** shape inference:
 
 | Token | Meaning |
-|---|---|
+| --- | --- |
 | `diff:<ref>` | force the **diff** shape against `<ref>` (a commit, range, or slug) |
 | `walkthrough:<ref>` | force the **diff** shape and compose a human review walkthrough instead of a teaching explainer |
 | `since:<when>` | force the **recap** shape over the window (`since:1w`, `since:last-ship`, an ISO date) |
@@ -60,6 +60,15 @@ A walkthrough is for human review, not retention. Write it under the normal run
 
 Completion criterion: every concern has at least one clickable repo-relative `path:line` stop, or the walkthrough states why the change has no source stops.
 
+## Visual dual-read (when composition earns it)
+
+If the explainer or walkthrough needs a spatial/relational page, follow the SKILL's
+"Visual where it earns it" branch: load matching playbooks from
+[`../../devrites-lib/reference/visual-playbooks/index.md`](../../devrites-lib/reference/visual-playbooks/index.md),
+emit `visual/<name>.html` + `visual/<name>.outline.md` (workspace or `$RUN_DIR`), treat
+outline as SSOT, and never invent a new phase or Lavish dependency. Classification still
+owns shape; the visual branch does not change which shape you are in.
+
 ### Predict-then-reveal (diff / recap)
 
 1. Pick the single most load-bearing hunk or decision in the explainer.

package/pack/generated/codex/skills/rite-plan/reference/dependency-graph.md

@@ -36,6 +36,9 @@ Mark edges that cross a frontend/backend or service boundary. Those slices shoul
 define the contract first (so both sides can proceed) and trigger `devrites-doubt`
 before standing the interface.
 
+After editing `tasks.md`, run `devrites-engine check task-graph <slug>` before Vet.
+Cycles or unknown dependencies block readiness.
+
 For monorepos/multiple repositories, annotate the proven root and deployable on each node.
 For data/integration changes, include recovery ordering: expand before new writers,
 backfill before contract, consumer compatibility before provider exposure, and monitoring

package/pack/generated/codex/skills/rite-spec/reference/spec-template.md

@@ -119,8 +119,11 @@ status routes Define/Vet/Build/Prove to the named standard without copying it he
 
 ## References
 - `brief.md`: request/outcome/scope; `architecture.md`: placement/integration;
-  `flows.md`: diagrams; `decisions.md`: decisions; `decision-coverage.md`: Clarify
-  topology/verdict; `traceability.md`: Define coverage; `design-brief.md`: UI direction.
+  `flows.md`: Mermaid-first diagrams (optional `visual/<flow>.html`+`.outline.md` companion
+  + link when richer presentation earns it — load playbooks via
+  `devrites-lib/reference/visual-playbooks/index.md`); `decisions.md`: decisions;
+  `decision-coverage.md`: Clarify topology/verdict; `traceability.md`: Define coverage;
+  `design-brief.md`: UI direction.
 
 ## Open questions
 | Question ID | Gate | Question | Impact |

package/pack/generated/codex/skills/rite-spec/reference/state-workspace.md

@@ -15,7 +15,8 @@ Load that schema before creating or updating workspace artifacts.
       brief.md
       spec.md
       architecture.md            # from $rite-define
-      flows.md                   # optional, only when useful
+      flows.md                   # optional Mermaid-first; only when useful
+      visual/                    # optional HTML+outline companions (never readiness)
       decisions.md
       assumptions.md
       questions.md
@@ -38,6 +39,26 @@ Load that schema before creating or updating workspace artifacts.
     <feature-slug>/
 ```
 
+## `flows.md` (optional Mermaid-first)
+
+Write `flows.md` only when sequence/state/data/lifecycle diagrams clarify the feature.
+Keep **Mermaid in `flows.md`** when that is enough. When a richer reviewable presentation
+is needed, **also** emit `.devrites/work/<slug>/visual/<flow>.html` +
+`visual/<flow>.outline.md` and link the pair from `flows.md`.
+
+Before any HTML:
+
+1. Open matching playbooks via
+   [`../../devrites-lib/reference/visual-playbooks/index.md`](../../devrites-lib/reference/visual-playbooks/index.md)
+   (progressive; never preload all seven).
+2. Copy required outline headings from
+   [`outline-template.md`](../../devrites-lib/reference/visual-playbooks/outline-template.md).
+3. Dual-read: agents treat the outline as SSOT; **outline wins** on conflict. No Lavish
+   runtime; this is not a new lifecycle phase and never inflates readiness.
+
+`$rite-spec` may seed a thin `flows.md` when investigation already needs a diagram;
+`$rite-define` owns richer architecture/flow companions beside `architecture.md`.
+
 ## Creation rules
 
 - Create or reuse the slug exactly under the canonical schema's
@@ -45,10 +66,12 @@ Load that schema before creating or updating workspace artifacts.
   contract.
 - `$rite-spec` creates the workspace map, `brief.md`, `spec.md`, `decisions.md`,
   `assumptions.md`, `questions.md`, `state.md`, optional `references.md` /
-  `references/`, and optional `design-brief.md` for UI.
+  `references/`, optional `flows.md` when a diagram already clarifies investigation,
+  and optional `design-brief.md` for UI.
 - `$rite-clarify` adds `decision-coverage.md`.
 - `$rite-define` adds `architecture.md`, `plan.md`, `tasks.md`, and
-  `traceability.md`.
+  `traceability.md`; may add or enrich `flows.md` and optional `visual/` HTML+outline
+  companions when Mermaid alone is not enough.
 - `$rite-vet` adds `eng-review.md` and `test-plan.md`.
 - Later phases add only the artifact they own. Do not create optional files as
   empty placeholders; absence means the phase has not produced that artifact.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",

package/scripts/install-lib.sh

@@ -134,7 +134,7 @@ dr_build_engine() {
   [ -d "$_dr_source_dir/engine" ] && [ -n "$_dr_go_bin" ] || return 1
   _dr_tag="$(dr_release_tag "$_dr_source_dir")"
   [ -n "$_dr_tag" ] || _dr_tag="dev"
-  ( cd "$_dr_source_dir/engine" && GOCACHE="$(dirname "$_dr_out")/go-cache" CGO_ENABLED=0 "$_dr_go_bin" build -trimpath -ldflags "-s -w -X github.com/devrites/devrites/internal/version.Version=$_dr_tag" -o "$_dr_out" . ) 2>/dev/null || return 1
+  ( cd "$_dr_source_dir/engine" && GOCACHE="${GOCACHE:-$(dirname "$_dr_out")/go-cache}" CGO_ENABLED=0 "$_dr_go_bin" build -trimpath -ldflags "-s -w -X github.com/devrites/devrites/internal/version.Version=$_dr_tag" -o "$_dr_out" . ) 2>/dev/null || return 1
   chmod +x "$_dr_out" 2>/dev/null || true
 }