devrites 2.6.1 → 3.0.0

package/pack/.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/.claude/{rules → skills/devrites-lib/reference/standards}/tooling.md

@@ -38,7 +38,7 @@ first-class path — never block a phase on a missing index.
 
 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`](../skills/devrites-refresh-indexes/SKILL.md)
+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
@@ -51,13 +51,40 @@ When implementing against, choosing, or verifying an **external** library/framew
 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`](../skills/devrites-source-driven/SKILL.md), it
+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

package/pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md

@@ -0,0 +1,110 @@
+# Workspace artifact schema
+
+DevRites stores feature truth in `.devrites/work/<slug>/`. The older
+`.devrites/features/<slug>/` path remains readable during migration; do not delete
+existing workspaces or aliases. `feature.md` and `index.md` may stand in for the
+workspace map; `proof.md` may stand in for `evidence.md`.
+
+## Required by phase
+
+| Phase | Required artifacts |
+| --- | --- |
+| spec | `README.md`/`index.md`/`feature.md`, `brief.md`, `spec.md`, `state.md`, `decisions.md`, `assumptions.md`, `questions.md` |
+| define/plan/vet/build | spec artifacts plus `architecture.md`, `plan.md`, `tasks.md`, `traceability.md` |
+| prove/polish/review/seal/ship | plan artifacts plus `evidence.md`/`proof.md`, `touched-files.md` |
+| conditional | `flows.md` when diagrams clarify; `design-brief.md` and `browser-evidence.md` for UI; `drift.md` for drift; `handoff.md` only when requested; `references.md` + `references/` when references exist |
+
+## What each file owns
+
+| File | Job | Budget |
+| --- | --- | --- |
+| `README.md` / `index.md` / `feature.md` | compact workspace map: phase, status, next action, artifact map, read-next table, blocking gates, last updated | 120 lines |
+| `brief.md` | user request, objective, non-goals, success definition | 80 lines |
+| `spec.md` | product WHAT/WHY, requirements, acceptance criteria, edge cases, measurable success, scope boundaries | 260 lines |
+| `architecture.md` | owning layer, integration points, data/API/events, dependencies, risks, affected boundaries | 180 lines |
+| `flows.md` | useful Mermaid sequence/state/data/lifecycle diagrams with why-it-matters text and related IDs | 160 lines |
+| `decisions.md` | ADR-style `DEC-###` log: status, context, options, decision, consequences, related IDs | 200 lines |
+| `assumptions.md` | assumptions with confidence, owner, validation status | 160 lines |
+| `questions.md` | `Q-###` open/resolved questions, gate, answer, impact | 180 lines |
+| `plan.md` | technical approach, slice strategy, validation strategy, rollback | 220 lines |
+| `tasks.md` | `SLICE-###` vertical slices with AC IDs, likely files, tests/proof, mode/gate, dependencies, done condition | 280 lines |
+| `traceability.md` | matrix: AC/REQ ID, slice IDs, test/proof, evidence ID, touched files, status | 220 lines |
+| `state.md` | compact cursor table/key-values; no narrative log | 120 lines |
+| `evidence.md` / `proof.md` | `EVID-###` command/action, result, timestamp if available, related AC/slice IDs, limitation | 280 lines |
+| `browser-evidence.md` | UI route/viewports/screenshots/console/network/interactions and Visual Verdict | 220 lines |
+| `drift.md` | `DRIFT-###` spec/plan drift and resolution | 160 lines |
+| `touched-files.md` | implementation files, slice ownership, reason, and a concern-ordered `## Review trail` of `path:line` stops for human review | 180 lines |
+| `design-brief.md` | UI design direction, states, interaction model | 160 lines |
+| `handoff.md` | cold-resume guide: current objective, last completed slice, next action, blockers, read-next links | 120 lines |
+
+Files can exceed the budget only with `Budget override: <reason>`.
+
+## Canonical slice grammar
+
+Every producer of `tasks.md` uses this field set. `Dependencies` is slice
+ordering; package and service requirements belong in `External dependencies`.
+
+<!-- canonical-slice:start -->
+```markdown
+## SLICE-001 <observable capability>
+Goal: <single observable capability>
+Satisfies: AC-001[, AC-002]
+Acceptance criteria: <binary criteria this slice closes>
+Complexity: <1..5> — <reason>
+Forge: <no | yes — reason>
+Mode: <AFK | HITL>
+Gate: <advisory | validating | blocking | escalating>
+SLA: <15m | 4h | 24h | none>
+Checkpoint: <question | none>
+Dependencies: <SLICE-### list | none>
+depends_on: [<SLICE-### IDs>]
+Consumes / Produces: <interfaces read and exposed>
+Known-Gotchas: <ordering hazards and framework footguns | none>
+Prior-slice learnings: <constraints learned earlier | none>
+Files likely touched: <real paths>
+Tests/proof: <tests to write/run and exact validation commands>
+Browser proof required: <yes | no>
+Frontend craft required: <yes | no>
+Design brief states: <UI states/interaction | none>
+Visual acceptance: <state × viewport × input target | none>
+Fullstack (FE+BE): <yes | no>
+External dependencies: <libraries/services | none>
+Existing to reuse / extend: <components/utilities/patterns | none>
+Rollback notes: <reversal path>
+Evidence required: <evidence /rite-prove must capture>
+Edge/Prohibition coverage: <EDGE/PROH IDs | none>
+Done condition: <checkable, exhaustive completion criterion>
+```
+<!-- canonical-slice:end -->
+
+`depends_on` is the machine-readable mirror of `Dependencies`; keep the sets
+identical and cycle-free. `Gate`, `SLA`, and `Checkpoint` are required for HITL
+slices; use `none` when they do not apply. Complexity above 3 triggers reslicing
+unless the stated reason makes the boundary irreducible. `Forge: yes` is reserved
+for a high-complexity architecture fork with multiple viable approaches.
+
+## Read next by phase
+
+| Phase | Read |
+| --- | --- |
+| spec | `README.md`, `brief.md`, `spec.md`, `references.md`, `questions.md` |
+| define | `README.md`, `state.md`, `spec.md`, `architecture.md`, `decisions.md`, `assumptions.md` |
+| vet | `README.md`, `traceability.md`, `plan.md`, `tasks.md`, `architecture.md`, `decisions.md` |
+| build | `state.md`, `tasks.md`, `plan.md`, `architecture.md`, `traceability.md`, `questions.md` |
+| prove | `traceability.md`, `tasks.md`, `evidence.md`, `browser-evidence.md`, `touched-files.md` |
+| review/seal | `README.md`, `traceability.md`, `spec.md`, `evidence.md`, `decisions.md`, `drift.md`, `touched-files.md` |
+| handoff | `README.md`, `state.md`, `handoff.md`, then the linked source artifacts |
+
+## Do not duplicate
+
+- Do not make `spec.md` carry deep architecture; link to `architecture.md`/`flows.md`.
+- Do not copy acceptance criteria into `plan.md`; reference `AC-###`.
+- Do not copy full proof into `handoff.md`; link to `evidence.md`.
+- Do not make `state.md` an append-only log; keep only the current cursor.
+- Do not create optional files before their phase; absence is meaningful.
+
+## ID contract
+
+Use stable IDs: `REQ-001`, `AC-001`, `SLICE-001`, `DEC-001`, `Q-001`,
+`DRIFT-001`, `EVID-001`. Old `AC1` and `Slice 1` forms are legacy and should
+not be generated for new workspaces.

