devrites 2.6.0 → 3.0.0

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

@@ -0,0 +1,119 @@
+# DevRites core rules — always-on
+
+The minimal always-on subset of the DevRites engineering rules. Workspace-operating
+lifecycle rites read it in workflow step 0; phase-specific files load on demand from
+`README.md`.
+
+Project conventions always win where they exist; these rules fill gaps.
+
+## Operating rules (every phase)
+
+1. **Right step, right time** — use the smallest relevant workflow; don't load
+   everything. When you read, parallelize independent reads and speculatively batch the
+   files a step is likely to need; aim for comprehensive coverage of the relevant code,
+   not the first match (a code-intelligence index, **if one is available**, answers
+   structural questions faster than raw reads — see [`tooling.md`](tooling.md); this rule
+   is for the raw reads, the fallback when none is).
+2. **No silent assumptions** — surface material assumptions; ask when the answer
+   changes scope, architecture, data model, UX, security, migration risk, or
+   acceptance.
+3. **No guessing through confusion** — if requirements / code / tests / docs
+   conflict, stop, name the conflict, present options, wait for resolution
+   when the answer changes the product.
+4. **Spec is living, not sacred** — change spec / plan only through the
+   Spec Drift Guard; never code against a known-wrong plan.
+5. **One slice at a time** — build a single vertical slice, leave it working +
+   proven, then stop. Don't auto-continue (HITL default; under AFK the loop runs to
+   its slice budget — see [`afk-hitl.md`](afk-hitl.md)).
+6. **Evidence over confidence** — tests, builds, runtime, screenshots beat
+   assertions; record commands and output.
+7. **Feature scope only** — review / simplify / polish / security stay within
+   the active feature and touched files. No project-wide refactor, no drive-by
+   cleanup. Some work is out of scope by nature — creating accounts, provisioning prod
+   infrastructure, managing credentials / secrets, testing against production — refuse it
+   and route to the human.
+8. **Prefer existing conventions** — follow the project's architecture,
+   components, tokens, tests, and commands; ask before adding a dependency or a
+   second design system.
+9. **Verify uncertain facts at the source** — when framework / library
+   behaviour matters and isn't certain, check the installed source or docs (context7 for
+   current upstream docs, **if available** — see [`tooling.md`](tooling.md)) and record it.
+
+## Rationalization guard
+
+When an excuse appears, load the canonical
+[`anti-patterns.md` rationalization table](anti-patterns.md#universal-rationalizations)
+and apply its matching rebuttal before continuing.
+
+## One-line discipline (load the full rule file when in scope)
+
+These are the universal craft musts. Each links to the full file — Claude
+reads it only when the phase needs depth.
+
+- **Fail fast, no silent catches.** Validate at the top; catch narrow, recover
+  or rethrow with context; fail closed on auth / permission / transaction. →
+  [`error-handling.md`](error-handling.md)
+- **Reuse before write.** Before adding a new util / component / helper /
+  type, search for an existing one. **Reuse → extend → build new.**
+  Duplication beats the wrong abstraction (AHA). →
+  [`coding-style.md`](coding-style.md), [`patterns.md`](patterns.md)
+- **Test behaviour, not implementation.** Assert on observable behaviour and
+  public interfaces; one behaviour per test; cover unhappy paths; no flaky
+  tests. → [`testing.md`](testing.md)
+- **Three-tier trust boundary.** *untrusted* → explicit validation + authz at
+  the *boundary* → *trusted* core. Every value crosses the boundary
+  deliberately; one that skips it is a finding. →
+  [`security.md`](security.md)
+- **Measure before you optimize.** An optimisation without a measurement is a
+  guess that adds complexity. → [`performance.md`](performance.md)
+- **Names reveal intent.** No `process()` / `handle()` / `data` / `temp`.
+  One concept, one word, across the codebase. → [`coding-style.md`](coding-style.md)
+- **Comments explain *why*, not *what*.** Rename before you comment; delete
+  commented-out code. → [`coding-style.md`](coding-style.md)
+- **Write like a human, not a model.** Cut the LLM tells from every artifact
+  and reply — filler openers, "not X, it's Y" contrasts, fake profundity,
+  marketing adjectives, em-dash tics — while keeping precise lists and exact
+  terms in specs. Read [`prose-style.md`](prose-style.md); for substantive prose,
+  explicitly invoke `devrites-prose-craft` for its rewrite and completion check.
+- **Atomic commits, Conventional Commits.** One logical change per commit;
+  it builds + passes tests on its own. → [`git-workflow.md`](git-workflow.md)
+
+## Persistence before stopping (handoff discipline)
+
+Before any `rite-*` skill stops:
+- Open question? → `questions.md` (with `status`, `gate`, `slice`, `proposed`,
+  `raised_at`). Decision discussed? → `decisions.md`.
+- Assumption made? → `assumptions.md`. Drift raised? → `drift.md`.
+- Approach tried that **failed**? → a `## Dead ends` section in `decisions.md` (what you
+  tried, why it failed, what it rules out). Compaction and the next agent must not repeat a
+  dead end — an invalidated approach is load-bearing context.
+- Next-action ambiguous? → resolve to one command in `state.md`.
+- HITL pause? → write the `Awaiting human` block to `state.md` and set
+  `Status: awaiting_human` before stopping; resume via `$rite-resolve <qid> "<answer>"`.
+  See [`afk-hitl.md`](afk-hitl.md) for the full AFK / HITL contract.
+
+A skill that "stops" without doing this leaves the workspace lying.
+
+## Context hygiene (end of every phase)
+
+Long contexts degrade reasoning quality (Liu et al. 2023 "lost in the middle";
+"context rot" on long inputs). Act on context at **50–70% used, not 95%**.
+
+Every `rite-*` skill ends with a one-line **Session hygiene** advisory naming
+the right move (`/clear` vs `/compact`) and the single resume command. Full
+phase-by-phase guidance: [`context-hygiene.md`](context-hygiene.md).
+
+## Precedence
+
+**Project principles > project conventions > DevRites rules.** The rules fill
+gaps; they don't overwrite the project's choices. When the project's own
+conventions disagree with these rules, **project wins**.
+
+Two of those layers carry **opposite** authority, and the difference is
+load-bearing:
+- **Project principles** (`.devrites/principles.md`) — authored, prescriptive
+  invariants the project will not break. *Trusted and gating*: a change that
+  violates one is a defect, not a prior to weigh — a top-severity, blocking
+  finding (absent file = none declared = gate passes). → [`principles.md`](principles.md)
+- **Conventions** (`.devrites/conventions.md`) — learned, *descriptive* idioms.
+  An *untrusted prior*: a fresh read of the live code overrides a convention.

package/pack/generated/codex/skills/devrites-lib/reference/standards/definition-of-done.md

@@ -0,0 +1,16 @@
+# Definition of Done
+
+DevRites acceptance criteria answer “did we build the requested thing?” Definition of Done answers “is the change finished to DevRites quality?”
+
+A feature is done only when:
+
+1. Acceptance criteria are mapped to evidence.
+2. See-it-fail-first proof exists where behavior changed.
+3. Runtime/build/test/browser evidence is fresh and recorded.
+4. No unscoped edits, drive-by refactors, or hidden second systems remain.
+5. Project standards and declared principles are honored, or an approved exception is recorded.
+6. No hard gates remain open: HITL, AFK, red tests, stale evidence, drift, review blockers, or NO-GO.
+7. Risky work names rollback/recovery.
+8. Public behavior, command surface, docs, or architecture changes update docs/ADR where applicable.
+
+Use this as the standing bar in `rite-vet`, `rite-build`, `rite-prove`, `rite-seal`, and `rite-quick`; phase-specific standards still apply.

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

@@ -0,0 +1,71 @@
+# Deprecation & migration
+
+Code is a liability, not an asset. Every line carries ongoing cost — bugs to fix, dependencies
+to patch, security to maintain, the next engineer to onboard. Most teams build well and remove
+badly, so dead and superseded code accumulates. Removing code that no longer earns its keep, and
+moving users safely off the old path, is its own discipline — and a riskier one than writing new
+code, because the failure mode is breaking something you forgot depended on it.
+
+DevRites already **gates** the dangerous moves: destructive migration, auth/authz change,
+public-API break, and data-loss paths always pause ([`afk-hitl.md`](afk-hitl.md) irreversible-risk
+list). The gate stops you; this rule is the safe path it stops you to take.
+
+## Code is a liability
+Unused code is pure cost with no return — deleting earned-out code is a feature, not housekeeping.
+But "I think this is unused" is a guess; prove it (below) before you act on it.
+
+**Design for removal.** The cheapest deprecation is the one you planned when you built the thing.
+When adding a new system, ask "how would we remove this in three years?" — the answer forces a seam
+(a flag, an adapter, a single call site) that makes the eventual exit a contraction instead of a
+surgery. Code built with no exit in mind is what becomes a zombie (below).
+
+## Hyrum's law — observable behavior is the contract
+With enough consumers, *every* observable behavior is depended on by someone — not just the
+documented API, but the quirks: timing, error shapes, ordering, the off-by-one nobody noticed.
+Removing or changing a behavior you think is incidental can break invisible dependents. Assume a
+consumer relies on it; verify against real usage rather than the spec's intent.
+
+## Prove it's unused before you remove it
+- Find the dependents: callers, subscribers, stored data, external clients, scheduled jobs. Use a
+  code-intelligence index for blast radius ([`tooling.md`](tooling.md)), then confirm against
+  **runtime** usage — a log/metric on the path proves zero traffic in a way static search can't
+  ([`observability.md`](observability.md)). No-usage-confirmed beats no-usage-assumed.
+- If you can't prove zero usage, you're not removing — you're deprecating (below).
+
+## Expand → contract (parallel change)
+Never big-bang a breaking change. Three independently-shippable, independently-reversible steps:
+1. **Expand** — add the new path alongside the old; both work.
+2. **Migrate** — move consumers and data to the new path; watch the old path's usage fall to zero.
+3. **Contract** — remove the old path *only once telemetry confirms it's unused*.
+
+The same shape applies to data: add column → backfill → switch reads → drop the old column. Every
+destructive step has a rollback, or it doesn't ship.
+
+## Deprecate before delete
+- Mark the old path deprecated with a pointer to the replacement and a **removal trigger** — a
+  date or a condition ("when v1 traffic hits zero"), not a vague "soon". A deprecation with no
+  trigger is a permanent TODO.
+- Emit a usage signal on the deprecated path so the removal trigger is a measured fact, not a
+  hope ([`observability.md`](observability.md)).
+
+## The Churn Rule — you own the deprecation, you own the migration
+If you own the thing being deprecated, moving the consumers off it is *your* job, not theirs.
+"They'll migrate on their own" is how a deprecation stalls advisory for years. Either do the
+migration for them — a codemod, a backfill, a config flip they don't have to think about — or ship
+the change as a backward-compatible update that needs no migration at all. Announcing a deadline
+without providing the tooling, docs, and support to hit it isn't a migration; it's a break with a
+countdown.
+
+## Zombie code — nobody owns it, everybody depends on it
+The dangerous middle state is not dead code (safe to remove) but **zombie** code: no one maintains
+it, yet live consumers still call it. Signs — no commits in 6+ months, an active caller graph, no
+named owner, failing tests nobody fixes. A zombie can't stay in limbo: it either gets **invested
+in** (an owner, green tests, a real place in the architecture) or gets **removed** on the
+prove-unused → expand→contract path above. Leaving it untouched is choosing the worst option — an
+unmaintained dependency that breaks under someone who never signed up to fix it.
+
+## Scope
+A removal or migration is a feature with its own spec, slices, and evidence — not a drive-by
+delete while you're in another change. A surprise deletion in an unrelated diff is a red flag
+([`anti-patterns.md`](anti-patterns.md)), and a destructive step trips the seal's risk-and-rollback
+check regardless.

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

@@ -0,0 +1,119 @@
+# Developer experience
+
+When a change ships a surface another engineer has to *use* — a public API, a CLI, an SDK
+or library, a webhook, a config/env contract, an error message, or the getting-started path
+that introduces all of them — the developer using it is a user, and their experience is part
+of the change. Code that compiles and passes its tests can still strand the next developer at
+a cryptic error, a getting-started snippet that doesn't run, or an endpoint whose shape you
+have to read the source to learn. Un-tested DX is a claim, the same way un-run code is a claim.
+
+This rule is the developer-facing counterpart to [`performance.md`](performance.md): perf says
+*measure the speed before you assert it*; this says *measure the experience before you assert
+it*. It pairs with the [`devrites-api-interface`](../../../devrites-api-interface/SKILL.md)
+skill (which shapes the contract) — this rule **proves** the shape is usable.
+
+## Scope — when this applies
+
+Conditional, like [`performance.md`](performance.md) and [`observability.md`](observability.md).
+It applies when the diff changes a **developer-facing surface**:
+
+- a public/external **API** endpoint, response shape, or status-code contract;
+- a **CLI** command, flag, output, or exit code;
+- an **SDK / library / package** export, signature, or type;
+- a **webhook**, event payload, or integration contract;
+- a **config / env-var** interface a consumer must set;
+- an **error message, exit code, or failure response** a developer reads to recover;
+- the **getting-started path** — README, install steps, quickstart, the first-run docs.
+
+Skip it for pure-internal refactors, private helpers, app-only UI (that's
+[`devrites-frontend-craft`](../../../devrites-frontend-craft/SKILL.md) /
+`devrites-frontend-reviewer`), docs-only typo fixes, and config that no external consumer
+touches. Don't DX-review a change with no developer-facing surface — the same scope discipline
+as the rest of the conditional rules. End-user UX is a different axis; this rule is about the
+*developer* consuming the surface.
+
+## The boomerang — predict at plan, measure at prove, reconcile at seal
+
+DevRites already runs a predict-then-prove spine (the vetted `test-plan.md` coverage target at
+`$rite-vet`, proven at `$rite-prove`, gated at `$rite-seal`). DX rides the same spine, and the
+gap between the two ends is the signal:
+
+1. **Predict** — at `$rite-vet`, when a developer-facing surface is in scope, score the *planned*
+   surface against the dimensions below and write a predicted scorecard to `devex.md` (the
+   estimate, e.g. "time-to-hello-world: ~3 min"). This is cheap and pre-build; it forces the
+   ergonomics question before the contract sets.
+2. **Measure** — at `$rite-prove`, actually exercise the surface (run the getting-started flow,
+   call the endpoint, invoke the CLI, trigger the error) and record the *measured* scorecard with
+   evidence: real time-to-hello-world, the verbatim error text, the screenshot of the docs page.
+3. **Reconcile (the boomerang)** — at `$rite-seal`, compare predicted against measured. A material
+   gap — "the plan said 3 minutes, the getting-started flow actually took 8 and step 4 errored" —
+   is a finding, not a rounding error. The estimate was wrong *or* the surface regressed; either
+   way the developer using it pays, and the gap is exactly what a single end-state score would hide.
+
+The boomerang is what makes DX a measured axis rather than an opinion: the prediction is on
+record, so the measured reality can falsify it.
+
+## The scorecard — what to score
+
+One entity, one name: call the metric **time-to-hello-world (TTHW)** consistently, not "onboarding
+time" in one place and "setup time" in another. Score these dimensions; only the ones the diff
+touches:
+
+- **Discoverability** — can a developer find the entry point without reading the source? Is the
+  new surface named, exported, and documented where they'll look?
+- **Time-to-hello-world (TTHW)** — wall-clock from "I have the repo/package" to "I got one
+  successful call/response/render". The headline number; measure it, don't estimate it at seal.
+- **Getting-started friction** — does the quickstart run *as written*, copy-pasted, on a clean
+  checkout? Every undocumented prerequisite, wrong command, or missing step is friction.
+- **Error-message quality** — does a failure say *what* failed, *why*, and *how to recover*, with
+  the relevant ids (never secrets — see [`security.md`](security.md))? A bare stack trace, a
+  silent exit, or "an error occurred" is a defect on a developer-facing path.
+- **Ergonomics & consistency** — does the surface match the project's existing conventions
+  (naming, argument order, pagination, error shape)? An inconsistent new endpoint taxes everyone
+  who learned the old ones. Sensible defaults; the common case is one call.
+- **Docs accuracy** — examples are copy-pasteable and correct, the signature in the docs matches
+  the code, and changed behavior updated its docs in the same change ([`documentation.md`](documentation.md)).
+
+## Measure, don't assert
+
+The same discipline as `performance.md` "measure first" and `testing.md` "see it fail first":
+
+- **Run it, don't read it.** A scorecard backed by "the code looks fine" is Source mode and says
+  so. The graded scorecard comes from actually invoking the surface — the getting-started flow on
+  a clean state, the real CLI `--help`, the real error path — and recording what happened.
+- **Quote the artifact.** Paste the verbatim error string, the exact failing command, the measured
+  TTHW; for a docs/quickstart page, capture it through the browser-proof ladder
+  ([`../skills/devrites-browser-proof/SKILL.md`](../../../devrites-browser-proof/SKILL.md)) and
+  describe the screenshot. A path is not proof; the observation is.
+- **No measurement → no DX claim**, and usually no finding above Suggestion. "Feels confusing" is
+  a hypothesis to test, not a verdict.
+
+## The gate — severity by who-pays
+
+DX findings carry the standard labels (Critical / Important / Suggestion / Nit / FYI), scaled to
+the cost the consumer bears, not to how polished it feels:
+
+- A **public/external contract that ships broken or wrong** — a documented command that errors, an
+  endpoint whose response contradicts its contract, a getting-started flow that can't complete — is
+  **Important**, and **Critical** when it's a frozen public surface (the principles-gated public-API
+  invariant, [`principles.md`](principles.md)) or an irreversible break.
+- A **measured DX regression** against the predicted scorecard with no recorded reason is a
+  finding the boomerang surfaces at seal — at least **Important** when it lands on a public surface.
+- An **unactionable error message** on a developer-facing failure path is **Important** — the
+  on-call test ([`observability.md`](observability.md)) applied to the consumer instead of the operator.
+- Inconsistent-but-working ergonomics, a thin doc, a missable default → **Suggestion**, unless the
+  spec made it acceptance.
+
+## The artifact — `devex.md`
+
+When a developer-facing surface is in scope, the workspace carries `devex.md`: the **predicted**
+scorecard (from `$rite-vet`), the **measured** scorecard with evidence (from `$rite-prove`), and
+the **boomerang delta** (reconciled at `$rite-seal`). Absent surface → no `devex.md`, and the gate
+passes silently — never block a change for the *absence* of a DX surface, the same no-op discipline
+as the principles and spec-grammar gates.
+
+## Scope discipline
+
+Review the developer-facing surface the change *touches*. A surface the diff didn't change is not
+this change's job; a project-wide DX audit (every endpoint, the whole CLI) is its own effort —
+record it as a follow-up, don't smuggle it into an unrelated change.

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

