devrites 2.6.1 → 3.0.1

package/pack/generated/claude/skills/devrites-lib/reference/standards/skill-authoring.md

@@ -0,0 +1,105 @@
+# Skill authoring
+
+Use this when creating or editing DevRites skills.
+
+## Distribution
+
+DevRites is installed through the npm package (`npx devrites ...`). Claude Code
+and Codex files are generated host artifacts copied by that installer, never
+Claude/Codex plugin-store surfaces. Edit the canonical Claude-authored pack sources,
+rebuild host artifacts, then validate.
+
+## Surface lifecycle
+
+- **Promoted** — shipped in `pack/`, documented in `docs/skills.md` and
+  `docs/command-map.md`, and covered by validation.
+- **Draft** — local/research material outside the shipped pack.
+- **Deprecated** — shipped only as a compatibility bridge with a replacement and
+  removal note.
+- **Research** — notes under `docs/research/`; never installed.
+
+## Description
+
+The description is an invocation pointer, not documentation.
+
+- **Model-invoked** skills pay context load so the agent or another skill can reach them;
+  omit `disable-model-invocation` and give them trigger-bearing descriptions.
+- **Explicit-only** skills pay human cognitive load instead; set
+  `disable-model-invocation: true`, keep the description a human summary, and expose them
+  through `/rite`. The Codex generator must map this to
+  `policy.allow_implicit_invocation: false` without stubbing a public description.
+- Keep public model-invoked skills under 90 words, internal specialists under 75,
+  explicit-only skills under 30, and `devrites-lib` under 60.
+- Front-load one stable leading word that is also used in prompts/docs when that concept
+  should trigger the skill.
+- Use one clear trigger branch per phrase; repeated `Use when` or `Not for` means the branch should collapse or move into the body.
+- State the **defining constraint** — the one fact that separates this skill from its nearest sibling (e.g. `/rite-seal` decides, `/rite-ship` mutates git). It is the strongest trigger discriminator the routing evals measure.
+- Put examples, edge cases, and rationale in `SKILL.md` body or a reference file, not in frontmatter.
+
+## Body
+
+- Put ordered work as steps, each ending in a checkable completion criterion.
+- Move branch-only reference behind a direct file pointer.
+- Keep one meaning in one place; prefer a shared reference over repeated prose.
+- Add an explicit setup/engine pointer only where the skill produces *wrong* output without
+  the config; where it merely sharpens output, plain prose ("the conventions ledger, if
+  present") is enough — cargo-culted pointers spread as sediment.
+
+## Router and docs
+
+- Public `rite-*` skills must appear in the `/rite` router, `docs/skills.md`,
+  and `docs/command-map.md`.
+- Internal `devrites-*` skills must stay out of the public command menu unless
+  named as implementation detail.
+- A public skill's docs card states purpose, when to invoke, where it fits,
+  its defining constraint (as plain prose, never a labelled aside), and what
+  evidence proves completion. Do not copy the full `SKILL.md` process into docs.
+- Model-invoked skills need positive/negative implicit-routing evals. Explicit-only
+  public skills need direct-command evals; non-workflow libraries are exempt explicitly.
+
+## Source intake
+
+External skill packs, articles, and examples are references, not authority.
+
+- Record source, commit/date, and files read in `docs/research/`.
+- Adopt the DevRites principle, not foreign names or workflow chains.
+- Name rejected ideas so future maintainers do not re-litigate them.
+- Add a validator or eval when the adoption creates a durable product contract.
+
+## Match the form to the failure
+
+Pick the instruction form from the *observed* failure, not by habit:
+
+- Agent **violates a rule under pressure** → hard guardrail + rationalization rebuttal
+  (the `anti-patterns.md` table form) + a red-flag stop list.
+- Output has the **wrong shape** (bloated, buried, missing emphasis) → a positive recipe or
+  template with REQUIRED slots. Prohibitions backfire here — wording tests show a "don't"
+  list produces *more* of the unwanted shape than no guidance at all.
+- Agent **omits a required element** → a structural slot in the artifact template, not a
+  prose reminder.
+- Behavior should **depend on a condition** → a conditional keyed to an observable
+  predicate, not an unconditional rule with exemption clauses ("unless it matters" reopens
+  the negotiation).
+
+## Wording evals
+
+A wording change to behavior-shaping content is a code change — prove it:
+
+1. **Baseline first (no-guidance control).** Run the scenario without the new wording; if
+   the control doesn't exhibit the failure, the guidance is a no-op — don't author it.
+2. **≥5 reps per variant, fresh context each.** Single samples lie; read every flagged run.
+3. **Variance is a signal.** Five runs, five interpretations = the wording isn't binding —
+   rewrite, don't average.
+
+## Pruning
+
+Delete no-op instructions the model already follows. Keep positive target behavior; use prohibitions only for hard guardrails.
+
+Read a draft for its **negative space**: every decision the skill declines to make is
+delegated to the model's priors, not left neutral. Decide each silence deliberately — fill
+it, or leave it open as a real branch.
+
+
+## Contribution preflight
+
+New skills are expensive routing surface. Before adding one, document the catalog search, why a reference inside an existing skill is insufficient, required eval coverage, host command parity, and whether the surface is public `rite-*` or internal `devrites-*`. Public commands need docs, evals, generated Claude/Codex artifacts, and a reply-contract marker. Internal skills need a clear trigger boundary and "when not to use" section. Agents need role/scope, read/write mode, output format, and composition block; only `devrites-slice-wright` may write.

package/pack/generated/claude/skills/devrites-lib/reference/standards/spec-grammar.md

@@ -0,0 +1,185 @@
+# Spec grammar — testable requirements, parseable by tooling
+
+Acceptance criteria are the contract the seal checks ([`testing.md`](testing.md),
+[`code-review.md`](code-review.md)). Prose criteria work, but a requirement written as free
+text is graded by a human reading carefully — and an ambiguous one ("handle errors
+gracefully") slips past every gate because nothing can falsify it. This rule adds an
+**optional, recommended structure** that makes a behavioral requirement testable by
+construction and parseable by a deterministic linter, so the spec phase catches a malformed
+requirement before `/rite-define` plans against it.
+
+It is the grammar counterpart to [`testing.md`](testing.md): testing says *prove every
+behavior*; this says *write each behavior so it can be proven*.
+
+## Progressive rigor — when to use the structured form
+
+Match the rigor to the stakes; don't pay grammar ceremony for a one-liner.
+
+- **Simple / routine change** — the flat checklist form is correct and stays. One bullet per
+  criterion, each tagged with an `AC-###` id:
+  ```markdown
+  ## Acceptance criteria
+  - [ ] AC-001: export returns a CSV with a header row
+  - [ ] AC-002: an empty dataset returns 204, not an empty 200
+  ```
+- **Behavioral / high-risk / cross-boundary requirement** — auth, data model, state machine,
+  public API, money, a migration, anything with non-obvious edge cases — use the structured
+  **Requirement / Scenario** grammar below. The act of writing the WHEN/THEN forces the edge
+  cases into the open at spec time, where they're cheapest to resolve.
+
+A spec mixes both: most criteria stay flat bullets; the two or three that carry real risk get
+the structured treatment. **Absence of structured requirements is never a failure** — the
+validator no-ops on a flat-bullet spec, the same discipline as the principles gate
+([`principles.md`](principles.md)).
+
+## The structured form
+
+```markdown
+### Requirement: Session tokens expire after inactivity
+The system SHALL reject any session token older than 15 minutes of inactivity.
+
+#### Scenario: token past the inactivity window
+- [ ] AC-004: **WHEN** a request presents a token whose last use was > 15m ago
+            **THEN** the request is rejected with 401 and the token is revoked
+
+#### Scenario: token within the window
+- [ ] AC-005: **WHEN** a request presents a token last used < 15m ago
+            **THEN** the request is served and the last-use timestamp advances
+```
+
+The rules the validator enforces (`devrites-engine spec-validate`):
+
+- **`### Requirement: <name>`** — a level-3 heading. Its block MUST carry a **SHALL** or
+  **MUST** statement (in the header or the body) describing the core behavior. Keep the name
+  descriptive and under ~50 characters.
+- **Header identity is the key.** Requirement names are **unique** within a spec — tooling (and
+  any future spec sync) matches a requirement by its header text, so two requirements can't
+  share a name. Renaming a requirement is a remove + add, not an in-place edit, so the change
+  is visible.
+- **`#### Scenario: <name>`** — every requirement owns **at least one**. A requirement with no
+  scenario is an assertion no test can target.
+- **WHEN / THEN** — every scenario states a trigger (**WHEN**) and an observable outcome
+  (**THEN**); chain extra conditions with **AND**. Keywords are uppercase so they parse
+  unambiguously. A scenario missing either half isn't falsifiable.
+
+## Behavior first — WHAT, not HOW
+
+A spec requirement describes observable behavior, not the implementation that delivers it
+(the spec stays technology-agnostic — see `rite-spec/reference/spec-template.md`). "**THEN**
+respond 401" is behavior; "**THEN** call `AuthGuard.reject()`" leaks the design and locks the
+plan before `/rite-define` has chosen it. Name the input, the observable output, and the state
+change — not the function, class, or library. Implementation belongs in `plan.md`, not the
+requirement.
+
+Acceptance criteria are **surface-anchored**: they observe the outermost surface the user or
+system can see. If the feature is an API contract, the THEN names the response shape/status; if it
+is a UI flow, the THEN names the visible state. Internal rows, helper calls, and emitted logs can
+support proof, but they are not the criterion unless the spec's surface is explicitly internal.
+
+## How it composes (no new gate, no duplication)
+
+- **`AC-###` ids nest inside scenarios.** Tag each scenario's checkable line with an `AC-###` id
+  exactly as the flat form does. The same `devrites-engine check-acceptance` grades it against `seal.md` at
+  the end of the lifecycle — this grammar checks the requirement's **shape**, that script
+  checks its **proof**. The two compose; neither replaces the other.
+- **`/rite-prove` and `/rite-review` get concrete hooks.** Each scenario is one behavior to
+  prove and the test analyst's unit of "is this actually covered" — the WHEN/THEN maps
+  straight to an arrange/assert ([`testing.md`](testing.md)).
+- **The spec-quality checklists still apply.** The grammar makes a requirement *parseable*; the
+  `checklists/<domain>.md` "unit tests for English" still score whether it's *complete and
+  measurable* ("is 'prominent' quantified?"). Structure doesn't excuse vagueness inside a THEN.
+
+## Outcome metrics are not acceptance criteria
+
+A **buildable** acceptance criterion names an observable behavior a slice delivers and a test
+proves — "export returns a CSV with a header row", "a token past 15m is rejected with 401". An
+**outcome metric** names a post-launch business result — "reduce support tickets 50%", "lift
+signup conversion 3pts", "cut p95 latency in prod under real traffic". The distinction is not
+pedantic: it decides what the coverage gate is allowed to check.
+
+Tag only buildable criteria with an `AC-###` id. An outcome metric carries no id and lives under
+a separate **`## Success metrics`** heading:
+
+```markdown
+## Acceptance criteria
+- [ ] AC-001: export returns a CSV with a header row      # buildable — a slice + a test
+
+## Success metrics                                        # outcome — no AC id, not slice-mapped
+- Support tickets about export drop by half within a quarter
+```
+
+Why the split earns its place: an outcome metric tagged `AC-###` poisons the coverage gate in
+both directions. `devrites-engine analyze` flags it CRITICAL forever — no slice can `Satisfies:` a KPI —
+so a genuinely complete plan reads as uncovered. And `devrites-engine check-acceptance` can never mark it
+proven at `/rite-seal`, because no end-to-end test run inside the feature observes a quarter of
+production traffic. The metric still matters — it's *why* the feature exists — but it belongs to
+intent (`brief.md` / `spec.md` overview), not to the criteria the lifecycle mechanically proves.
+The load-bearing test: **can one slice make this true and one test show it?** If no, it's a
+success metric, not an acceptance criterion. (`analyze` scopes its coverage count to `AC-###`
+ids, so an untagged `## Success metrics` line is correctly ignored by the gate.)
+
+## The validator — `devrites-engine spec-validate`
+
+Deterministic, zero-token. Run it on the workspace (or a spec path) at the spec readiness gate:
+
+```bash
+devrites-engine spec-validate .devrites/work/<slug>
+```
+
+Exit codes: `0` valid (or no structured requirements — nothing to lint), `1` grammar
+violation(s) with `file:line` locations, `2` usage, `5` missing `spec.md`. A non-zero exit is a
+blocking spec-readiness failure: fix the requirement, never soften the check. It runs as part
+of `/rite-spec`'s readiness gate and is safe to re-run any time the spec changes.
+
+## Delta form — when the capability ledger already holds this behavior
+
+The Requirement / Scenario block is the unit the **capability ledger** stores — the living
+`.devrites/specs/<capability>/spec.md` record of *what the system does now*, folded in on ship
+([ledger reference](../../../rite-ship/reference/ledger.md)). When a feature changes behavior a
+ledger already describes, write its spec as **deltas against the ledger** instead of a flat
+snapshot, so the change — not merely the end state — is explicit and the fold is unambiguous.
+
+Group the structured `### Requirement:` blocks under three H2 sections, each tagged with the
+capability it folds into. One feature spec MAY carry deltas across several capabilities:
+
+```markdown
+## ADDED Requirements — capability: theming
+### Requirement: Dark mode honors the system preference
+The system SHALL default to the OS colour-scheme on first load.
+#### Scenario: no stored preference
+- [ ] AC-010: **WHEN** a first-time visitor loads the app **THEN** the theme matches the OS setting
+
+## MODIFIED Requirements — capability: settings-ui
+### Requirement: Settings exposes a theme control
+<the full new version of the requirement — not just the diff>
+
+## REMOVED Requirements — capability: theming
+### Requirement: Theme is hard-coded to light
+Removed — superseded by system-preference detection.
+```
+
+Fold semantics on `devrites-engine ledger sync` — **ADDED** appends, **MODIFIED** replaces the
+same-named requirement, **REMOVED** deletes it. Matching is by **header identity** (the rule
+above: names are unique and a rename is a remove + add), so the section MUST use the exact ledger
+header text for MODIFIED / REMOVED.
+
+- **The `— capability: <name>` suffix is the fold target.** Omit it and the fold defaults to the
+  feature slug — correct for a single-capability feature; name it explicitly when a feature spans
+  more than one, or when the capability differs from the slug.
+- **Pick the kind against the current ledger, not from memory.** `devrites-engine ledger show
+  <capability>` prints what it holds. A real change marked ADDED yields two competing
+  requirements; new behavior marked MODIFIED has nothing to replace.
+- **Greenfield stays flat.** A capability with no ledger entry is all-new — write plain
+  `### Requirement:` blocks with no delta H2; the first `ledger sync` seeds the capability as if
+  every block were ADDED. Never pay delta ceremony for behavior that has no prior record.
+
+Validate the classification deterministically at the spec gate — `--against` points the linter at
+the ledger root so it flags an ADDED that already exists or a MODIFIED/REMOVED that doesn't:
+
+```bash
+devrites-engine spec-validate .devrites/work/<slug> --against .devrites/specs
+```
+
+Exit `1` on a mismatch (a blocking spec-readiness failure); `0` when the deltas reconcile. The
+plain-grammar checks (SHALL, WHEN/THEN, unique headers) run in the same pass — delta H2 headers
+are transparent to them, so a flat spec and a delta spec lint identically.

package/pack/generated/claude/skills/devrites-lib/reference/standards/test-proof-checklist.md

@@ -0,0 +1,9 @@
+# Test proof checklist
+
+- New behavior has an asserting test, preferably written before implementation.
+- The test was seen fail for the right reason.
+- Verification commands and relevant output are recorded.
+- Regression, edge, and error paths match the acceptance criteria.
+- Passing existing tests alone is not proof of the change.
+
+Detailed standard: `testing.md`.

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

@@ -0,0 +1,162 @@
+# Testing
+
+Tests are evidence. They exist to prove behavior and to catch regressions — not to hit a
+coverage number.
+
+## Shape: a pyramid
+- **Many** fast, isolated unit tests at the base.
+- **Some** integration tests for how components actually fit together.
+- **Few** end-to-end tests for critical user journeys (they're slow and the most
+  flake-prone — reserve them for what matters).
+
+Size by **resource cost**, not by folder. A **small** test runs in one process, no I/O — the
+base of the pyramid, and the only size allowed to be many. A **medium** test touches the local
+machine (filesystem, a container, `localhost`). A **large** test crosses the network or a real
+external service — the flaky, slow tier E2E lives in. Push every behavior to the smallest size
+that can still prove it; a behavior provable small but written large is a slow test you'll
+learn to skip.
+
+## Completeness — every behavior, element, and flow has a test (at the right level)
+"Tested" means *every* observable behavior, *every* interactive element (input field,
+checkbox, radio, select, toggle, button, actionable link), and *every* user flow has at
+least one **asserting** test — not that a coverage % is hit. Completeness counts behaviors
+covered, not lines executed: 100% line coverage can still leave a button's click untested,
+and a button with one asserting unit test is "covered" at far less than 100% lines. Chase the
+behavior, not the number.
+
+Acceptance and tests are **surface-anchored**: assert the outermost surface the intent names. If the feature promised an API response, assert the API response; a database row behind it is supporting evidence, not proof.
+
+Put each test at the level that proves it cheapest and most reliably (the pyramid above):
+- **Element / field behavior** — validation, required, format, min/max, toggle on→off, select
+  options load + change fires, button enabled/disabled, handler runs → a **unit / component**
+  test. The bulk of element coverage lives here.
+- **Wiring across a few components** — form submit → store → re-render → an **integration** test.
+- **A critical end-to-end journey** — login, checkout, a destructive / data-loss path → **one
+  E2E** test. E2E is slow + flake-prone; reserve it for journeys, **never one-per-field**.
+
+An interactive element or a user flow with **zero asserting test is a defect** — surfaced as an
+unproven gap at `/rite-prove` and a NO-GO at `/rite-seal`, the same standing as an unproven
+acceptance criterion. Assert what the element *does*, not that the markup exists.
+
+## Assertion strength — a test that can't fail proves nothing
+Completeness counts tests; strength makes them mean something. A test that passes for *any*
+implementation is theatre — and it's the shape AI reaches for by default. Reject the weak forms:
+
+- **No tautological assertions.** `expect(result).toBeDefined()` / `.not.toBeNull()` /
+  `assert x is not None` pass for almost any return value. Assert the **actual value or
+  observable effect** — `expect(total).toBe(42)`, the specific error thrown, the state changed,
+  the row written, the event emitted.
+- **Don't assert the mock.** A test that stubs a dependency to return `X` then asserts `X` came
+  back tests the stub, not your code. Assert the real effect on real (or realistic) data.
+- **Cover the unhappy edges, not just the happy path.** AI is strong on "valid input → success"
+  and weak on empty / boundary / invalid-state / long-or-weird input — write those explicitly.
+- **Prove it can fail (fault injection).** For a critical or regression path, after green,
+  **break the code on purpose** (flip a comparison, drop a guard, return a constant) and confirm
+  the test goes **red**. A test never seen failing against broken code is unproven — this is
+  "see it fail first" extended past the happy path. Use the project's **mutation-testing** runner
+  to automate it where one exists; otherwise spot-check the criticals by hand.
+- **Don't mirror the implementation.** A test whose assertions restate the code under test
+  (same constant, same formula, same branch) stays green even when the logic is wrong. Assert
+  an **independently-derived** expected value — reasoned from the spec, not copied from the code.
+- **Don't grep the source.** A test that reads a source file as text and asserts it
+  `contains("foo")` proves a string exists, not that the behavior works — it passes on dead code
+  and breaks on a harmless rename. **Execute** the code and assert its effect; reserve text
+  scanning for genuinely textual artifacts (generated output, a committed manifest, a golden snapshot).
+- **Coverage says "ran"; mutation says "checked".** Line coverage proves a line executed, not
+  that a test would catch it breaking. Where the project has a mutation runner, the changed-files
+  mutation gate (`devrites-engine mutation-gate`) certifies the suite would fail on a wrong implementation; a
+  surviving mutant is a behaviour no test actually checks.
+
+## Never weaken a failing test (test integrity)
+A failing test is a signal, not an obstacle. Never delete it, skip it (`it.skip`, `xit`,
+`@pytest.mark.skip`, `t.Skip`, `#[ignore]`), mark it `xfail`, narrow the run with `.only`, or
+loosen its assertions to turn the suite green. A red test means one of two things: the code is
+wrong (fix the code) or the test is wrong (surface it as a blocking question and get the change
+agreed) — never quietly make the red go away. A test weakened to clear a gate is a **Critical**
+finding; `devrites-engine test-integrity` diffs the test files against the slice base and exits non-zero when
+one is deleted, skipped, or loses assertions.
+
+## The verification gap — green, but the test doesn't prove the change
+Test-integrity catches reaching green by *weakening* a test. This catches the quieter failure: a
+test that was never touched, is fully green, and still doesn't exercise the behavior that changed.
+A passing suite is not proof the *change* is proven — the suite could pass identically with the
+change reverted. Run this trace for each behavioral change in the diff:
+
+1. **Screen for behavioral change.** What in this diff changes an observable output, not just its
+   shape? Treat a dependency bump, a build/config edit, or a data change as behavioral too — the
+   load-bearing change often isn't the line that looks important.
+2. **Name what changed.** State the old behavior and the new one in one sentence each.
+3. **Trace to the consumer.** Find where the changed code is actually called from.
+4. **Inspect the consumer's test.** Does an *asserting*, surface-anchored test drive that consumer through the
+   **new** behavior — not merely execute the path, and not assert the old expectation still?
+5. **Confirm the gap is real.** A finding is: `<change at file:line>` has no test that would go red
+   if it regressed — cite the test that *should* cover it and show what it misses. No general
+   advice; a gap you can't point at is not a finding (the verification gate applies).
+
+A changed behavior with no test that would fail on its regression is an **unproven gap** — the same
+standing as an untested element or an unproven acceptance criterion. `devrites-engine test-integrity`
+emits an advisory when a diff changes source but touches no test file; that signal is a pointer to
+run this trace, never a verdict on its own.
+
+## Test behavior, not implementation
+- Assert on observable behavior and public interfaces, not private internals — so a
+  refactor that preserves behavior keeps tests green.
+- One behavior per test; name the test for the behavior. A failure should point straight
+  at what broke.
+- Cover the unhappy paths: empty, boundary, error, permission-denied, and concurrency
+  cases — not just the happy path.
+- **Test state, not interactions.** Assert the outcome (the value returned, the row written,
+  the event emitted), not the sequence of internal calls that produced it. A test that asserts
+  "method X was called then Y" locks in today's implementation and breaks on every refactor.
+
+## DAMP over DRY in tests
+Test code optimizes for a different reader than production code: someone staring at a failure who
+needs the whole scenario in front of them. A test should read like a spec — arrange, act, assert,
+visible in one screen. Prefer a little repetition over a clever shared helper that hides what the
+test actually exercises; **D**escriptive **A**nd **M**eaningful **P**hrases beat **D**on't **R**epeat **Y**ourself
+here. (This trades against production `coding-style.md` reuse-first on purpose — a shared fixture
+that makes the reader scroll away to understand the case has cost more than the duplication saved.)
+
+## Test doubles — reach for the real thing first
+Prefer, in order: **real > fake > stub > mock**. Use the real collaborator when it's fast and
+deterministic; a **fake** (an in-memory implementation that honors the contract) when it isn't; a
+**stub** for a canned return; a **mock** (asserting *how* it was called) only at a true boundary
+you own. Over-mocking is the failure mode: a suite stitched from mocks passes while production
+breaks, because it tested the stubs, not the code (see "Don't assert the mock" above).
+
+| Double it | Leave it real |
+|---|---|
+| The database, network, filesystem, clock, randomness | Pure functions and business logic |
+| A third-party API or paid/rate-limited service | Your own internal utilities and transforms |
+| Anything non-deterministic or slow | Validation and mapping under test |
+
+## The Beyoncé Rule — if you liked it, you should have put a test on it
+A refactor, a dependency bump, or CI is not responsible for catching your regressions — your tests
+are. If a behavior matters, it has an asserting test that goes red when the behavior breaks;
+otherwise the next person to touch the area is free to break it and every gate will stay green.
+"It worked when I ran it" is not the same as "a test holds it." This is the completeness bar above,
+stated as the rule you'll quote when a untested behavior regresses.
+
+## See it fail first
+For new behavior, watch the test fail for the *expected* reason before you make it pass.
+A green test you never saw red proves nothing.
+
+## Determinism — no flaky tests
+- A flaky test is a broken test. Isolate and fix it immediately; don't paper over it with
+  retries or `sleep`.
+- Mock/stub external services so tests are predictable and fast. Use stable selectors in
+  UI tests, not brittle positional ones.
+- No hidden shared state or order-dependence between tests.
+- **Seam the clock; never read it raw in a tested path.** Route wall-clock reads through one
+  injectable seam (an env override like `DEVRITES_NOW`, or an injected clock) so time/date-derived
+  output is pinned in tests. A raw `time.Now()` feeding output makes a golden snapshot rot at the
+  next day boundary — green today, red tomorrow, for no code change. (Live example: `resolve
+  next-qid` did exactly this until the seam landed — see ADR-0006.)
+- **No elapsed-time assertions.** `assert elapsed < 200ms` / `took` under a threshold tests the
+  CI runner's load, not your code — flaky by construction. Assert the *result*, not the duration;
+  for ordering or concurrency use a deterministic signal (a fake clock, a channel), never a `sleep`.
+
+## Use the project's tooling
+Run the project's existing test commands and framework. Don't introduce a new test runner
+to prove one change. If a project has no tests, propose the minimal setup — ask before
+adding a framework.

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

@@ -0,0 +1,99 @@
+# Optional tooling — code intelligence, docs, memory
+
+Every external tool DevRites can use is **optional**. Detect what's present, use the best fit
+for the job, and **degrade gracefully to `Read` / `Grep` / `Glob`** (always available) when
+nothing is. Never assume a tool is installed, never require installing one to run a phase, and
+never block on a missing tool — the fallback path is a first-class path, not a failure.
+
+DevRites is stack-agnostic and installs into arbitrary projects; an index or MCP server that
+exists in one repo is absent in the next. Treat the tools below as accelerators you reach for
+*when available*, not dependencies.
+
+## Code intelligence — structure, placement, callers, impact, blast-radius, trace
+
+For "where is X / what calls X / what would changing X break / how does X reach Y", reach for a
+code-intelligence index when available. The three indexes below are **recommended, not
+mandatory** — follow this order and skip any that isn't installed:
+
+1. **codebase-memory-mcp — primary.** When available, answer the structural question here
+   **first**: `search_graph`, `trace_path`, `detect_changes` (git-diff → affected symbols +
+   blast radius), `get_architecture`, `get_code_snippet`, `query_graph`.
+2. **Cross-verify with codegraph *and* graphify (both, when present).** Re-ask the same
+   structural question of `codegraph` (`.codegraph/`, `codegraph_*`) **and** `graphify`
+   (`graphify-out/`), and confirm they agree with the codebase-memory-mcp answer — especially
+   for load-bearing claims (blast radius, every caller of a thing you're about to change,
+   "nothing else uses this"). A disagreement between indexes is a signal, not noise: trust a
+   fresh read of the **live code** over any index, and investigate the gap before relying on it.
+3. **Standard methods — the always-available fallback.** When none of the three indexes is
+   present — or to pin an exact reference an index is unsure of — use **LSP** (Claude Code Code
+   Intelligence: go-to-definition, find-references, hover / signature, diagnostics, document &
+   workspace symbols) plus **`Read` / `Grep` / `Glob`**, reading comprehensively rather than
+   stopping at the first match (see `core.md` rule 1).
+
+Use whatever subset is installed: codebase-memory-mcp alone is fine; codebase-memory-mcp plus
+one of the others still cross-verifies; none present → standard methods. The fallback path is a
+first-class path — never block a phase on a missing index.
+
+### Keeping the indexes fresh
+
+An index only helps if it matches the live code; after edits, a stale graph manufactures the
+very index-disagreement step 2 treats as a signal. DevRites keeps the three mechanical indexes
+current automatically — the [`devrites-refresh-indexes`](../../../devrites-refresh-indexes/SKILL.md)
+Stop hook incrementally reindexes whichever of codebase-memory-mcp, codegraph, and graphify
+track the repo, at end of turn, in a detached process. It self-guards on changes, no-ops when no
+index is present, and is disabled by `DEVRITES_REFRESH_INDEXES=off`. Force a synchronous refresh
+— or re-run graphify's semantic pass after **doc** changes (`/graphify --update`) — via that
+skill. Still trust a fresh read of the live code over any index when they disagree.
+
+## Up-to-date library / framework docs — context7
+
+When implementing against, choosing, or verifying an **external** library/framework whose
+current API or version behaviour matters, use **context7 if available**: `resolve-library-id`
+(library name + your question) → `query-docs` (the resolved id + the question).
+
+context7 pairs with [`devrites-source-driven`](../../../devrites-source-driven/SKILL.md), it
+doesn't replace it: the project's **installed / pinned source still wins** for the version the
+project actually runs. Reach for context7 when the local source/docs are missing, or when you
+need the *current upstream* behaviour the installed copy may predate. Record the fact + its
+source in `decisions.md` / `evidence.md` the same way — a context7 lookup is a cited source,
+not a memory.
+
+## Up-to-date web facts — web search
+
+When a **material decision** turns on a fact neither the codebase nor the installed docs can
+answer — a common UX pattern, a standard/spec, a prevailing best practice, how comparable
+products solve it, a pricing/compatibility fact — **search the web if a search tool is
+available**, and fold the finding into the option you present the human (below). Order of
+preference: **brave MCP is the primary** (`mcp__brave-search__brave_web_search`, or
+`brave_local_search` for place/region queries); **fall back to the harness's native web search
+only when brave MCP is unavailable** — Claude Code `WebSearch` / `WebFetch`, Codex `web_search`
+(`--search` / `web_search = "live"` for fresh pages; its default `"cached"` mode serves an
+OpenAI-indexed snapshot); else skip and log the open question. A web fact is a **cited source**,
+not a memory — record the claim + its URL in `decisions.md` (or the option's rationale) exactly as
+a context7 lookup is recorded.
+
+Graceful degradation is the rule: no search tool present is a first-class path, never a
+blocker. Search to *inform the human's decision*, not to replace it — the finding sharpens the
+recommended option and its trade-off; the human still picks.
+
+**Re-fetching a doc URL is cheap.** On Claude Code a `WebFetch` is transparently cached per project
+and, on reuse, revalidated against the origin — the cached reading is replayed **only** on an HTTP
+304 (unchanged), so a citation stays as sound as a fresh fetch without the round trip. Fetch freely;
+don't skip a verification to save a request. Mechanism: the `devrites-source-cache` hooks
+(`DEVRITES_SOURCE_CACHE=off` to disable); it pairs with
+[`devrites-source-driven`](../../../devrites-source-driven/SKILL.md). (Claude-only — Codex has no
+`WebFetch` tool to intercept, and its `web_search` already serves from a cached index, so the same
+caching is built in there.)
+
+## Architecture & decision memory — codebase-memory-mcp
+
+Where a fast codebase map or a durable decision record helps, and codebase-memory-mcp is
+available: `get_architecture` for an overview (languages, packages, routes, hotspots, clusters)
+during `/rite-spec`, `/rite-define`, or `/rite-zoom-out`; `manage_adr` for an ADR-style record
+at `/rite-define` / `/rite-seal`. This complements the workspace `decisions.md`; it never
+replaces it — the workspace files remain the canonical source of truth.
+
+## Output hygiene
+
+Per [`prose-style.md`](prose-style.md): don't name these tools to the user. Say what you
+learned ("the change touches three call sites"), not which tool found it.