package/pack/.claude/skills/devrites-prose-craft/SKILL.md

@@ -1,20 +1,13 @@
 ---
 name: devrites-prose-craft
-description: Write the artifacts and chat replies a senior engineer would — direct, specific, human voice, with the default LLM tells stripped. Use when a DevRites phase writes prose (spec.md, plan.md, decisions.md, review.md, seal.md, commit/PR bodies) or a user-facing reply, and as the catch pass in /rite-polish. Not for code comments and naming (the build-time anti-slop charter covers those) or UI craft (use devrites-frontend-craft).
+description: Humanize prose without losing technical content. Use when asked to remove AI-writing tells, match a writing sample or project voice, edit artifacts/replies/commit or PR prose, or run `/rite-polish`'s prose pass. Not for code comments or UI craft.
 user-invocable: false
 ---
 
 # devrites-prose-craft — prose that reads human
 
-Strip the default LLM voice from everything DevRites writes. The reader is a teammate, not a
-search engine; the artifact is documentation a person will rely on, not content to fill a box.
-This is the prose sibling of [`devrites-frontend-craft`](../devrites-frontend-craft/SKILL.md):
-craft applied to words instead of UI.
-
-The always-available core is [`.claude/rules/prose-style.md`](../../rules/prose-style.md) — the
-two registers and the cut-list. This skill carries the depth: the full banned-phrase and
-structure references, and the before/after examples. Read the rule first; load a reference
-when you need the full list.
+Write for a teammate who will rely on the result. Remove model-shaped filler without sanding
+off the author's voice or weakening technical content.
 
 ## When this fires
 - A text-generating phase composes an artifact: `/rite-spec` (overview, rationale),