@@ -0,0 +1,51 @@
+# Development workflow
+
+Ship small, integrate often, keep the main branch releasable. This is the general
+engineering loop the DevRites feature lifecycle (spec → define → build → prove → polish →
+review → seal → ship) runs on top of.
+
+## Work in small batches
+- Break work into thin, independently shippable slices and integrate them frequently —
+  ideally merging to the main branch at least once a day.
+- Small batches shrink merge pain, surface integration problems early, and get real
+  reviews. Large batches hide defects and stall.
+
+## Short-lived branches, trunk always green
+- Prefer short-lived branches off the main branch (trunk-based). Long-running branches
+  drift and create painful merges.
+- The main branch is **always in a releasable state**. Validate every change through a
+  **fast, reliable CI pipeline** (tests + build) before it merges.
+- Hide incomplete work behind a **feature flag / toggle** rather than a long branch, so
+  partial work can land without blocking releases or breaking the trunk.
+
+## Review gate
+- Every change is reviewed before merge (see `code-review.md`). Keep reviews fast — slow
+  reviews push people back toward big, risky batches.
+- Set expectations on PR size and merge cadence: small, frequent, single-concern.
+
+## Definition of done
+The **Definition of Done** is the project's *standing bar* — the floor every change clears,
+distinct from a slice's **acceptance criteria** (which change per slice and say what *this* work
+must do). Acceptance criteria answer "did we build the right thing"; the DoD answers "is it
+shippable at all". The bar does not move with deadline pressure — a Definition of Done that gets
+renegotiated each time is not one. Apply it in tiers so the cost matches the scope:
+
+- **Every slice** — Correctness + Quality: meets its acceptance criteria with **evidence**
+  (tests/build/runtime — see `testing.md`), behaviour verified at runtime not just compiled; tests
+  and build green in CI; reviewed and **within scope, no unrelated refactor snuck in**; edge and
+  error paths handled, not only the happy path.
+- **Every feature** — Integration + Documentation: works with the rest of the system, migrations/
+  config/flags accounted for, backward compatibility considered for any public-interface change;
+  docs/comments touched are updated (`documentation.md`) and describe the *current state in timeless
+  language*, not the change history.
+- **Every release** — Ship-readiness: security reviewed for any untrusted input/auth/data
+  (`security.md`), observability on new critical paths (`observability.md`), a **rollback for
+  anything risky**, and a **human has reviewed and approved before merge**.
+
+Two invariants across all tiers: evidence post-dates the code it proves — edits made after
+`$rite-prove` (polish/review) require re-proof before seal, stale evidence is not proof; and
+"tests pass" is not a synonym for done. "Code written" is not done. "Proven and reviewed" is.
+
+## Incremental delivery
+Deliver a working end-to-end path each slice, then expand. Avoid the "90% done, nothing
+proven" pile-up — one finished, verified slice beats five half-built ones.

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

