devrites 4.7.0 → 5.1.0

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

@@ -0,0 +1,345 @@
+# AFK & HITL: the pause/resume contract
+
+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
+expires_at: "<ISO-8601 UTC timestamp>" # absolute unattended-authority expiry
+# 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: rite-build/reference/afk-discipline.md
+allow_gates: [advisory, validating]  # gate severities AFK auto-handles (auto-picks the recommended option)
+```
+
+The file is **read-only config**: never rewritten in place. `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`.
+
+## Unattended resource envelope
+
+AFK writer admission needs a bounded input queue, effective slice cap, and valid
+`max_agents`, `max_minutes`, `max_review_queue`, and `expires_at`. Existing sentinels
+that declare writer admission but miss/malform these fail closed; cold resume keeps the
+state-owned slice counter.
+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. `expires_at` is
+absolute ISO-8601 authority. 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, absolute expiry, and current
+review queue remain durable/recomputed across wakes. Persist each activation stop and
+checkpoint before notification.
+
+New sentinels default `expires_at` to arming + 4h with 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
+[`.omp/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 regardless of `allow_gates`.
+
+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
+
+`devrites-doubt` and similar skills that "ask the user" follow this rule when
+`.devrites/AFK` exists:
+
+Ceiling comparison order: Suggestion/Nit/FYI < Important < Critical; gates advisory <
+validating < blocking < escalating; a finding is ≤ the ceiling when its severity's gate
+class (Suggestion/Nit/FYI→advisory, Important→validating, Critical→blocking) is at or
+below the slice's gate.
+
+- Finding severity ≤ slice's gate ceiling (slice's `Gate:` plus `.devrites/AFK`
+  `allow_gates`) → log to `questions.md` as `gate: advisory`, record the trade-off in
+  `decisions.md`, proceed.
+- Finding severity > gate ceiling, OR finding touches the irreversible-risk list →
+  log to `questions.md` as `gate: blocking`, set `state.md` `Status: awaiting_human`,
+  fire `notify:`, STOP.
+
+The loop limits of the calling skill still apply. At the limit, classify the unresolved
+finding by the decision-ownership rule above: human-owned uncertainty becomes a blocking
+question; an objective technical finding becomes a recorded blocker with its required
+changes, not a request for permission to retry.
+
+## Retry cap, no-progress loops, and self-resolve
+
+- **Fingerprint the failed invariant, not the review round.** An exact causal
+  fingerprint is the owning gate/invariant plus its minimal reproduction and
+  decisive failure signal. A new DEC/DRIFT number, changed line number, reviewer
+  wording, or splitting one finding does not create a new fingerprint.
+- **Cap no-progress retries:** three no-progress attempts per exact causal fingerprint
+  across wright and recovery is a hard cap. Only a repair whose narrow recheck
+  leaves that fingerprint open or reproduces the same decisive failure consumes
+  an attempt. Closing a prior finding with discriminating evidence is progress:
+  mark that fingerprint resolved and do not charge it as no-progress. A genuinely
+  new Critical or Important finding with a different failed invariant and exact
+  evidence gets its own fingerprint and budget; Suggestion, Nit, FYI, or renamed
+  evidence cannot open, reset, or extend recovery.
+- **Separate consumptive authority from recovery.** Spending a one-shot action's
+  authorization forbids another real execution but does not consume the offline
+  recovery budget for a newly evidenced fingerprint. The retained artifact starts
+  caller-owned diagnosis and correction immediately; only the next consumptive
+  execution waits for fresh authorization.
+- **Persist accounting in existing records.** Record each fingerprint,
+  reproduction, attempted correction, `progress: resolved|no-progress`, and
+  decisive result in `drift.md` and `evidence.md`. Cold resume derives the count
+  from those records. There is no recovery counter file or command.
+- **Reconcile before honoring a terminal cursor.** A persisted distinct
+  Critical/Important fingerprint with retained evidence and fewer than three
+  recorded no-progress corrections still has recovery budget, even when an older
+  `state.md` says `Next step: none`. Resume it; do not treat session age or the
+  prior action's spent authorization as 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`.
+  Do not emit `/rite-plan unblock`, another phase command, a question, or
+  `/rite-resolve`. Reinvocation with the unchanged fingerprint remains blocked
+  and never resets the retry cap.
+- **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 — never for
+  writing code, writing tests, or reviewing; the agent's own work is not a valid human gate.
+  This narrows needless pauses and never weakens the blocking / escalating / irreversible gates.
+
+## 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` (`.omp/skills/rite-resolve/SKILL.md`).
+- Workflow integration: `/rite-build` (`.omp/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
+  (`reference/one-slice-cycle.md`).
+- Render contract: `.omp/skills/rite-build/reference/checkpoint-protocol.md`.
+- Loop discipline: `.omp/skills/rite-build/reference/afk-discipline.md`.
+- Gate taxonomy: `.omp/skills/rite-define/reference/gates.md`.
+- Schema: `.omp/skills/rite-spec/reference/state-workspace.md`.
+- Doubt's AFK exception: `.omp/skills/devrites-doubt/SKILL.md` (AFK exception section).

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

@@ -0,0 +1,98 @@
+# Agent orchestration
+
+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.
+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.
+
+## Independence
+
+- A fresh result sees scope/paths-diff/rubric only — never another result's or the root's conclusions, severities, expected verdicts, or edited context; seeding voids the packet.
+- 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/omp/skills/devrites-lib/reference/standards/anti-patterns.md

@@ -0,0 +1,48 @@
+# DevRites: universal anti-patterns
+
+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/omp/skills/devrites-lib/reference/standards/browser-proof-checklist.md

@@ -0,0 +1,24 @@
+# Browser proof checklist
+
+Compact sweep only. Numbers and failing cases live in
+[`quality-standards.md`](../../../devrites-frontend-craft/reference/quality-standards.md)
+§ Focus & states, § Responsive, and § Browser chrome — do not restate a shorter
+viewport set here.
+
+- Open the real UI (never screenshot-only); check console and network for errors.
+- Before reading the builder's verdict, inventory the raw captures against the
+  required routes/states/viewports and candidate identity. Open each capture: a
+  wrong route, blank render, unexpected login wall, inconsistent dimensions, or
+  stale candidate is missing evidence. Recapture; until resolved, record
+  `cannot_verify` and block visual approval. A convincing narrative cannot repair it.
+- Interactive slices capture each relevant canonical state and the canonical
+  viewport set. Omission needs a one-line `not-needed` reason; states must exist
+  in source — an unreachable state's capture proves nothing.
+- Browser-default chrome is judged by § Browser chrome; reflow, zoom and bounded
+  two-dimensional exceptions by § Responsive. Compare to `design-brief.md` → Visual Verdict.
+- Tooling unavailable ⇒ record fallback + limitation. Backend-only changes record
+  that disposition instead of capturing quietly; UI copy follows
+  `devrites-frontend-craft`, long-form prose follows `devrites-prose-craft`
+  ([`prose-style.md`](prose-style.md)).
+
+Detailed skill: `devrites-browser-proof`.

package/pack/generated/omp/skills/devrites-lib/reference/standards/ci-cd.md

@@ -0,0 +1,50 @@
+# CI/CD & automation
+
+Read this only when creating or changing a build/deploy pipeline. [`hooks.md`](hooks.md) owns local checks, [`development-workflow.md`](development-workflow.md) owns trunk health, and [`deprecation.md`](deprecation.md) owns migrations.
+
+## Pipeline gates
+
+- Put each check at the earliest affordable stage: editor → pre-commit → pre-push → CI.
+- Keep batches small so failures are attributable and releases remain reversible.
+- Run lint → type-check → unit → build → integration → audit → E2E as applicable. A red gate stops the line; fix the defect rather than disabling the rule, weakening the test, or skipping the gate. CI is the source of truth for green.
+
+## Failure loop and ownership
+
+Read the specific failure, fix its root cause, verify locally, then push again. Do not blind-rerun a flaky pipeline. Use `devrites-debug-recovery` when a test or build failure needs reproduction.
+
+A designated Build Cop (a human/team role, not a pack agent) owns restoring a broken trunk by fixing or reverting, whichever is faster. Restoring trunk outranks feature work.
+
+## Deploy versus release
+
+Keep incomplete or risky behavior disabled behind a flag so deploy and release remain separate and rollback does not require a redeploy. Every flag has an owner and a removal trigger; remove it through the [`deprecation.md`](deprecation.md) expand/contract path.
+
+## Deployment order and configuration
+
+- Derive an explicit order for schema, application, worker, contract, config, and flag
+  changes. Prove the system remains safe at every intermediate old/new combination;
+  "deploy together" is not an atomicity guarantee across units.
+- Validate required configuration at startup or the earliest safe boundary. Record names,
+  owners, environments, safe defaults, and rollback values without recording secrets.
+  A staging value copied by memory is not production evidence; a configuration mismatch
+  blocks exposure until the exact target value/owner is verified.
+- Documentation drift in commands, configuration, migration order, or rollback steps is a
+  delivery defect: update the canonical doc and execute the documented path before exposure.
+- Migration and destructive steps apply [`data-integrity.md`](data-integrity.md); service,
+  queue, webhook, and cache changes apply
+  [`integration-reliability.md`](integration-reliability.md). Their recovery/observability
+  gates precede exposure.
+- Feature flags separate exposure only when both states are tested, the off path preserves
+  current behavior, and disabling the flag stops the risky effect. A flag cannot undo an
+  already destructive schema or data change.
+
+## Secrets
+
+Commit `.env.example` without values; never commit real `.env` files. Inject CI secrets from the platform store and scope them to the job. Build runners do not receive production credentials.
+
+## Slow pipelines
+
+When wall time exceeds roughly ten minutes, measure before and after. Improve in order: cache dependencies, parallelize independent jobs, path-filter, shard the slow suite, re-tier genuinely slow tests, then consider larger runners.
+
+## Scope
+
+Change only the pipeline surface in scope; record wider CI redesign as follow-up work.

package/pack/generated/omp/skills/devrites-lib/reference/standards/code-navigation.md

@@ -0,0 +1,43 @@
+# Code navigation
+
+Decision tree for structural questions. Load with [`tooling.md`](tooling.md);
+this file is the pack-canonical routing table agents cite in Build, Vet, and
+Review.
+
+## Route by question
+
+| Question | First tool | Fallback |
+| --- | --- | --- |
+| Explore unfamiliar area, architecture, blast radius | `codegraph_explore` or codebase-memory `search_graph` / `get_architecture` | code-review-graph `detect_changes_tool` / `get_impact_radius_tool` |
+| Callers, callees, data flow across files | codebase-memory `trace_path` | code-review-graph `query_graph_tool` |
+| PR/review context for a diff | code-review-graph `get_review_context_tool` | `detect_changes_tool` |
+| Exact symbol body before edit | `read_symbol` / `module_report` (pi-lens) | `get_code_snippet` then targeted `Read` |
+| Rename, references, diagnostics | LSP (`lsp` rename/references) when available | graph trace + grep |
+| Known file, one-line fix | `Read` at offset/limit | — |
+| Literal string / config value | `Grep` | — |
+
+## Before cross-file edits
+
+1. Run **one** primary route from the table (record tool + query in the artifact).
+2. Read symbol bodies you will change (`read_symbol` counts as read).
+3. After edits: LSP diagnostics + project tests.
+
+Skipping step 1 on a multi-file slice is a Build orient gap unless recorded
+`cannot_verify`.
+
+## Index freshness
+
+| Index path | Provider |
+| --- | --- |
+| `.codegraph/` | CodeGraph |
+| `.code-review-graph/` | code-review-graph MCP |
+| `.codebase-memory/` | codebase-memory MCP |
+Run `devrites-engine check indexes` for a quick presence check. Stale or missing index:
+build/refresh per provider docs, or fall back to LSP + grep and note the gap.
+
+## Anti-patterns
+
+- Duplicate graph queries for reassurance.
+- Whole-file reads when `read_symbol` or `module_report` suffices.
+- Grep-only blast-radius claims when an index is present.
+- Editing without reading the enclosing symbol body.