@@ -37,69 +30,40 @@ adjective standing in for evidence, a false/unsourced claim) → **P1** obvious
 parallelism, filler openers, em-dash tics) → **P2** polish (rhythm, word choice). A quick pass
 fixes P0 + P1 and stops; a full pass takes P2 too.
 
-## The two registers (calibrated — this is the adaptation that matters)
-DevRites writes in two voices; apply the cut-list to both, but the precision rules differ.
-
-- **Prose** — replies and narrative artifact sections. Optimize for a human voice: direct,
-  specific, active, varied rhythm.
-- **Technical** — acceptance criteria, task slices, API/data contracts, schema, config, test
-  names. Optimize for **precision**. Numbered criteria, complete enumerations, exact
-  identifiers, and domain terms are correct here — **keep them**. Never humanize a spec into
-  vagueness.
-
-The shared rule: cut what carries no information; keep what the reader needs. In prose that
-kills filler; in technical writing it keeps the precise list.
-
-## The cut-list (summary — full lists in references)
-1. **Throat-clearing openers.** "Here's the thing", "It's worth noting", "Let me be clear".
-   State the point. → [`reference/banned-phrases.md`](reference/banned-phrases.md)
-2. **False binary contrast.** "It's not X, it's Y", "not just X but Y", "the question isn't X".
-   State Y directly; drop the negation. → [`reference/structures.md`](reference/structures.md)
-3. **Fake profundity & vague declaratives.** "Let that sink in", "the implications are
-   significant". Show the specific thing or cut the sentence.
-4. **Marketing adjectives on engineering work.** "robust", "scalable", "seamless",
-   "production-ready", "comprehensive". Say what it does and what proves it.
-5. **Hedging stacks & meta-narration.** "it's important to note that, generally"; "in this
-   section we'll…". Make the claim or delete the announcement.
-6. **False agency.** "the data tells us", "the decision emerges". Name who acts.
-7. **Em-dash tics.** A tool, not a tic — at most one per paragraph; multiple is the tell.
-8. **Active voice, varied rhythm.** Named actor at the front; mix sentence lengths; don't
-   stack staccato fragments for drama.
-
-## Strong verbs (technical register)
-Weak verb + adverb → one precise verb. The swap kills filler and sharpens the claim:
-
-| Weak | Strong |
-|---|---|
-| "helps with" / "works to" | powers · enforces · gates · blocks |
-| "makes use of" / "utilizes" | uses |
-| "is responsible for" | owns · writes · renders |
-| "in order to" | to |
-| "has the ability to" | can |
-| "provides support for" | supports |
-| "a number of" / "a variety of" | the actual count |
-
-**Signal, not verdict.** The cut-list flags *signals* of LLM prose, not proof — a precise technical
-list, an exact identifier, or a numbered acceptance criterion can trip a "tell" pattern and still be
-correct. When a flagged construct carries real information (a genuine three-item list, a real
-contrast the spec needs), keep it. Over-correcting precise spec structure into smooth prose is its
-own slop (this is the same calibration as the two registers above).
-
-## Quick check before delivering prose
-- Filler opener or recap of what you just said? Cut it.
-- "Not X, it's Y" anywhere? Rewrite to state Y.
-- A claim of significance with no specific named? Replace with the specific, or cut.
-- A marketing adjective standing in for evidence? Replace with what proves it.
-- Passive voice hiding the actor? Front the actor.
-- More than one em-dash in a paragraph? Reduce to one.
-- Vague attribution ("studies show", "best practice says") with no source named? Cite or cut.
-- Topic-swap test: would the sentence read true for any other feature? Then name the specific.
-- **Technical register intact?** Acceptance criteria still numbered, identifiers exact, real
-  enumerations complete, one name per entity — confirm the calibration didn't strip precision.
-
-Examples (including a slop `spec.md` vs a clean one): [`reference/examples.md`](reference/examples.md).
-
-## Default vs departure
-Match the project's existing writing where it has a voice (its README, ADRs, code comments).
-A house style — even a plain one — beats a "better" foreign voice. Only depart when the
-existing prose is itself slop. When unsure, write flatter and more direct.
+## Process
+
+1. **Calibrate.** Choose rewrite or detect-only mode, split prose from technical sections, and
+   set the voice baseline: an explicit user sample first, then neighboring project prose, then
+   the source text itself. Fall back to flat, direct prose. Done when every section has a
+   register and one voice baseline.
+2. **Protect.** Apply the preservation contract in
+   [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md) before changing words.
+   Scan for clusters of tells; one isolated marker is not a verdict. Done when every claim,
+   constraint, identifier, example, quotation, and deliberate uncertainty is accounted for.
+3. **Rewrite.** Remove P0/P1 tells and P2 when the caller asked for a full pass. Match the
+   baseline's vocabulary and cadence without inventing facts, opinions, or quirks. Done when the
+   same reader can make the same decisions from the rewrite as from the source.
+4. **Audit.** Compare source and result, read the prose aloud, and run the relevant references
+   below. Done when the preservation contract passes, the technical register remains exact,
+   and no in-scope tell remains.
+
+## References
+
+- Always read [`prose-style.md`](../devrites-lib/reference/standards/prose-style.md) for the two
+  registers, preservation contract, and core checks.
+- Load [`reference/banned-phrases.md`](reference/banned-phrases.md) when word choice or tone is
+  the problem.
+- Load [`reference/structures.md`](reference/structures.md) when sentence shape, rhythm, or
+  formatting is the problem.
+- Load [`reference/examples.md`](reference/examples.md) when the target artifact's shape is
+  unclear.
+
+## Boundaries
+
+This skill edits language, not facts. When style and fidelity conflict, fidelity wins.
+
+## Output
+
+- **Rewrite:** replace the target prose; add no editing commentary unless the caller's contract
+  asks for it.
+- **Detect-only:** return ordered P0/P1/P2 findings with the exact phrase and a concrete fix.