@@ -0,0 +1,35 @@
+# Documentation
+
+Write the documentation that saves the next person time — no more, no less.
+
+## Explain why, keep it current
+- Document **intent and decisions**, not a restatement of the code. The *why* is what
+  can't be recovered from reading the source.
+- Out-of-date docs are worse than none. Update docs in the same change that changes the
+  behavior; stale docs erode trust in all docs.
+
+## Record decisions
+- Capture significant choices and their rationale (an ADR-style note: context, decision,
+  consequences). Future readers need to know *why this and not the obvious alternative*.
+  DevRites records these in `decisions.md`.
+- Note the trade-off you accepted and what would change the decision.
+- **The rejected alternatives are the highest-value part.** Anyone can read the decision from the
+  code; only the ADR records the options you weighed and *why each lost*. List them with the reason
+  each was rejected, or the note answers nothing the source doesn't already show.
+- **An ADR has a lifecycle:** `PROPOSED → ACCEPTED → SUPERSEDED / DEPRECATED`. When a decision
+  changes, write a **new** ADR that references and supersedes the old one — never edit or delete the
+  original, or you erase the record of why the project once chose differently.
+
+## What to document
+- **Public surfaces**: APIs, module boundaries, and config — inputs, outputs, errors,
+  and gotchas. Writing the contract down is the first test of the design: documenting a public
+  interface surfaces its rough edges before the code sets around them.
+- **READMEs that actually run**: setup, the real commands to build/test/run, and how to
+  get a working environment. Keep examples copy-pasteable and correct.
+- **Non-obvious constraints**: invariants, ordering requirements, "do not call X before
+  Y", and known limitations.
+
+## Keep it lean
+- Don't document the obvious or duplicate what the type signatures already say.
+- Prefer one good example over three paragraphs of prose.
+- Put long reference material where it's loaded on demand, not inline everywhere.

