devrites 3.0.7 → 3.2.0

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

@@ -1,61 +1,44 @@
 # DevRites rules
 
-Stack-agnostic engineering rules that DevRites installs to `.agents/skills/devrites-lib/reference/standards/`. They encode
-the standards the DevRites workflow holds code to: quality, safety, testing, and review
-discipline that apply in any language.
+These stack-agnostic rules ship under `.agents/skills/devrites-lib/reference/standards/`. Project-specific conventions win where they exist.
 
-These are **common** by design: nothing here assumes a specific framework or language.
-Project-specific conventions always win where they exist (DevRites reads the codebase and
-prefers what's already there).
+## Loading model
 
-## Loading model: progressive disclosure
+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.
 
-To keep context lean, the rules follow progressive disclosure: each DevRites `rite-*`
-skill Reads `.agents/skills/devrites-lib/reference/standards/core.md` as its first step;
-the remaining rule files load on demand by the phase that needs them.
-
-### Always-on (read by each `rite-*` skill as step 0)
-
-| Rule | Covers |
+| Rule | Load when |
 |---|---|
-| `core.md` | Operating rules, universal anti-rationalizations, one-line craft disciplines (fail-fast, reuse-first, test-behaviour-not-impl, trust boundary, measure-first), persistence + hygiene reminders. |
-
-### On-demand (read by the phase / topic that needs it)
-
-| Rule | Covers | Typical phase |
-|---|---|---|
-| `coding-style.md` | Naming, function shape, guard clauses, comments, simplicity, reuse-first. | `$rite-build`, `$rite-polish` Phase 1. |
-| `prose-style.md` | Human-voice writing for artifacts + replies; two registers (prose vs technical); the LLM-tell cut-list. Depth in the `devrites-prose-craft` skill. | Any phase that writes prose: `$rite-spec`, `$rite-define`, `$rite-review`, `$rite-seal`, `$rite-ship`; `$rite-polish` Phase 1 as the catch. |
-| `error-handling.md` | Fail fast, no silent catches, meaningful messages, fail closed. | `$rite-build`, `$rite-polish` (backend), `$rite-review`. |
-| `testing.md` | Pyramid, behavior over implementation, determinism. | `$rite-build`, `$rite-prove`, `$rite-review`. |
-| `spec-grammar.md` | Optional, recommended structure for behavioral acceptance: `### Requirement:` (SHALL/MUST) + `#### Scenario:` (WHEN/THEN), validated deterministically by `devrites-engine spec-validate`. Progressive rigor; flat `AC-###` bullets stay valid. | `$rite-spec` readiness gate; `$rite-prove`, `$rite-review` consume the scenario hooks. |
-| `code-review.md` | Small PRs, severity labels, what to check, actionable feedback. | `$rite-review`, `$rite-seal`. |
-| `edge-case-trace.md` | Mechanical branch/boundary sweep, fixed-set siblings, and deletion-contract checks. | `$rite-review`, `$rite-seal`, `devrites-doubt`. |
-| `security.md` | Untrusted input, least privilege, secrets, three-tier trust boundary, fail closed. | When input / auth / data / integrations are in scope. |
-| `performance.md` | Measure first, common pitfalls, prove the win. | When perf is in scope. |
-| `observability.md` | Structured logs, metrics/SLIs, traces, symptom-based alerts, verify-the-telemetry-fires: proof a feature works in prod. | When the change has a runtime surface (endpoint, job, integration, user flow); `$rite-prove`, `$rite-seal`. |
-| `developer-experience.md` | DX as a measured axis: the predict-at-vet / measure-at-prove / reconcile-at-seal boomerang; scorecard (TTHW, getting-started, error-message quality, ergonomics, docs); severity by who-pays. Conditional + greenfield no-op. | When a developer-facing surface is in scope (public API, CLI, SDK/library, webhook, config, error messages, getting-started); `$rite-vet`, `$rite-prove`, `$rite-seal`. |
-| `patterns.md` | SOLID, composition, loose coupling, avoid over-engineering. | `$rite-build`, simplification audit. |
-| `git-workflow.md` | Conventional Commits, atomic commits, small PRs. | `$rite-ship` commit / push / tag steps. |
-| `hooks.md` | Stage checks by cost, fast local hooks, secret scanning. | Reference-only: read when setting up the project's git hooks; not auto-loaded by any phase. |
-| `ci-cd.md` | Shift-left + faster-is-safer, the no-skip gate pipeline, the CI-failure loop, Build Cop, feature-flags decouple deploy from release, secret tiers, the pipeline-speed ladder. | Reference: read when setting up or changing a build/deploy pipeline; `$rite-ship` when CI/CD is in scope. |
-| `documentation.md` | Explain why, keep current, record decisions. | `$rite-spec`, `$rite-define`, `$rite-seal`. |
-| `elicitation.md` | A move-set of named reasoning techniques (Steelman, Delphi, Red-Team/Blue-Team, Assumption Audit, Pre-Mortem…) selected per section by risk, to deepen a spec or plan on demand. | `$rite-temper`, `$rite-vet`; any section that needs sharper thinking. |
-| `development-workflow.md` | Small batches, trunk-always-green, definition of done. | `$rite-define`, `$rite-plan`. |
-| `principles.md` | The four knowledge layers; project invariants (`.devrites/principles.md`) as a *trusted, gating* pass/fail (vs conventions' untrusted prior); justified-exception register; dated-amendment governance. | `$rite-define`, `$rite-vet`, `$rite-build`, `$rite-review`, `$rite-seal`; seeded by `$rite-adopt`, grown by `$rite-learn`. |
-| `deprecation.md` | Code-as-liability, Hyrum's law, prove-unused-before-remove, expand→contract, deprecate-before-delete. The safe path behind the irreversible-migration gate. | When removing / replacing / migrating code, a feature, an API, or data. |
-| `agents.md` | DevRites review subagents + specialist skills, when to fan out. | `$rite-review`, `$rite-seal`. |
-| `context-hygiene.md` | `/clear` vs `/compact`, lost-in-the-middle, phase-aware hygiene footer. | Phase-end hygiene footer; choosing `/clear` vs `/compact`. |
-| `anti-patterns.md` | Pack-wide rationalizations + red flags the agent reaches for. | Loaded by each `rite-*/reference/anti-patterns.md`; loaded directly when reluctance is broader than the active phase. |
-| `afk-hitl.md` | AFK vs HITL contract: `.devrites/AFK` sentinel format, `questions.md` schema, four-gate taxonomy (advisory / validating / blocking / escalating), AFK-never-silently-accepts boundaries. | `$rite-build`, `$rite-status`, `$rite-resolve`, `devrites-doubt`; anywhere a pause-or-proceed decision happens. |
-| `tooling.md` | Optional external tools: code intelligence (codebase-memory-mcp first → cross-verify with codegraph + graphify → standard methods LSP / `Read`/`Grep`/`Glob`), up-to-date library docs (context7), architecture/ADR memory. Recommended, not required. | Any phase doing structural lookups (callers / impact / placement) or relying on external library/framework facts. |
-| `skill-authoring.md` | Skill descriptions, progressive disclosure, completion criteria, and pruning rules for keeping DevRites skills predictable and cheap. | When creating or editing DevRites skills or reviewing skill pack quality. |
-| `definition-of-done.md` | Done means acceptance proven, evidence recorded, drift resolved, and handoff/ship state clean. | `$rite-prove`, `$rite-seal`, `$rite-ship`. |
-| `review-checklist.md` | Compact reviewer pass/fail checklist. | `$rite-review`, `$rite-seal`. |
-| `test-proof-checklist.md` | Proof-quality checklist for tests and evidence. | `$rite-prove`, `$rite-seal`. |
-| `browser-proof-checklist.md` | Browser/UI proof checklist. | UI features in `$rite-prove`, `$rite-polish`, `$rite-seal`. |
-| `security-checklist.md` | Security review checklist. | Auth/input/data/integration changes. |
-
-How they're used: DevRites skills follow these rules; you and Claude can reference them
-directly. They are guidance, not enforced gates: the enforced gates live in the
-workflow skills (Spec Drift Guard, readiness gates, the seal).
+| `core.md` | Every workflow phase: operating, persistence, evidence, and precedence rules. |
+| `coding-style.md` | Writing or simplifying code. |
+| `prose-style.md` | Writing prose artifacts or user replies. |
+| `error-handling.md` | Adding or reviewing failure paths. |
+| `testing.md` | Designing tests or judging proof quality. |
+| `spec-grammar.md` | Structuring high-risk behavioral requirements or capability deltas. |
+| `code-review.md` | Reviewing a change or sealing review findings. |
+| `edge-case-trace.md` | Sweeping branches, boundaries, fixed-set siblings, or deletion contracts. |
+| `security.md` | Handling input, auth, data, secrets, dependencies, or integrations. |
+| `performance.md` | A measured performance concern is in scope. |
+| `observability.md` | A changed runtime path must be diagnosed in production. |
+| `developer-experience.md` | A public API, CLI, SDK, webhook, config, error, or getting-started surface changes. |
+| `patterns.md` | Choosing or simplifying architecture. |
+| `git-workflow.md` | Preparing commits, branches, tags, or changelog entries. |
+| `hooks.md` | Creating or changing repository hooks. |
+| `ci-cd.md` | Creating or changing a build/deploy pipeline. |
+| `documentation.md` | Behavior, commands, contracts, or durable decisions change. |
+| `elicitation.md` | Temper or Vet needs a sharper reasoning move for one section. |
+| `development-workflow.md` | Planning batch size, integration, or the standing done bar. |
+| `principles.md` | Authoring or checking project invariants and approved exceptions. |
+| `deprecation.md` | Removing, replacing, or migrating behavior, code, APIs, or data. |
+| `agents.md` | Dispatching, awaiting, validating, or reconciling fresh-context agents. |
+| `context-hygiene.md` | Choosing `/clear`, `/compact`, or a handoff. |
+| `anti-patterns.md` | A pack-wide rationalization or red flag appears. |
+| `afk-hitl.md` | A pause, question, resume, or AFK decision is possible. |
+| `tooling.md` | Structural lookup, current external facts, or architecture memory is needed. |
+| `skill-authoring.md` | Creating, editing, routing, evaluating, or pruning a DevRites skill. |
+| `definition-of-done.md` | Prove, Seal, Ship, or Quick must decide whether work is finished. |
+| `review-checklist.md` | A compact review pass/fail sweep is enough. |
+| `test-proof-checklist.md` | Test and evidence quality needs a compact sweep. |
+| `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.

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

@@ -1,10 +1,10 @@
 # AFK & HITL: the pause/resume contract
 
-The rule layer for DevRites's two run modes. Every `rite-*` and `devrites-*` skill that
+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.
 
-The contract is intentionally small: one sentinel, one queue, one verb.
+The contract uses one sentinel, one queue, and one resume verb.
 
 ## Run modes
 
@@ -14,9 +14,9 @@ The contract is intentionally small: one sentinel, one queue, one verb.
   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**.
-  **No interactive question tool in the current surface?** (Codex outside Plan mode:
+  **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 pick. Auto-picking an option
+  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
@@ -67,8 +67,7 @@ for the full taxonomy. Summary:
 | 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`. They are the
-"AFK never silently accepts" guarantees in protocol form.
+`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
@@ -77,14 +76,14 @@ validating gate resolves.
 
 ## Option set: how every gap is presented
 
-Wherever a gap, checkpoint, or non-trivial decision surfaces (`$rite-spec`, `$rite-define`,
+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 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, not just the choice.
+  Name the trade-off as well as the choice.
 - 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.
@@ -92,8 +91,21 @@ Wherever a gap, checkpoint, or non-trivial decision surfaces (`$rite-spec`, `$ri
 **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 and the **rejected options stay in `questions.md`** as the considered-alternatives
-trail: the audit shows what was weighed, not just what was decided.
+recorded verbatim. Keep the **rejected options in `questions.md`** so the record includes
+the alternatives considered.
+
+## 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)
 
@@ -105,16 +117,18 @@ The following always invoke the checkpoint protocol, regardless of `Mode`, `Gate
 - Public API break (response shape, removed endpoint, changed status code semantics).
 - External-service contract change.
 - Filesystem destruction outside the workspace.
-- Red tests / types / lint on slice completion (fail-on-red).
 
 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 exists to make you do it right, not to
-abandon the work.
+([`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:
@@ -142,6 +156,15 @@ 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.
+
 ## `state.md` `Awaiting human` block
 
 When a HITL gate fires, `$rite-build` writes:
@@ -177,8 +200,8 @@ walked away from), plus `--batch`. In an **interactive HITL** session the skill
 `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**:
-one source of truth, two entry points (live pick vs typed verb). Manual edits work but the
-script is the contract: use it.
+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:
@@ -198,24 +221,27 @@ When `$rite-resolve` does resume a stopped session, the skill does **not** auto-
   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: after the limit, the unresolved
-doubt becomes a blocking question regardless of AFK config.
+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, stuck loops, and self-resolve
 
-- **Cap retries.** At most **3 attempts** on the same failing check (test, lint, type, build).
-  On the third failure, stop guessing and convert it to a `gate: blocking` question: a fourth
-  identical attempt is thrash, not progress.
-- **Stuck loops pause even in AFK.** A detected loop (the same action repeating, or an
-  action↔error ping-pong) pauses regardless of `allow_gates` (`devrites-engine stuck`), the same standing as
-  the irreversible-risk list. AFK widens what's automatic, never what's looping.
-- **Bias to self-resolve.** Before raising a question, try to answer it from the code, the docs,
+- **Cap retries:** three total attempts per root cause across wright and recovery, carrying the
+  failure and dead ends; never rerun an unchanged check.
+- **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`.
+- **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
   needless pauses and never weakens the blocking / escalating / irreversible gates.
-- **Human time is for human-only work.** A `human_intervention` pause is for what the agent
+- **Use human intervention only for human-owned work.** A `human_intervention` pause is for what the agent
   literally cannot do (create a cloud account, click a console button): never for writing code,
-  writing tests, or reviewing. Punting the agent's own job to the human is not a valid gate.
+  writing tests, or reviewing. The agent's own work is not a valid human gate.
 
 ## What the rule does NOT cover
 
@@ -228,7 +254,7 @@ This contract is about **human pauses**. It does not weaken or replace:
   are unproven at `$rite-prove`.
 - `/clear` / `/compact` advice: context-hygiene rules are unchanged.
 
-AFK shifts the boundary between automatic and "ask"; nothing else.
+AFK changes which decisions are automatic. It changes nothing else.
 
 ## Cross-reference