package/pack/.claude/skills/devrites-prose-craft/reference/examples.md

@@ -21,9 +21,9 @@ feature is, who it's for, and the scope boundary.
 ## 2. Acceptance criteria (technical register — precision stays)
 
 **Keep this as-is — do NOT "humanize" it:**
-> - [AC1] A `GET /reports/:id/export?format=csv` returns `200` with `Content-Type: text/csv`.
-> - [AC2] Rows stream; peak memory stays under 50 MB for a 1M-row export.
-> - [AC3] An unknown `format` returns `400` with `{ "error": "unsupported format" }`.
+> - AC-001: A `GET /reports/:id/export?format=csv` returns `200` with `Content-Type: text/csv`.
+> - AC-002: Rows stream; peak memory stays under 50 MB for a 1M-row export.
+> - AC-003: An unknown `format` returns `400` with `{ "error": "unsupported format" }`.
 
 Three items, exact identifiers, exact status codes. This is the technical register working
 correctly. The skill leaves it alone.
@@ -50,7 +50,7 @@ Named the decision, the reason (with evidence), and the trade-off. That's what a
 
 **After:**
 > Critical — `export.ts:42` catches every error and returns `500 "something went wrong"`. A
-> bad `format` param should be a `400` with the specific message (AC3). Catch the parse error
+> bad `format` param should be a `400` with the specific message (AC-003). Catch the parse error
 > narrowly; let the rest propagate.
 
 Severity label, `file:line`, the specific problem, the fix. No hedging, no "fundamentally".
@@ -79,7 +79,21 @@ Dropped the pleasantries and the "not just X" inflation. Led with what's done an
 
 Followed `git-workflow.md`: the *why*, wrapped, in plain language.
 
-## The pattern across all six
+## 7. Fidelity when evidence is incomplete
+
+**Before (slop, but informative):**
+> It is important to note that the importer retries twice after a `429`. The available evidence
+> does not clearly indicate whether a third attempt is dropped or queued. In either case, the
+> alert text is `Import delayed`.
+
+**After:**
+> The importer retries twice after a `429`. We do not have a production trace showing whether a
+> third attempt is dropped or queued. The alert text remains `Import delayed`.
+
+Cut the opener and vague phrasing. Kept the retry count, status code, evidence gap, two possible
+outcomes, and exact alert text. A smoother sentence that picked one outcome would be fabrication.
+
+## The pattern across all seven
 
 1. Lead with the concrete thing (what it is, what's done, what's wrong).
 2. Replace every "robust/seamless/leverage" flourish with the specific behavior + its proof.