package/pack/generated/codex/skills/devrites-lib/reference/standards/edge-case-trace.md

@@ -0,0 +1,19 @@
+# Edge-case trace
+
+Use this when a diff changes branching logic, boundaries, validation, deletion, or a claim that a path is safe.
+
+## Trace
+
+1. **Scope the changed surface.** Name the changed function/API/state/config and the nearest observable caller.
+2. **Enumerate explicit paths.** Walk each `if`/`switch`/loop/error branch and boundary value the changed surface handles.
+3. **Enumerate fixed-set siblings.** If the change special-cases members of a known set — enum values, statuses, sentinels, flags, roles, modes — list the untouched siblings too. A handled `pending`/`failed` branch makes `success` an implicit branch to check.
+4. **Check deletion contracts.** For removed or replaced code, name the behavior or contract it carried and where the diff re-establishes it. If it was intentionally retired, cite the spec/decision that retires it.
+5. **Report only reachable gaps.** A finding needs `file:line`, trigger condition, missing guard/handling, and concrete consequence. If the path is already handled, drop it silently.
+
+## Output shape
+
+```md
+[Important] path:line — <trigger> reaches <unhandled path>; add <minimal guard/handling>. Consequence: <what breaks>.
+```
+
+Use the caller's severity scale. Do not create a separate edge-case score.

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

