devrites 5.10.2 → 5.12.0

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

@@ -0,0 +1,417 @@
+# AFK & HITL: the pause/resume contract
+
+> Applies when: any rite/devrites skill that can pause for a human or run unattended; irreversible-risk list, budgets, recovery accounting.
+
+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.
+
+## Contents
+
+- [Run modes](#run-modes)
+- [The sentinel: `.devrites/AFK`](#the-sentinel-devritesafk)
+- [Unattended resource envelope](#unattended-resource-envelope)
+- [The four gates](#the-four-gates)
+- [Option set: how every gap is presented](#option-set-how-every-gap-is-presented)
+- [Decision ownership: search before asking](#decision-ownership-search-before-asking)
+- [Irreversible-risk list (always pause)](#irreversible-risk-list-always-pause)
+- [`questions.md` schema](#questionsmd-schema)
+- [`state.md` `Awaiting human` block](#statemd-awaiting-human-block)
+- [The resume verb: `/rite-resolve`](#the-resume-verb-riteresolve)
+- [AFK exception for discretionary pauses](#afk-exception-for-discretionary-pauses)
+- [Retry cap, no-progress loops, and self-resolve](#retry-cap-no-progress-loops-and-self-resolve)
+- [What the rule does NOT cover](#what-the-rule-does-not-cover)
+- [Cross-reference](#cross-reference)
+
+## Run modes
+
+- **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
+  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**.
+  **If the current surface has no interactive question tool** (Codex outside Plan mode:
+  `request_user_input` is Plan-mode-only.) Render the same option set as a plain numbered
+  list in chat and **end the turn**. The human's reply is the selection. Auto-picking an option
+  is **AFK's contract, gated by the `.devrites/AFK` sentinel**: a missing tool never
+  converts a HITL gap into a self-answered one.
+- **AFK:** `.devrites/AFK` is present. For any gate AFK may auto-handle (severity in
+  `allow_gates`), the skill **auto-picks the recommended option** (option 1 of the set), records
+  it (`gate: advisory` + a `decisions.md` ADR), and continues unattended. Gates above the
+  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
+it at decision time. There is no `state.md` run-mode field to drift out of sync.
+
+## The sentinel: `.devrites/AFK`
+
+Presence = AFK active. The file body is optional YAML:
+
+```yaml
+max_slices: 10                       # whole-workspace writer budget; seeds state.md remaining count
+max_agents: 32                       # native agent dispatches in one host activation
+max_minutes: 120                     # wall-clock minutes in one host activation
+max_review_queue: 8                  # unresolved review/gate items admitted before fan-out stops
+# max_tokens: 200000                 # optional stricter host-observed token cap
+# max_cost_usd: 10                   # optional stricter host-observed cost cap
+notify: "ntfy.sh/my-topic"           # shell command; examples: .devin/skills/rite-build/reference/afk-discipline.md
+allow_gates: [advisory, validating]  # gate severities AFK auto-handles (auto-picks the recommended option)
+continue_sequence: true              # after Seal GO, open the next recorded continuation
+max_workspaces: 5                    # workspaces one armed sequence may open
+max_parallel: 10                     # unattended default cap; `--parallel N` on this invocation wins and may rewrite only this field
+```
+
+The file is **read-only config**: never rewritten in place, except `/rite-autocomplete --parallel N` writes or replaces only `max_parallel: N`. `max_slices` is the initial
+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`.
+
+### Sequence continuation (`continue_sequence`, `max_workspaces`)
+
+`continue_sequence: true` lets one armed run open the next **recorded** continuation
+after a `Seal GO` instead of stopping. Absent means `1` — the current workspace only;
+an existing sentinel never receives the default implicitly. `max_workspaces` is the
+sequence budget (nonnegative decimal, fail closed): spend one when a new workspace is
+opened, never when resuming the current one. `max_slices` stays **per workspace** —
+each new workspace's `state.md` seeds its own `afk_slices_remaining`.
+
+The chain lives in root-owned `state.md` cursor fields, not in chat:
+`sequence_parent` (the immediately preceding workspace slug), `sequence_position`
+(1-based ordinal), `sequence_workspaces_remaining` (slots the chain may still
+open after this workspace), and — on the release milestone only —
+`sequence_role: release`. Seeding is exactly-once because the values are
+derived, not remembered: a continuation's fields are computed from its recorded
+parent and the parent's counter at creation, and a resumed run that finds a
+continuation workspace missing the fields re-derives the same values from its
+`brief.md` parent/position plus the parent's counter — never a second charge. A
+workspace without a recorded parent/position is not a sequence member; the
+counter only decreases, malformed values fail closed, and `0` opens nothing.
+`sequence_role: release` makes `check candidate` and `check seal` require the
+candidate manifest to cover the whole recorded chain — run
+`devrites-engine state merge-manifest <slug>` before Prove.
+
+- Only continuations recorded in the parent's `decisions.md` sequence
+  ([slicing.md § Continuation workspaces](../../../rite-plan/reference/slicing.md#continuation-workspaces))
+  qualify; no recorded next entry, or the cap/review-queue bound reached, stops
+  with the winning reason.
+- Milestones are **not** shipped: they stay sealed and unarchived in `.devrites/work/`
+  with `Next step: /rite-ship` preserved. Local `WIP(<slug>):` checkpoints still
+  land ([checkpoint.md](../../../rite-build/reference/checkpoint.md)), so the tree
+  stays clean and crash-safe.
+- Git stays human-gated. The release ship is one disclosed plan, one literal `GO`, and
+  one native approval; it collapses the sequence's `WIP` commits into the single
+  release commit and may archive the sealed predecessors.
+- Every human-owned, safety, access, exhaustion, and `NO-GO` condition still stops the
+  run exactly as without this field.
+
+`max_parallel` is the unattended default batch cap only when this invocation does
+not contain `--parallel N`; `1` forces the serial cycle only in that default
+case. An exact `--parallel N` on `/rite-autocomplete` or `/rite-build` is the
+batch cap for this run: do not consult leftover sentinel `max_parallel`, and do
+not treat `max_parallel: 1` as serial. `/rite-autocomplete --parallel N` writes
+or replaces only that field so later ticks keep the cap; `/rite-build --parallel N`
+wins for that invocation without rewriting the sentinel. Never write `max_slices`
+from `--max-slices`. **Failing case:** `/rite-autocomplete --parallel 5` honors a
+leftover `max_parallel: 1` and stays serial.
+Unattended runs take the largest eligible set ≤ that cap and recompute after
+every completed round (serial slice or parallel integrate)
+([parallel-batch.md § Dynamic selection and re-batching](../../../rite-build/reference/parallel-batch.md#dynamic-selection-and-re-batching)).
+
+## Unattended resource envelope
+
+AFK writer admission needs a bounded input queue, effective slice cap, and valid
+`max_agents`, `max_minutes`, and `max_review_queue`. Existing sentinels
+that declare writer admission but miss/malform these fail closed; cold resume keeps the
+state-owned slice counter. A leftover `expires_at` is ignored and never rewritten.
+Read-only watchers use equivalent native caps from [`loop-operations.md`](loop-operations.md).
+
+`max_agents` counts every leaf in the native activation, including failures and
+parallel branches; do not add dispatch telemetry to `.devrites/`. `max_review_queue`
+counts open validating questions plus unresolved admitted Critical/Important findings.
+Above it stop; at it run only reconciliation that reduces the queue. Optional
+`max_tokens`/`max_cost_usd` lower enforceable native caps; if declared but unobservable, stop.
+
+Numeric limits are nonnegative decimals. Before costly checks, fan-out, or writing,
+run cheap readiness, reject overlap, count queue, and confirm agent/time/token/cost
+headroom; re-check after every result. Never start one call that can exceed remaining
+headroom. Agent/time/token/cost counters are per native activation and start fresh only
+for a genuinely new activation. Slices, recovery attempts, and current
+review queue remain durable/recomputed across wakes. Persist each activation stop and
+checkpoint before notification.
+
+New sentinels write no `expires_at` and no notification/token/cost cap.
+Post-Vet pending count may lower slices. Existing files
+never receive missing defaults implicitly.
+
+To leave AFK, delete the file. The next skill invocation reverts to HITL.
+
+## The four gates
+
+Every `Mode: HITL` slice declares a `Gate:` and an `SLA:`. See
+[`.devin/skills/rite-define/reference/gates.md`](../../../rite-define/reference/gates.md)
+for the full taxonomy. Summary:
+
+| Gate | Stakes | Pause? | SLA | AFK auto-handle when in `allow_gates`? |
+|---|---|---|---|---|
+| advisory | low | no | none | yes (log + proceed) |
+| validating | medium | async | 4h | yes (build + queue, no merge until resolved) |
+| blocking | high | sync | 15m | **no** (always pauses) |
+| escalating | novel pattern | sync to specialist | 24h | **no** (always pauses) |
+
+`blocking` and `escalating` always pause for HITL and for AFK `/rite-build`,
+regardless of `allow_gates`.
+
+**Autocomplete exception.** While `/rite-autocomplete` is the controlling
+caller, an open `gate: blocking` question that already carries a ranked
+recommended option (`proposed:` or option 1 labelled `(Recommended)`) is not a
+user handoff: the orchestrator auto-picks that option through
+`devrites-engine state resolve` and continues, including internal Spec Drift
+Guard when the answer changes ownership or acceptance. Escalating,
+irreversible-risk, access, and blocking questions with no recommended option
+still pause. Putting `blocking` in `allow_gates` does not replace this resolve
+step: an unanswered blocking question still fails Seal.
+
+An open `gate: validating` entry is **merge-blocking by definition**: at `/rite-seal` any
+`questions.md` entry with `gate: validating` and `status: open` is a NO-GO, regardless of
+its behavior impact. A slice marked `built (pending review)` is **not done** until that
+validating gate resolves.
+
+## Option set: how every gap is presented
+
+Wherever a gap, checkpoint, or non-trivial decision surfaces (`/rite-spec`, `/rite-clarify`, `/rite-define`,
+`/rite-build`, `/rite-temper`, `/rite-vet`, `devrites-doubt`, `devrites-interview`), present a
+**ranked option set**, never a single bare guess:
+
+- **2-4 concrete options**, the **recommended one first**, labelled `(Recommended)`.
+- 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 — describe it`).
+- 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`; 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
+
+A gate is human only when its remaining choice is human-owned. First search live code,
+project/decision docs, and authoritative dependency sources; make and record reversible
+implementation/test choices. Ask only about product, scope, acceptance, architecture policy,
+irreversible risk, or human-only access/action.
+
+Objective test/build/tool failure runs bounded `devrites-debug-recovery`; fix it or record a
+technical blocker. Never ask permission for another attempt, test, parser repair, or probe.
+Close decisions at the earliest informed phase: product in spec, coverage in clarify,
+scope/risk in temper, architecture/dependencies in define, and proof/toolchain in vet. Build
+keeps only unavailable-pre-code or mandatory action-time checkpoints.
+
+## Irreversible-risk list (always pause)
+
+The following always invoke the checkpoint protocol, regardless of `Mode`, `Gate`, or
+`allow_gates`:
+
+- Destructive data migration (drop column, drop table, irreversible backfill).
+- Auth / authz boundary change.
+- Public API break (response shape, removed endpoint, changed status code semantics).
+- External-service contract change.
+- Filesystem destruction outside the workspace.
+
+When a pause clears and you proceed with a destructive migration, a removal, or a
+public-API break, take the **safe path** the gate stopped you for: expand→contract,
+prove the old path unused before removing it, and a rollback for every destructive step
+([`deprecation.md`](deprecation.md)). The gate requires the safe path; it does not
+cancel the work.
+
+By default, AFK widens what's *automatic*; it never widens what's *irreversible*.
+
+Red checks remain hard non-advance build gates, but are not inherently irreversible or
+human-owned; bounded recovery owns them.
+
+## `questions.md` schema
+
+Append-only. One entry per qid. Format:
+
+```markdown
+## q-YYYY-MM-DD-NNN
+status: open | answered | dropped
+slice: <slice id, e.g. 03-list-endpoint, or "spec" / "plan">
+gate: advisory | validating | blocking | escalating
+question: <one crisp sentence>
+options: |                                    # ranked option set; recommended FIRST (see "Option set")
+  1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+  2. <alternative> — <dimension-tagged rationale + trade-off>
+  3. Something else — describe it
+proposed: <the recommended option restated — the HITL default + the AFK auto-pick>
+raised_at: <iso>
+answered_at: <iso, when status flips off "open">
+answer: <chosen option (or human's verbatim reply / drop reason)>
+```
+
+Rules:
+- `NNN` is sequential per date: the next-available 3-digit integer.
+- `status: open` is the only state `/rite-resolve` can mutate; `answered` and `dropped`
+  are terminal.
+- 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.
+
+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
+
+When a HITL gate fires, `/rite-build` writes:
+
+```markdown
+- Status: awaiting_human
+- Next step: /rite-resolve <qid> "<answer>"
+
+## Awaiting human
+- qid: <q-...>
+- gate: <gate>
+- question: <crisp text>
+- proposed: <agent's tentative answer>
+- raised_at: <iso>
+- blocking_slices: [<slice ids that cannot advance>]
+```
+
+`/rite-resolve` removes the block on success and flips `Status: running`.
+
+## The resume verb: `/rite-resolve`
+
+Three shapes:
+
+```
+/rite-resolve <qid> "<answer>"
+/rite-resolve --drop <qid> ["<reason>"]
+/rite-resolve --batch <path-to-yaml>
+```
+
+`/rite-resolve` is the canonical writer for **async** resume: a gate that already paused and
+stopped the session (an AFK blocking/escalating/irreversible queue, or a HITL pause the human
+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 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.
+
+When `/rite-resolve` does resume a stopped session, the skill does **not** auto-run the next
+`/rite-build`. The user types the next command explicitly so:
+- A `/rite-plan repair` can land first if the answer changes scope.
+- The user sees the workspace state before resuming.
+- Each verb has one mutation; chaining is a hidden side-effect.
+
+## AFK exception for discretionary pauses
+
+With `.devrites/AFK`, apply decision ownership first. Accepted in-scope technical
+corrections return to the caller for repair/verification; severity blocks acceptance,
+not authorized repair. Never silently accept a defect or broaden existing approval.
+
+Discretionary ceilings apply only to
+human-owned trade-off/risk decisions; accepted technical corrections do not enter
+these branches. Compare Suggestion/Nit/FYI→advisory, Important→validating,
+Critical→blocking against advisory < validating < blocking < escalating:
+
+- Within the slice's `Gate:` and `.devrites/AFK` `allow_gates`: record advisory in
+  `questions.md`, trade-off in `decisions.md`, proceed.
+- Above ceiling, missing authority, or unapproved irreversible risk: record blocking
+  question, `Status: awaiting_human`, fire `notify:`, STOP.
+
+Recovery uses only the [retry contract](#retry-cap-no-progress-loops-and-self-resolve).
+
+## Retry cap, no-progress loops, and self-resolve
+
+Owns all phase recovery, including Doubt/Vet/serial/parallel Build. Resource,
+access, safety and irreversible-action boundaries independently stop work.
+
+- **Fingerprint the failed invariant, not the review round.** Identify owning
+  invariant + defect mechanism + minimal reproduction/decisive failure signal.
+  DEC/DRIFT IDs, line numbers, wording and splitting one cause create no new budget.
+- **Cap no-progress retries:** three no-progress attempts per exact causal fingerprint
+  across wright/recovery. Only a correction whose narrow recheck leaves that cause
+  open or reproduces its failure consumes an attempt.
+  Closing a prior finding with discriminating evidence is progress: resolve it,
+  do not charge. A new Critical or Important finding gets its own budget only for
+  a distinct evidenced cause. The same invariant with a different evidenced mechanism qualifies;
+  renaming/splitting an unchanged cause does not. Suggestion/Nit/FYI cannot extend
+  recovery. Initial discovery and expected test-first RED are not corrections;
+  total rounds, re-batches and distinct-finding counts never exhaust recovery.
+- **Rechecks are scoped; late findings never reopen the round.** *Late* applies only
+  from a phase's **second** review pass (Vet 1b, Build's recheck after the first repair,
+  Review step 7); an initial pass has no late findings and every supported finding is
+  folded normally. A recheck packet
+  names the open fingerprints, the correction diff, and the dependents of each
+  changed clause/hunk; the owning reviewer's verdict covers exactly that. A finding
+  on text/code unchanged since that role's previous pass is *late*: Critical with a
+  concrete failure path → new fingerprint under this budget; otherwise recorded
+  (Plan/Vet: `eng-review.md` `## Deferred findings`; Build: `touched-files.md`
+  `## Review trail`) with severity · site · role · kind · round, and consumed by the
+  next full-inventory gate (Vet `mechanism` → one `test-plan.md` proof row; Build →
+  the `/rite-review` roster) — never by another repair round in this phase. Review
+  closes every deferred row with a labeled verdict; Seal blocks on any without one.
+  **Failing case:** round 4 finds three Important items on clauses untouched since
+  round 1 and dispatches another repair.
+- **Separate consumptive authority from recovery.** Spent one-shot authorization
+  blocks another execution, not offline recovery. Retained evidence starts caller-owned
+  diagnosis/correction immediately; the next consumptive execution needs fresh authority.
+- **Persist existing records.** Put fingerprint, reproduction, correction,
+  `progress: resolved|no-progress` and decisive result in `drift.md` and `evidence.md`.
+  Cold resume derives counts there; no new counter file/command.
+- **Reconcile terminal cursors.** Retained distinct Critical/Important evidence below
+  cap resumes despite stale `Next step: none`; age/spent action authority is not exhaustion.
+<!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"unattended root reaches current admitted Workflow Artifact work","action":"invoke classifier; execute returned route without wright/slice charge","return":"saved lifecycle phase/action; no intermediate reply"} -->
+- **Classify exhaustion:** human-owned contract/risk/access gaps open their gate.
+  Otherwise preserve reproduction/dead ends, set `Status: blocked` and
+  `Next step: none — technical recovery exhausted; requires new evidence or changed failure conditions`.
+  Emit no phase command, retry-permission question or `/rite-resolve`.
+  Reinvocation with unchanged cause stays blocked; it never resets the cap.
+- **Resolve agent-owned questions first** from code/docs/decisions. Human communication
+  is for blocked environment, handover, inaccessible critical information or missing
+  credentials/permission—not writing, testing or review. Blocking/escalating/
+  irreversible gates remain.
+
+## What the rule does NOT cover
+
+This contract is about **human pauses**. It does not weaken or replace:
+
+- `/rite-prove`, `/rite-review`, `/rite-seal`: feature-scoped gates that always run.
+- Spec Drift Guard: answer that changes acceptance criteria routes through
+  `/rite-plan repair`, not silently into the slice.
+- `evidence.md` writes: every AFK iteration still records evidence; un-recorded passes
+  are unproven at `/rite-prove`.
+- `/clear` / `/compact` advice: context-hygiene rules are unchanged.
+
+AFK changes which decisions are automatic. It changes nothing else.
+
+## Cross-reference
+
+- Skill: `/rite-resolve` (`.devin/skills/rite-resolve/SKILL.md`).
+- Workflow integration: `/rite-build` (`.devin/skills/rite-build/SKILL.md`),
+  the readiness / HITL pre-flight stages before dispatch, and the DOUBT → PROVE
+  (fail-on-red) → RECORD stages on the wright's return
+  ([`one-slice-cycle.md`](../../../rite-build/reference/one-slice-cycle.md)).
+- Render contract: `.devin/skills/rite-build/reference/checkpoint-protocol.md`.
+- Loop discipline: `.devin/skills/rite-build/reference/afk-discipline.md`.
+- Gate taxonomy: `.devin/skills/rite-define/reference/gates.md`.
+- Schema: `.devin/skills/rite-spec/reference/state-workspace.md`.
+- Doubt's AFK exception: `.devin/skills/devrites-doubt/SKILL.md` (AFK exception section).

package/pack/generated/devin/skills/devrites-lib/reference/standards/agents.md

@@ -0,0 +1,119 @@
+# Agent orchestration
+
+> Applies when: dispatching or admitting any devrites-* role; the source-writing boundary.
+
+Follow DevRites policy and [`depth profiles`](../orchestration-profiles.md).
+
+## Authority
+
+- Root owns scope, questions/decisions/results, `.devrites/**`, phase transitions — not product source/tests; vetted executable workflow artifacts follow [`workflow-artifacts.md`](workflow-artifacts.md).
+- Only bounded wright writes product source/tests; others inspect an immutable candidate.
+- Every named role runs; unavailable → HITL, never skip/substitute.
+- Leaves never invoke agents, ask humans, change phase, push, install/deploy, migrate live data, or act irreversibly; they return evidence/proposals for root acceptance. Sole exception: one local unpushed transfer commit by an eligible native-worktree `devrites-slice-wright` — transport, not shipping authority or a checkpoint.
+
+## Agents
+
+| Agent |
+| --- |
+| `devrites-evidence-scout` |
+| `devrites-plan-drafter` |
+| `devrites-upgrade-planner` |
+| `devrites-proof-runner` |
+| `devrites-strategy-reviewer` |
+| `devrites-plan-reviewer` |
+| `devrites-doubt-reviewer` |
+| `devrites-spec-reviewer` |
+| `devrites-code-reviewer` |
+| `devrites-test-analyst` |
+| `devrites-frontend-reviewer` |
+| `devrites-security-auditor` |
+| `devrites-performance-reviewer` |
+| `devrites-devex-reviewer` |
+| `devrites-simplifier-reviewer` |
+| `devrites-retrospector` |
+| `devrites-slice-wright` |
+
+Files own briefs; [`parallel-dispatch.md`](../parallel-dispatch.md) owns rosters.
+
+## Native invocation
+
+Skills name exact fresh roles, omit native fields;
+hosts spawn/wait/deliver. Root MUST NOT advance/claim completion before admitting required results;
+running/orphaned/unavailable = `gap` — no root/generic substitute.
+Where a feature workspace exists, every fresh dispatch to a named `devrites-*`
+role — wave or solo — builds its read-set with `devrites-engine context <slug>
+--phase <p> --role <role>` and tracks the launch through `devrites-engine
+dispatch <slug> open|start|seal|return` (a solo dispatch is a wave of one;
+start/return auto-record metrics). Without a workspace the plain host dispatch
+contract above applies and no engine tracking is required.
+Workflow-named skills (e.g. devrites-source-driven) are invoked inline in the root context, never dispatched as agents.
+
+## Source-writing boundary
+
+Claude grants only wright `acceptEdits`; Codex root is workspace-capable (children cannot elevate). Wright alone `:workspace`; others `:read-only`. Wright gets the smallest exact project-relative source/test list — no directories/globs, traversal, or `.devrites/**`; no scope widening; root rejects `git diff --name-only` extras. Never patch product source/tests in root, bypass/substitute wright, accept drift, or recreate a dispatch bridge.
+
+Isolated-worktree pilot only under [`wright-dispatch.md`](../../../rite-build/reference/wright-dispatch.md#isolated-writer-worktree-pilot): one writer, committed/clean baseline, non-submodule parent, exact transfer commit, candidate reconciliation — never parallel writers nor weaker exact-path admission. Root may materialize only exact Vet-ready workflow-artifact paths per [`workflow-artifacts.md`](workflow-artifacts.md) — not a writer dispatch or candidate mutation.
+
+Each job gets objective/exclusions, exact paths/immutable candidate, rubric/result shape, a **stop condition** (when to return), and the exact result shape; a dispatch missing them is malformed and re-issued. Briefs MUST NOT seed verdict/severity cap/conclusion/suppression. Results state status/scope, outcome, commands/escalation; wright adds paths, changed files, gates, stood decisions; results never widen scope.
+
+**Same-tree concurrent sessions claim first.** Worktree dispatch isolates
+parallel batch siblings, but two agent *sessions* (two hosts, two features, or
+a human plus an agent) can share one working tree. Before a same-tree writer
+starts, it records an advisory claim — `devrites-engine claim add --session
+<id> <paths>` — retains the returned `<claim-id>`, then checks the same paths
+with `devrites-engine claim check --session <id> <paths>`; a held claim from a
+live foreign session is a stop-and-report, not a merge-later problem. On every
+terminal path after `add` — success, gap, stop, or launch failure — run
+`devrites-engine claim release --session <id> --id <claim-id>`. Claims expire
+by TTL only as crash recovery; `claim list` shows who holds what. Claims are
+advisory coordination, never a substitute for the one-writer-per-worktree rule.
+
+## Independence
+
+- A fresh result sees scope/paths-diff/rubric only — never another result's or the root's conclusions, severities, expected verdicts, chosen verification methods, or edited context; seeding voids the packet.
+- **Verify the packet is clean before admitting the account.** Confirm the returned packet/trace carries no host-injected context: an automatic memory/summary banner naming an earlier phase verdict (e.g. `past Temper PASS … next is /rite-define`) or harness reminder text seeds the pass and voids it. Cancel that account — never admit it — name the lost coverage, and re-dispatch with the host's context injection disabled for that child. Tool config changes that do not stop native child auto-injection are not a fix; verify on the next spawn instead of assuming.
+- A parent-context pass contributes attributed evidence but is not independent: exclude it from independent accounting and name the lost coverage.
+- Final severity is set at reconciliation after re-verifying the claimed consequence at the cited site (reviewer severity advisory); dismissals record a reason, and true facts about neighboring code route elsewhere instead of being dismissed.
+- Conflicting required results are arbitrated by re-verifying evidence at the site; the deciding evidence is recorded, truly unresolved conflicts stay open blockers. Two results describing the same defect merge only when both defect and fix path match; otherwise the more conservative classification stands, and severity never widens without new site evidence — an overridden or demoted finding stays visible with the reason, never silently merged away.
+
+## Result admission
+
+Each required reviewer/analyst/auditor starts with exactly one:
+`Outcome: findings`, `Outcome: no-findings`, or `Outcome: gap`.
+
+**Canonical finding shape (C2 — all `devrites-*-reviewer` / auditor agents):**
+
+```text
+Outcome: <findings | no-findings | gap>
+Finding: <severity> | <file:line or artifact section> | <observed quote/result> | <impact> | <minimum fix>
+Basis: <files read · commands run to reach this finding>
+```
+
+- **`findings`:** each row uses the shape above; confidence 1–10 on Critical/Important.
+  Critical/Important requires 7+, exact evidence, concrete impact, and a non-empty
+  `Basis` — a correct verdict reached by an unrecorded inspection path is unproven.
+- **`no-findings`:** `No-findings:` names checks and inspected evidence. Bare
+  pass, empty list, or “looks good” is malformed.
+- **`gap`:** names missing/unreadable/stale input; skipped/failed required check;
+  tool/reviewer failure; or another limit. Required gaps block.
+
+Root treats results as claims; verifies proposed Critical/Important blockers
+against candidate. Missing fields become
+`Unverified: <claim> — missing <proof>` and stay `gap` until verified/rejected
+with evidence—never silently dropped/demoted. Null/timeout/failure/malformed
+output is `gap`, never `no-findings`. Conditional `Not-applicable` must name the
+inspected scope and why its trigger did not fire. **Failing case:** parent admits a
+wright "done" with no `git diff --name-only` ⊆ path-contract (allowlist) observation.
+
+## Reconciliation
+
+Root rejects stale/out-of-scope work, dedupes by root cause, records
+accepted conclusions, and reruns only affected proof/review. Reconciliation runs
+only after every dispatch reaches a terminal classification
+([parallel-dispatch.md](../parallel-dispatch.md)); findings that do not survive stay
+visible as `withdrawn: <n> (<reason>)` in the account rather than being silently
+dropped, so a later reader can audit what was discarded and why.
+Route defects before correction: product/acceptance → Spec Drift Guard/Clarify;
+architecture/slicing/proof → Plan/Vet; source/test → wright;
+external/pre-existing → blocker/defer. Never patch downstream to hide an upstream
+defect.

package/pack/generated/devin/skills/devrites-lib/reference/standards/anti-patterns.md

@@ -0,0 +1,50 @@
+# DevRites: universal anti-patterns
+
+> Applies when: universal rationalizations; load when tempted to shortcut any standard.
+
+The pack-wide rationalizations the agent reaches for when discipline gets in
+the way. Apply at every phase. Each `rite-*/reference/anti-patterns.md`
+extends this with phase-specific items.
+
+This file is the **single source** of the universal anti-rationalization table.
+`core.md` points here when an excuse appears.
+
+## Universal rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "I'll add the tests later." | Tests written after the fact don't drive design and miss the boundary cases the act of writing exposes. Test now or the tests you eventually write are worse. |
+| "Lint and build pass, that proves quality." | Automation proves syntax and style, not design or correctness. Never cite clean automation as evidence of good design. |
+| "It's only a small refactor while I'm in here." | Feature scope only: drive-by cleanup balloons the diff, hides intent, and gets rejected at seal. Record as an FYI follow-up. |
+| "This is a special case, the pattern doesn't apply." | Special cases multiply silently. Either they really are special (record *why* in `decisions.md`) or they're not (and the pattern wins). |
+| "The user will tell me if something is wrong." | Drift detection is the workflow's job, not the user's QA. Surface assumptions; route material questions through the Spec Drift Guard. |
+| "Generic name (`processData`, `handleItem`) is fine: the code is self-evident." | Generic AI naming is slop. Match the project's idiom; one concept gets one word across the codebase. |
+| "Better safe than sorry: add the defensive null/length check." | Over-defensive guarding is slop. Validate at boundaries; trust the core. A check inside trusted code hides bugs in the boundary. |
+| "It's faster to skip the small step." | Process shortcuts pay back later as drift, missed criteria, or unrecorded decisions. The step is the point. |
+| "I observed it pass; recording is bureaucracy." | Un-recorded pass = unproven. The next phase reads `evidence.md`, not your memory. |
+| "User clearly wants this, so I'll bypass the gate." | Gates exist for the failure modes asks miss. Honor the gate; the gate exists *because* of the ask. |
+| "The test is failing. I'll just skip it / loosen the assertion to get green." | Faking green is reward-hacking, not progress. Never delete / skip / `xfail` / `.only` / loosen a failing test: a red test means fix the code or agree the change. Diff review and dedicated test analysis treat weakening as Critical. |
+| "This project principle doesn't really apply to my case." | A declared invariant (`.devrites/principles.md`) is not advisory. Either it genuinely needs relaxing (record a scoped, dated exception a human approves) or it applies and the change is wrong. Silently routing around a principle is the defect the gate exists to catch (`principles.md`). |
+
+## Pack-wide red flags
+
+These show up at any phase and are equally damning regardless:
+
+- Touching files that aren't in `touched-files.md` "while I'm here".
+- A finding / decision / assumption recorded only in chat, not in the workspace files (it dies on `/clear`).
+- Catching the broadest possible error and continuing past it.
+- A test that asserts the implementation, not the behavior.
+- A failing test deleted, skipped, `xfail`-ed, `.only`-narrowed, or loosened to make the suite pass.
+- Commenting out code instead of deleting it.
+- A `// TODO` left in shipped code.
+- Adding a dependency or a second design system without rationale in `decisions.md`.
+- A change that violates a declared project principle (`.devrites/principles.md`) with no recorded, human-approved exception.
+- "I'll fix it in a follow-up PR" with no follow-up opened.
+
+## Where this gets loaded
+
+Phase-specific `rite-*/reference/anti-patterns.md` files extend this table with only their local cases. Load this file when the rationalization is broader than one phase.
+
+## Behavioral coverage
+
+A new behavior-shaping rebuttal needs a matching behavioral eval; prose alone does not prove the guard holds under pressure.

package/pack/generated/devin/skills/devrites-lib/reference/standards/architecture-health.md

@@ -0,0 +1,64 @@
+# Architecture health
+
+> Applies when: an audit, vet, or seal needs a structural read on the whole
+> codebase — not the diff — and a dependency index is available.
+
+A health score compresses six structural signals into one 0–100 number with a
+letter grade. It is an *audit instrument*, not a gate: it ranks surfaces for
+attention and tracks drift between milestones. It never proves a change safe
+and never substitutes for review.
+
+## When to measure
+
+Compute a score only when a code index covers the repo (see
+[`code-navigation.md`](code-navigation.md) § Index freshness). With no index,
+report `unmeasured` — a placeholder number presented as a measurement is a
+false pass. **Failing case:** an audit reports "health: 100/100" on a repo the
+instrument could not parse.
+
+## Dimensions
+
+Weight the dimensions exactly once; do not invent extra dimensions ad hoc —
+record repo-specific signals as findings instead.
+
+| Dimension | Weight | What it measures | Healthy | Warning |
+| --- | --- | --- | --- | --- |
+| Coupling | 25% | Cross-file edges per file; penalize god-file outliers (max ≫ 3× mean) and >70% cross-directory share | avg ≤3 connections | avg >10 |
+| Cohesion | 20% | Share of a directory's edges that stay inside it | ≥70% internal | <30% |
+| Circular deps | 20% | File-level dependency cycles per 100 files | 0 cycles | >5 per 100 |
+| God files | 15% | Files with >3× mean connections | none | >6% of files |
+| Orphans & dead exports | 10% | Unreferenced files; exported symbols with zero dependents (60/40 blend) | 0% orphans | >10% orphans or >5% dead exports |
+| Depth | 10% | Longest dependency chain, cycles collapsed to one hop each (SCC-condensed DAG) | ≤4 levels | >8 |
+
+Grade bands: ≥90 A · ≥80 B · ≥70 C · ≥60 D · below F.
+
+## Rules
+
+- **Measure before and after.** A score's value is the delta: record
+  before/after for structural work in `evidence.md`; a drop >3 points needs a
+  named cause, not a shrug.
+- **Count runtime edges, not type-only edges.** `import type`-style
+  relationships inform dead-code analysis but do not execute; including them
+  overstates coupling.
+- **Exclude fixtures and generated files** from orphan/dead counts — a
+  directory of test fixtures is not dead code.
+- **Depth is computed on the condensed graph.** Collapse each cycle (strongly
+  connected component) to one node first; an exact longest-path search on a
+  cyclic graph is unbounded and returns no honest number.
+- **Every recommendation names the dimension it moves.** "Improve the
+  architecture" is not an action; "extract `x/` → `y/` edge to cut cross-dir
+  coupling (Coupling, est. +8)" is.
+- **Trend over snapshots.** Keep the score per milestone in `evidence.md` or
+  the feature's audit artifact; a single reading without a baseline is a
+  weather report, not a climate signal.
+
+## Orphan and dead-export semantics
+
+An orphan file has zero cross-file runtime edges. A dead export is an exported
+top-level symbol (function/class/interface/type/enum/constant) with zero
+incoming edges — member-level symbols (methods, properties) are excluded:
+they are not meaningful architecture-level candidates and produce false
+positives. Both counts feed only this dimension; the *removal decision* for a
+dead export follows [`deprecation.md`](deprecation.md), including its
+confidence rubric — a low-confidence dead lead is a watch item, never an
+automatic deletion.