package/pack/.claude/skills/devrites-refresh-indexes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devrites-refresh-indexes
-description: Keep the optional code-intelligence indexes — codebase-memory-mcp, codegraph, graphify — current after code changes so the next structural lookup reads live code. Use when a structural lookup disagrees with the live code, after a large change before a structural query, or the user says "reindex". The Stop hook does this automatically; this skill is the manual force + the reference for it. Not for agentmemory (a separate, judgment-based store).
+description: Refresh stale optional indexes. Use when structural lookup disagrees with live code or rite-doctor requests a synchronous reindex.
 user-invocable: false
 ---
 
@@ -23,7 +23,7 @@ anything, never blocks. Same incremental shape for all three; no LLM needed for
 
 ## Automatic (already wired — no action needed)
 
-The `Stop` hook `devrites-refresh-indexes.sh` runs at end of turn. It self-guards: exits
+The `Stop` hook `devrites-engine hook refresh-indexes` runs at end of turn. It self-guards: exits
 instantly unless an index tracks the repo, exits instantly if no source file changed since the
 last refresh, else stamps + locks and spawns a **detached** worker so the turn never blocks.
 ON by default; disable with `DEVRITES_REFRESH_INDEXES=off`.
@@ -33,10 +33,7 @@ ON by default; disable with `DEVRITES_REFRESH_INDEXES=off`.
 Force a synchronous refresh now and print the report — resolve the hook across install layouts:
 
 ```bash
-H=".claude/hooks/devrites-refresh-indexes.sh"
-[ -f "$H" ] || H="${CLAUDE_PLUGIN_ROOT:-}/pack/.claude/hooks/devrites-refresh-indexes.sh"
-[ -f "$H" ] || H="pack/.claude/hooks/devrites-refresh-indexes.sh"
-bash "$H" --force .
+devrites-engine hook refresh-indexes --force .
 ```
 
 Then the one case the hook can't cover:

package/pack/.claude/skills/devrites-source-driven/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devrites-source-driven
-description: Verify uncertain framework or library behavior against official docs or installed source before relying on it, then record the source in `evidence.md` / `decisions.md`. Use when the user says "check the docs", "verify this assumption", or build hits an unfamiliar framework call. Not for project-internal code or trivial stdlib calls.
+description: Verify uncertain framework/library behavior against official docs or installed source before relying on it. Use when the user says "check the docs", "verify this assumption", or hits an unfamiliar API. Not for internal code.
 user-invocable: false
 ---
 
@@ -28,9 +28,25 @@ matters and isn't certain, check the source of truth.
 4. **Record it** in `decisions.md` (or `evidence.md`): the fact, the version, and the
    source (path or URL). Future phases trust the record instead of re-checking.
 
+## Delegate reading legwork bigger than one fact
+When the question is an *area*, not a fact — surveying a library's API surface, an unfamiliar
+subsystem's docs, a migration guide — dispatch a **background agent** instead of reading inline:
+it investigates against the same source-of-truth order above, cites each claim (path or URL +
+version), and writes one note to the active workspace's `references/` directory, linked from
+`references.md`. You keep working while it reads; later phases trust the cited note. The inline
+flow above stays the path for confirming a single fact.
+
 ## Rules
 - Prefer the **installed** source over remembered docs — it can't be out of date.
 - Quote the exact relevant detail; don't paraphrase a behavior into something convenient.
 - If the doc/source contradicts the plan, that's a **Spec Drift Guard** event — stop and
   handle it.
 - Don't rabbit-hole: confirm the one fact you need, record it, return.
+
+## Re-fetching is cheap (and still fresh)
+Fetching the same doc URL twice costs almost nothing: on Claude Code a WebFetch is transparently
+cached per project and, on reuse, revalidated against the origin — the cached reading is replayed **only**
+when the server confirms the page is unchanged (HTTP 304). A 304 is a fresh verification, not a
+memory read, so citing a revalidated page is as sound as re-fetching it. Fetch freely; don't
+skip a check to save a round trip. (Mechanism: the `devrites-source-cache` hooks; off via
+`DEVRITES_SOURCE_CACHE=off`. Web-search + cache policy lives in [`tooling.md`](../devrites-lib/reference/standards/tooling.md).)