@@ -0,0 +1,80 @@
+# Elicitation — a move-set for the thinking phases
+
+The thinking phases (`$rite-temper` on the spec, `$rite-vet` on the plan) default to one shape each
+— a pre-mortem, a plan review. That's a floor, not a ceiling. When a section needs deeper thought,
+this is the menu you reach into: named reasoning techniques, each with the shape it produces, so
+"make this stronger" becomes a concrete move instead of a vibe.
+
+## How to use it (progressive — no ceremony by default)
+1. Look at the **one section** in front of you (a requirement, a risk, an estimate, a boundary).
+2. Read its **risk**, then pull the 3–5 techniques below whose *When to reach for it* matches.
+3. Present them as a short numbered menu; the human picks one (or `skip`).
+4. Run that technique on that section, apply the result, move on.
+
+Selection is by the section's risk, not taste. Reach for the row that fits:
+
+| The section is… | Reach for |
+|---|---|
+| an irreversible / boundary / auth / data-model decision | Red-Team vs Blue-Team · Assumption Audit · Pre-Mortem |
+| a vague or contested requirement | Steelman-then-Attack · Devil's Advocate · Five Whys |
+| an estimate, sizing, or a "how long / how risky" | Delphi · Reference-Class Forecast |
+| a design with more than one plausible shape | Tournament (A vs B) · Inversion · Analogy Mapping |
+| a spec that feels *too* big or *too* small | Scope Extremes (MVP vs Gold-plate) · YAGNI Pass |
+| a risk surface you suspect is under-explored | Chaos Scenarios · Edge-Case Hunt · Second-Order Effects |
+
+## The techniques
+
+Each entry is **name — when to reach for it — the shape it produces** (`→` reads "then").
+
+### Sharpening a claim
+- **Steelman-then-Attack** — a requirement or approach you're inclined to accept. Build the
+  *strongest* case for it → then attack that strongest form. Survives → keep; falls → revise.
+- **Devil's Advocate** — consensus formed too fast. One voice argues the opposite in good faith →
+  surface the objection the room skipped.
+- **Assumption Audit** — a plan resting on unstated beliefs. List every assumption the section
+  makes → mark each *load-bearing / verified / unverified* → the unverified load-bearing ones are
+  the work.
+- **Five Whys** — a stated requirement whose *reason* is fuzzy. Ask "why" five times down from the
+  ask → reach the root need (often narrower or different than the surface ask).
+
+### Stress-testing a decision
+- **Pre-Mortem** — before committing an irreversible choice. Assume it's six months later and this
+  failed → write the failure story → each cause becomes a mitigation or a blocking question. (This
+  is `$rite-temper`'s default; the others deepen it.)
+- **Red-Team vs Blue-Team** — a security, trust-boundary, or adversarial-input surface.
+  `defense → attack → hardening`: state the defense, attack it as a hostile party, harden the gap.
+- **Inversion** — "how do we make X good?" stalls. Ask instead "how would we *guarantee X fails*?"
+  → invert each failure into a requirement.
+- **Second-Order Effects** — a change that touches shared surface. For each first-order effect ask
+  "and then what?" twice → surface the downstream consequence the diff hides.
+
+### Sizing and estimating
+- **Delphi** — an estimate one person is anchoring. Gather independent estimates *without* seeing
+  each other → reveal → discuss the spread → re-estimate → converge. Kills anchoring.
+- **Reference-Class Forecast** — "this'll be quick." Find 3 past changes of the same *class* → use
+  their actual cost as the base rate, not the inside view.
+
+### Widening the option space
+- **Tournament (A vs B)** — two plausible designs. Put them head-to-head on the *decision hinge*
+  (the one axis that actually differs) → pick on that axis, not on a feature checklist.
+- **Analogy Mapping** — a novel problem. "What is this *like* that's already solved?" → borrow the
+  solved structure, note where the analogy breaks.
+- **Scope Extremes** — a spec of uncertain size. Describe the *MVP* (smallest thing that ships
+  value) and the *gold-plated* version → the right scope is usually named by the gap between them.
+- **YAGNI Pass** — a plan carrying "might need it later." For each speculative piece, demand a
+  *current* acceptance criterion → no criterion, cut it to a follow-up.
+
+### Finding what's missing
+- **Edge-Case Hunt** — a happy-path-shaped spec. Walk empty / boundary / invalid / concurrent /
+  huge-or-weird input for each element → each uncovered case is a missing criterion.
+- **Chaos Scenarios** — a system with external dependencies. "What if the DB is down / the API
+  times out / the clock jumps / the input is hostile?" → each becomes a failure-mode requirement.
+- **Completeness Critic** — end of a section. Ask only "what's *missing* — a modality not covered, a
+  claim not verified, a flow with no path?" → the answer is the next round of work.
+
+## The one rule
+Run the technique on the **section in front of you**, not the whole document — a move applied to
+everything is a move applied to nothing. Record what it changed in the phase artifact (a new
+requirement, a mitigation, a blocking question), not just that you ran it.
+
+A project can append its own house techniques to this file — same three-column shape.

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

@@ -0,0 +1,33 @@
+# Error handling
+
+Errors are part of the contract, not an afterthought. Make failure loud, local, and
+recoverable.
+
+## Fail fast
+- Validate preconditions at the top; stop the moment state is invalid, close to the root
+  cause. Don't let bad data propagate and surface as a confusing failure three layers
+  later.
+
+## No silent catches
+- Never swallow an error to make a problem "go away" — that hides bugs and corrupts
+  state silently.
+- Catch the **narrowest** error you can actually handle, not a blanket catch-all. A
+  bare/broad catch masks unrelated failures.
+- If you catch, either recover meaningfully, or rethrow/wrap with added context. Don't
+  log-and-continue past an error you didn't handle.
+
+## Meaningful messages
+- Error messages state what failed, the relevant context (ids, inputs — not secrets),
+  and ideally how to recover. Cryptic messages cost hours.
+- Distinguish *expected* failures (validation, not-found) from *unexpected* (bugs);
+  handle the first as flow, surface the second.
+
+## Fail closed (security-relevant paths)
+- On error in an auth/permission/transaction path, **deny and roll back** — never
+  default to granting access or committing partial state.
+
+## Logging
+- Log key events (failures, access violations, validation errors) with enough context to
+  debug. Prefer structured logs (key/value or JSON) over string soup.
+- **Never log secrets, credentials, tokens, or personal data.** Show users a clear,
+  non-revealing message; keep the detail in the logs for the team.

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

@@ -0,0 +1,65 @@
+# Git workflow
+
+History is documentation. Keep it clean, atomic, and readable.
+
+## Conventional Commits
+Format: `type(scope): subject`
+- **type**: `feat fix docs style refactor perf test build ci chore revert` (lower-case).
+- **scope**: the area changed (lower-case).
+- **subject**: imperative mood, no leading capital, no trailing period
+  ("add export endpoint", not "Added export endpoint.").
+- Keep the header short (~50, hard cap ~72). Put the *why* in the body, wrapped, after a
+  blank line. Reference issues in the footer.
+
+```
+feat(export): stream large CSV exports
+
+Buffering the whole file OOM-ed on >100k rows. Stream rows to the
+response instead so memory stays flat.
+
+Refs: #123
+```
+
+## Atomic commits
+- One logical change per commit; it should build and pass tests on its own.
+- Don't mix refactor + behavior change in one commit — split them so each is reviewable
+  and revertible.
+
+## Small, focused branches/PRs
+- One concern per branch. Short-lived; rebase/merge per the project's convention.
+- Keep PRs small (see `code-review.md`) so they get a real review.
+
+## Change summary — prove the scope
+When you hand back a change, state what you deliberately left alone, not only what you touched.
+A **"Things I didn't touch (intentionally)"** line — the adjacent smells you noticed and declined
+to fix — proves the diff is feature-scoped ([`core.md`](core.md) rule 7) and matches
+`touched-files.md`, rather than an unsolicited renovation the reviewer has to untangle from the
+real change. Noticed-but-not-fixed becomes an FYI follow-up, never a silent addition to this diff.
+
+## Merge conflict recovery
+When git is mid-merge or mid-rebase, recover before other workflow work:
+
+1. Inspect state: `git status --short --branch`, then note whether this is a merge or rebase.
+2. For each conflicted file, identify **our intent** and **their intent** before editing.
+3. Resolve each hunk by preserving both intents when possible; if intents conflict, pick one and
+   record the trade-off in the commit/PR body.
+4. `git add` the resolved files, then run the smallest relevant checks.
+5. Finish with `git merge --continue` or `git rebase --continue`; abort only when the chosen
+   branch direction is wrong, not because a hunk is annoying.
+
+## Versioning & changelog
+- **The version is a promise.** Semver encodes what a consumer may rely on. A "patch" that
+  changes behaviour someone depended on is a major wearing a disguise — every observable behaviour
+  is a contract (Hyrum's law, [`deprecation.md`](deprecation.md)). When unsure whether a change is
+  breaking, assume it is; a surprise major is far cheaper than a broken consumer.
+- **The tag is the single source of truth** for the version. Derive it from the tag; never
+  hand-edit a version copied across `package.json`, a constant, and a header — three copies drift,
+  one tag can't.
+- **A changelog is not the git log.** Curate it by user impact — what a consumer must know to
+  upgrade — not by commit. Write the entry in the same change that earns it, while the impact is
+  fresh; a changelog reconstructed later is a guess.
+
+## Never commit
+- Secrets, credentials, tokens, or `.env` files. If one lands in history, rotate it and
+  scrub it — deleting the file in a later commit is not enough.
+- Generated artifacts, dependencies, or large binaries that belong in ignore rules.