devrites 3.2.28 → 4.0.0

package/pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md

@@ -1,117 +1,42 @@
-# Parallel review dispatch
+# Native review dispatch
 
-This file defines reviewer rosters for `/rite-review` and `/rite-seal`. The shared
-packet, result, capability ladder, concurrency limit, retry, and reconciliation rules live in
-[`standards/agents.md`](standards/agents.md); do not restate them here.
-
-All reviewers read the same **immutable candidate**, but no more than three run
-concurrently. For a larger panel, use awaited batches of at most three; after resource
-or process errors, reduce the batch or run serially. A batch boundary does not permit a
-write.
+Host dispatches; DevRites governs.
 
 ## Roster
 
-`/rite-seal` accounts for all seven roles. `/rite-review` runs the first two.
-Conditional triggers use the listed signals.
+Review: Spec/Code; Seal: all applicable roles.
 
 | Reviewer | Fires | Trigger |
 |---|---|---|
-| `devrites-spec-reviewer` | always | review Spec axis; seal may carry it forward only on the identical candidate |
-| `devrites-code-reviewer` | always | review Code-review axis; seal may carry it forward only on the identical candidate |
-| `devrites-test-analyst` | always at seal | completed feature |
-| `devrites-frontend-reviewer` | conditional | diff touches a component, template, stylesheet, story, route, screen, or design token |
-| `devrites-security-auditor` | conditional | input, auth/authz, data access/storage, external integration, permission, dependency, or secret |
-| `devrites-performance-reviewer` | conditional | spec has a performance budget, or diff adds a query, growing-set loop, render/hot-path work, or material payload |
-| `devrites-devex-reviewer` | conditional | public API, CLI, SDK/export, webhook, config/env, error message, docs, or getting-started path |
-
-Not in this roster: `devrites-simplifier-reviewer` (polish), `devrites-doubt-reviewer`
-(doubt), `devrites-strategy-reviewer` (temper), `devrites-plan-reviewer` (vet),
-`devrites-forge-judge` (build), and `devrites-retrospector` (ship).
-
-## Hit-rate gating
-
-Before conditionals, run:
-
-```bash
-devrites-engine reviewer-stats report
-```
-
-- `run`, `run (always-on)`, or `run (insurance — never gated)`: apply the roster.
-- `gate-candidate`: a conditional produced zero surviving findings in its last 10+
-  dispatches. Record a skip with `gated: zero surviving findings in <N> dispatches`.
-- `--full`: dispatch every triggered reviewer despite gating.
-
-Always-on reviewers and insurance reviewers (security and doubt) are never hit-rate
-gated. After reconciliation, record each dispatched reviewer's surviving
-Critical+Important count:
-
-```bash
-devrites-engine reviewer-stats record devrites-<x>-reviewer <count> <slug>
-```
-
-## Reviewer packet
-
-Create `agent-packet/v1` per `standards/agents.md`. In addition to the common fields:
-
-```yaml
-objective: Audit the active feature on <axis>; derive expected behavior independently.
-inputs:
-  - path: .devrites/work/<slug>/spec.md
-    purpose: acceptance contract
-  - path: .devrites/work/<slug>/touched-files.md
-    purpose: feature boundary
-  - path: <scratch_root>/candidate.diff
-    purpose: reviewed candidate
-scope:
-  in: [<axis-specific workspace paths>, <touched source/test paths>]
-  out: [author reasoning, sibling findings, unrelated repository debt]
-  allowed_repo_writes: []
-```
-
-Tell the role to apply its documented discipline and return `payload.type:
-review-findings`, one finding per line, labeled Critical / Important / Suggestion /
-Nit / FYI and anchored to `file:line` plus the spec criterion or observed command.
-The exact result `CANNOT-VERIFY: <requirement> — <why>` is never a pass.
-
-Before dispatching `devrites-devex-reviewer` in measured mode, the root runs the
-documented quickstart in an isolated clean checkout and adds immutable commands,
-timings, output, candidate identity, and log hashes to the packet. Before
-dispatching `devrites-performance-reviewer`, the root supplies the immutable diff
-and any already-authorized measurement artifacts. Reviewers validate these inputs;
-their read-only identity never executes quickstarts, builds, browser runs, or
-assignment-only shell setup.
-
-Dispatch rules:
-
-- Fresh-context dispatch through the capability ladder; one packet per reviewer.
-- No author context, sibling findings, severity coaching, or plan justification.
-- Feature scope is `touched-files.md` plus the frozen diff.
-- Await every required batch before any write or verdict. Never background/detach.
-
-## Account for every reviewer
-
-Log exact agent names as decisions are made:
-
-```bash
-devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer
-devrites-engine footprint log <slug> skip devrites-<x>-reviewer
-devrites-engine footprint roster <slug>
-```
-
-`roster` rc=3 means an unaccounted reviewer: dispatch or record why it does not apply.
-rc=1 means an always-on skip; this is valid only for an unchanged-candidate
-carry-forward. A required reviewer that cannot be dispatched blocks the phase.
-
-## Reconciliation
-
-1. Preserve each valid report verbatim under `## <axis>` in `review.md`/`seal.md`.
-2. Surface contradictions explicitly; the root decides them.
-3. Keep the shared five-label scale. The simplifier's Suggestion/Nit/FYI subset is valid.
-4. Resolve every `CANNOT-VERIFY` before the gate or retain it as a gap.
-5. Add a deduped roll-up only after the verbatim record. Mark matching `file:line`
-   findings from two or more axes as consensus; do not hide lone findings.
-6. Apply the caller's gate; do not invent a composite score.
-
-Every panel reviewer runs at the ceiling or inherited tier. If the named role is
-unavailable, use the universal ladder. If no fresh-agent rung is available, stop for
-HITL; never execute the reviewer in the root context.
+| `devrites-spec-reviewer` | always | acceptance/scope |
+| `devrites-code-reviewer` | always | implementation correctness |
+| `devrites-test-analyst` | seal | completed feature |
+| `devrites-frontend-reviewer` | conditional | UI/route/screen/style/design-token change |
+| `devrites-security-auditor` | conditional | input/auth/data/permission/dependency/integration/secret |
+| `devrites-performance-reviewer` | conditional | performance budget or hot path/query/growing set |
+| `devrites-devex-reviewer` | conditional | public API/CLI/SDK/webhook/config/error/docs/onboarding |
+
+Also: `devrites-simplifier-reviewer`, `devrites-doubt-reviewer`,
+`devrites-strategy-reviewer`, `devrites-plan-reviewer`, or `devrites-retrospector`.
+
+## Dispatch contract
+
+1. Freeze one candidate; give each reviewer the same spec, paths, and diff.
+   Parallelize only when writes/state/locks/tool sessions/scarce resources
+   (ports/processes/quotas/FDs/browsers/MCP) are compatible. Frozen read-only
+   usually is; pressure requires batches or serial work.
+2. Ask for each exact named agent in fresh context; omit native syntax and
+   `agent_type`/`task_name`/`fork_turns` from the instruction.
+3. Wait for all applicable results before reconciling.
+4. Apply [`agents.md` § Result admission](standards/agents.md#result-admission)
+   and dedupe by evidence/root cause. Account for all seven in
+   `review.md`/`seal.md`: `Outcome:` plus admitted account, or
+   `Not-applicable: <inspected-scope reason>`. Spec/Code may cite unchanged
+   `review.md`; persist no dispatch telemetry.
+5. Missing profile, null/failure, or malformed output is a `gap`; never
+   infer approval or substitute inline review.
+
+On exhaustion/contention: stop spawning; collect running results; batch/serialize.
+Never restart/orphan the cohort or infer approval.
+
+Reviewers are read-only; accounts store evidence, never telemetry.

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

@@ -1,126 +1,59 @@
 # DevRites completion reply contract
 
-Use this for every user-facing, workspace-operating `rite-*` skill. The chat reply is
-a compact status summary; durable detail belongs in the phase artifact
-(`spec.md`, `plan.md`, `eng-review.md`, `evidence.md`, `polish-report.md`,
-`review.md`, `seal.md`, `ship.md`, and related records).
+Use the host's normal response. Do not run a progress renderer, emit session
+telemetry, assign a health score, or repeat state already visible in the durable
+artifact.
 
-Before the final reply, persist the phase event, then render the deterministic
-progress chrome:
-
-```bash
-devrites-engine timeline log run-finished \
-  --slug "$(cat .devrites/ACTIVE 2>/dev/null)" \
-  --outcome "<passed|blocked>" \
-  --execution-mode named \
-  --guard-strength n/a \
-  --reason-id "<stable DRV-* reason for the result>" \
-  --host "<claude|codex>" \
-  --evidence "<project-relative primary artifact>"
-devrites-engine budget
-devrites-engine progress
-```
-
-If the phase produced a quality verdict (review, prove, polish, seal, ship), also
-record the evidence-backed health signal before `progress`:
-
-```bash
-devrites-engine health record <0..10> "<evidence-backed label>" --note "<primary check or blocker>"
-```
-
-Skip `timeline` / `health` only when the skill is explicitly workspace-less or
-read-only and has no active `.devrites` workspace.
-
-Do not restate the slice meter or flow ribbon in prose. Keep the default reply to
-roughly 8-10 lines after the progress footer.
-
-## Default completion
+Keep the reply compact and evidence-backed:
 
 ```text
-Done: <phase result in one sentence>
-Changed: <artifact(s) written/updated, or "workspace only">
-Evidence: <checks/proof/artifact pointer, or "not applicable">
-Open: <none | non-blocking questions or follow-ups>
-Next: <exactly one recommended command>
+Done: <result in one sentence>
+Changed: <artifact or source paths>
+Evidence: <commands and observed outcomes, or not applicable>
+Open: <none | unresolved items>
+Next: <one recommended action>
 Record: <primary durable artifact path>
-↻ Hygiene: <clear/compact/handoff advice, one line>
 ```
 
-Rules:
-- Use this default form only for a green, non-blocking result. If proof, a verdict,
-  or a required decision is missing, use `Awaiting human`, `Stopped / blocked`, or
-  `NO-GO`; do not label the phase `Done` or advance it.
-- `Next:` contains exactly one recommended command. Put alternates in `Open:` or an
-  `Alternative:` line only when the phase needs one.
-- Use `Evidence: not applicable` only when the phase truly does not verify runtime
-  behavior, such as spec or plan creation.
-- Claims such as "proved", "reviewed", "sealed", "shipped", and "all slices built"
-  must point to evidence or an artifact.
-- Use stable labels: `Done`, `Changed`, `Evidence`, `Open`, `Next`, `Record`,
-  `↻ Hygiene`.
-- Status symbols are optional; never rely on color or emoji alone. Pair them with
-  explicit text labels such as `Done`, `Stopped`, `Awaiting human`, `NO-GO`, `GO`,
-  or `Shipped`.
-
-## Awaiting human
+If a required decision, proof, or invariant is missing, use one of these states
+instead of `Done`:
 
 ```text
-Awaiting human: <qid> · <gate> · <slice/phase>
-
-Question
-  <question>
-
-Recommended
-  1. <option 1 + short reason>
-
-Other options
-  2. <option 2>
-  3. <option 3 if any>
-
+Awaiting human: <question id and gate>
+Question: <exact decision needed>
+Recommended: <one option and reason>
 Resume: /rite-resolve <qid> "<answer>"
 Record: .devrites/work/<slug>/questions.md
-↻ Hygiene: no /clear until the answer is persisted
 ```
 
-## Stopped / blocked
-
 ```text
 Stopped: <reason>
-Blocking: <specific blocker>
-Why: <one-line impact>
-Fix: <single command or action>
+Blocking: <specific invariant>
+Fix: <one action>
 Record: <artifact path>
-↻ Hygiene: /compact (<topic>) if fixing now; /clear if stopping
 ```
 
-## NO-GO
-
 ```text
-NO-GO: <short verdict>
-Blockers: <count + top 1-3 blockers>
-Fix: <single next command>
+NO-GO: <verdict>
+Blockers: <top blockers>
+Fix: <one action>
 Record: .devrites/work/<slug>/seal.md
-↻ Hygiene: /compact (seal blockers) if fixing now; /clear if stopping
 ```
 
-## GO
-
 ```text
 GO: feature cleared to ship
-Follow-ups: <none | non-blocking count>
+Follow-ups: <none | count>
 Next: /rite-ship
 Record: .devrites/work/<slug>/seal.md
-↻ Hygiene: /clear before /rite-ship
 ```
 
-## Shipped
-
 ```text
 Shipped: <feature>
-Commit: <sha> on <branch>
-Tag/PR: <value | none>
-Acceptance: <n>/<total> proven
-Archived: .devrites/archive/<slug>/ · ACTIVE cleared
+Commit: <sha and branch>
+Acceptance: <proven count>
+Archived: .devrites/archive/<slug>/
 Record: .devrites/archive/<slug>/ship.md
-↻ Hygiene: /clear
 ```
+
+Claims such as proved, reviewed, sealed, shipped, or complete must point to real
+output or an artifact. Use exactly one recommended next action.

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

@@ -1,10 +1,13 @@
 # DevRites rules
 
-These stack-agnostic rules ship under `.claude/skills/devrites-lib/reference/standards/`. Project-specific conventions win where they exist.
+Stack-agnostic rules: `.claude/skills/devrites-lib/reference/standards/`.
+[`core.md` § Precedence](core.md#precedence) governs: repository conventions
+select technical form only inside its safety, source-writing, and evidence gates.
 
 ## Loading model
 
-Every workspace-operating `rite-*` skill reads [`core.md`](core.md) first. Load the smallest topic file needed for the current step; each file owns its full rule.
+Each workspace rite reads [`core.md`](core.md); then load only the current
+topic's owner.
 
 | Rule | Load when |
 |---|---|
@@ -41,4 +44,4 @@ Every workspace-operating `rite-*` skill reads [`core.md`](core.md) first. Load
 | `browser-proof-checklist.md` | UI behavior needs browser proof. |
 | `security-checklist.md` | Auth, input, data, or integration work needs a compact security sweep. |
 
-These files guide judgment. Workflow skills and engine gates own enforcement.
+These guide judgment; workflows and engine gates enforce.

package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md

@@ -1,8 +1,8 @@
 # AFK & HITL: the pause/resume contract
 
-This file defines DevRites's two run modes. Every `rite-*` and `devrites-*` skill that
-might pause for a human reads from this contract; `/rite-build`, `/rite-status`,
-`/rite-resolve`, and `devrites-doubt` are the primary callers.
+Defines two modes for `rite-*`/`devrites-*` skills that may pause; main
+callers are `/rite-build`, `/rite-status`, `/rite-resolve`, and
+`devrites-doubt`.
 
 The contract uses one sentinel, one queue, and one resume verb.
 
@@ -10,7 +10,7 @@ The contract uses one sentinel, one queue, and one resume verb.
 
 - **HITL (default):** human is present. At a gap/checkpoint the skill **asks inline** via
   the harness `AskUserQuestion` tool: a ranked **option set** (recommended first, each with
-  dimension-tagged rationale; see [Option set](#option-set--how-every-gap-is-presented)). The
+  dimension-tagged rationale; see [Option set](#option-set-how-every-gap-is-presented)). The
   human picks; the skill records the pick to `questions.md` (`answered`) + `decisions.md` and
   **continues in place: no `/rite-resolve` round-trip**. `/rite-resolve` is only for answering
   **async** (a pause that already stopped the session) or in **batch**.
@@ -25,9 +25,8 @@ The contract uses one sentinel, one queue, and one resume verb.
   ceiling (and every irreversible-risk item) pause and queue a `questions.md` entry for
   `/rite-resolve`.
 
-`.devrites/AFK` presence is authoritative for run mode; gate-deciding skills re-read the
-sentinel at decision time (the shared preamble derives the mode from it). There is no
-`state.md` run-mode field to drift out of sync.
+`.devrites/AFK` presence is authoritative for run mode; gate-deciding skills re-read
+it at decision time. There is no `state.md` run-mode field to drift out of sync.
 
 ## The sentinel: `.devrites/AFK`
 
@@ -40,9 +39,22 @@ allow_gates: [advisory, validating]  # gate severities AFK auto-handles (auto-pi
 ```
 
 The file is **read-only config**: never rewritten in place. `max_slices` is the initial
-budget; the mutable remaining count lives in `state.md` as `AFK slices remaining: <n>`,
-seeded from `max_slices` on the first AFK build and decremented by `devrites-engine tick-afk` (which
-exits non-zero at 0, forcing a HITL stop). The cap is enforced by the script, not prose.
+budget; the mutable remaining count is the `state.md` cursor
+`afk_slices_remaining` (`AFK slices remaining: <n>` in the released bullet
+form), owned by the controlling root. Recognize either spelling and preserve
+the existing table or bullet presentation. Before dispatch, a configured
+`max_slices` and any existing remaining value must be decimal nonnegative
+integers; malformed or negative values fail closed. The pending → built state transition spends
+exactly one slice: on the first green slice write `max_slices - 1`, otherwise
+write `remaining - 1`, never below zero. Re-reading an already built slice does
+not spend again. At zero, stop before the next dispatch.
+
+An orchestrator that can derive a stricter budget only after planning may pre-seed
+`afk_slices_remaining` in `state.md` before the first dispatch instead of rewriting the
+sentinel. It uses the minimum of pending work and every configured/explicit cap. An
+existing counter may be lowered but never increased or reinitialized. Once present, that state
+counter is the effective remaining budget even when the read-only sentinel omits
+`max_slices`.
 
 Missing keys fall back to defaults:
 
@@ -81,18 +93,17 @@ Wherever a gap, checkpoint, or non-trivial decision surfaces (`/rite-spec`, `/ri
 **ranked option set**, never a single bare guess:
 
 - **2-4 concrete options**, the **recommended one first**, labelled `(Recommended)`.
-- Each option carries a **one-line rationale tagged by the dimensions that matter**:
-  `logic · infra · business · architecture` (add `security` / `UX` / `risk` when in scope).
-  Name the trade-off as well as the choice.
+- Each option has a **one-line, dimension-tagged rationale**: `logic · infra · business ·
+  architecture` (add `security` / `UX` / `risk` in scope) and trade-off.
 - Always include an escape hatch (`Something else — I'll describe it`).
-- The recommendation reflects what's best for *this* project (its conventions, stack, scale,
-  domain), not a generic default.
+- With more than four materially distinct choices, first ask a discriminating question or use
+  sequential packets, then obtain final confirmation. Materially distinct options MUST NOT
+  be silently dropped, merged, or preselected to fit the UI.
+- Recommend for project conventions, stack, scale, and domain, not a generic default.
 
-**HITL** renders the set via `AskUserQuestion` (recommended option first; rationale in each
-option's description); the human's pick resolves the gate **in place**. **AFK** auto-picks
-option 1 (the recommendation) for gates it may auto-handle. Either way the chosen option is
-recorded verbatim. Keep the **rejected options in `questions.md`** so the record includes
-the alternatives considered.
+**HITL** renders the set via `AskUserQuestion`; the human's pick resolves the gate **in place**.
+**AFK** auto-picks option 1 for gates it may auto-handle. Record the chosen option verbatim and
+keep the **rejected options in `questions.md`**.
 
 ## Decision ownership: search before asking
 
@@ -156,14 +167,8 @@ Rules:
 - The file is the audit trail. Don't edit answered/dropped entries: open a new qid that
   references the old one (`supersedes: q-...-OLD`) and resolve it.
 
-Destructive Git uses a narrower engine-owned question:
-`schema: devrites-git-authority/v1`, `kind: destructive-git-once`, the exact
-operation digest, sorted classifier reason IDs, `requested_at`, `expires_at`, and
-`answer_contract: Authorize once`. Run `/rite-resolve <qid> "Authorize once"`;
-then retry within 15 minutes. `git-guard` consumes the grant before the tool runs,
-so a failed tool call still spends it. Never hand-edit, broaden, reuse, or copy
-this authority record. Ambiguous shell forms cannot use it: rewrite them as a
-direct literal Git command.
+AFK never authorizes destructive Git. The native host permission/sandbox
+boundary owns any such request and requires explicit user approval.
 
 ## `state.md` `Awaiting human` block
 
@@ -199,7 +204,7 @@ stopped the session (an AFK blocking/escalating/irreversible queue, or a HITL pa
 walked away from), plus `--batch`. In an **interactive HITL** session the skill resolves the
 `AskUserQuestion` pick **in place** (the same `questions.md` `answered` write + `state.md`
 clear), so you don't type `/rite-resolve` for gaps you answer live. Both paths flip
-`status: open → answered` and clear `Awaiting human` through the **same `devrites-engine resolve` writer**:
+`status: open → answered` and clear `Awaiting human` through the **same `devrites-engine state resolve` writer**:
 one source of truth, two entry points (live pick vs typed verb). Use the writer;
 manual edits are never destructive-operation authority.
 
@@ -226,15 +231,19 @@ finding by the decision-ownership rule above: human-owned uncertainty becomes a
 question; an objective technical finding becomes a recorded blocker with its required
 changes, not a request for permission to retry.
 
-## Retry cap, stuck loops, and self-resolve
+## Retry cap, no-progress loops, and self-resolve
 
-- **Cap retries:** three total attempts per root cause across wright and recovery, carrying the
-  failure and dead ends; never rerun an unchanged check.
+- **Cap retries:** three total attempts per root cause across wright and recovery is a hard
+  cap. The caller and recovery loop count every failed attempt with the same
+  causal fingerprint from the current context and recorded `## Dead ends` /
+  `evidence.md`. Persist the exact failure and attempted idea after each; never
+  make a fourth unchanged or related attempt for the same root cause. There is
+  no recovery counter file or command.
 - **Classify exhaustion:** human-owned contract/risk/access gaps open their gate. Otherwise
   preserve reproduction/dead ends, set `Status: blocked` and `Next step: /rite-plan unblock`,
   with no question or `/rite-resolve`.
-- **Stop loops even in AFK:** `devrites-engine stuck` ends the build and applies that same
-  classification regardless of `allow_gates`.
+- **Reassess no-progress loops:** After repeated attempts without progress, stop and
+  reassess the failure and approach rather than continuing blindly.
 - **Resolve agent-owned questions first.** Before raising a question, try to answer it from the code, the docs,
   or `decisions.md`. Communicate only for a blocked environment, a deliverable to hand over,
   critical info you genuinely can't access, or a credential / permission you lack. This narrows