devrites 3.0.5 → 3.0.6

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

@@ -1,25 +1,25 @@
 # Testing
 
-Tests are evidence. They exist to prove behavior and to catch regressions — not to hit a
+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.
+- **Some** integration tests for how components fit together.
 - **Few** end-to-end tests for critical user journeys (they're slow and the most
-  flake-prone — reserve them for what matters).
+  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
+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
+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)
+## 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
+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.
@@ -27,97 +27,97 @@ 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
+- **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
+- **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
+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
+## 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:
+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,
+  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.
+  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
+  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.
+  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
+  `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.
+  surviving mutant is a behaviour no test 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**
+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
+## 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
+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
+   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.
+3. **Trace to the consumer.** Find where the changed code is 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?
+   **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
+   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
+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
+- 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.
+  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,
+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
+test 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
+## 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
@@ -130,8 +130,8 @@ breaks, because it tested the stubs, not the code (see "Don't assert the mock" a
 | 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
+## 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,
@@ -141,7 +141,7 @@ stated as the rule you'll quote when a untested behavior regresses.
 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
+## 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
@@ -150,13 +150,13 @@ A green test you never saw red proves nothing.
 - **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.)
+  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;
+  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
+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

@@ -1,51 +1,51 @@
-# Optional tooling — code intelligence, docs, memory
+# 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.
+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
+## 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:
+mandatory**: follow this order and skip any that isn't installed:
 
-1. **codebase-memory-mcp — primary.** When available, answer the structural question here
+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
+   (`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
+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.
+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)
+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.
+index is present, and is disabled by `DEVRITES_REFRESH_INDEXES=off`. Use that skill to force a
+synchronous refresh or rerun graphify's semantic pass after **doc** changes
+(`/graphify --update`). Still trust a fresh read of the live code over any index when they disagree.
 
-## Up-to-date library / framework docs — context7
+## 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`
@@ -53,45 +53,45 @@ current API or version behaviour matters, use **context7 if available**: `resolv
 
 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
+project 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,
+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
+## 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
+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`
+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
+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
+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
+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
+[`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
+## 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.
+replaces it: the workspace files remain the canonical source of truth.
 
 ## Output hygiene
 

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

@@ -4,7 +4,7 @@ description: Humanize prose without losing technical content. Use when asked to
 user-invocable: false
 ---
 
-# devrites-prose-craft — prose that reads human
+# devrites-prose-craft: prose that reads human
 
 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.
@@ -14,15 +14,15 @@ off the author's voice or weakening technical content.
   `/rite-define` / `/rite-plan` (plan narrative), `/rite-temper` / `/rite-vet` (review prose),
   `/rite-review` / `/rite-seal` (findings + verdict prose), `/rite-ship` (commit/PR body),
   `devrites-doubt` / `rite-handoff` (notes).
-- Any phase composes a substantive **user-facing reply** (not the deterministic progress
-  footers — those are script-rendered and exact by design).
+- Any phase composes a substantive **user-facing reply**. Deterministic progress footers are
+  script-rendered and exact by design.
 - `/rite-polish` Phase 1 as the **catch** pass on prose that slipped through at write time.
 
 ## Two modes
 - **Rewrite (default).** When DevRites writes the artifact/reply or polishes it, fix the prose
   in place.
-- **Detect-only.** When auditing prose you shouldn't silently change — a user's existing
-  `spec.md` at `/rite-adopt`, text under `/rite-review` — list the tells with quotes and leave
+- **Detect-only.** When auditing prose you shouldn't silently change, such as a user's existing
+  `spec.md` at `/rite-adopt` or text under `/rite-review`, list the tells with quotes and leave
   the text untouched. Mirrors `devrites-audit`'s read-only stance.
 
 Order findings by severity: **P0** credibility-killers (vague attribution, a marketing

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

@@ -4,10 +4,10 @@ description: Refresh stale optional indexes. Use when structural lookup disagree
 user-invocable: false
 ---
 
-# devrites-refresh-indexes — keep the code-intelligence indexes fresh
+# devrites-refresh-indexes: keep the code-intelligence indexes fresh
 
 `tooling.md` says to cross-verify structural claims across codebase-memory-mcp, codegraph, and
-graphify, and that **a disagreement between indexes is a signal** — a fresh read of live code
+graphify, and that **a disagreement between indexes is a signal**: a fresh read of live code
 beats any index. A *stale* index manufactures exactly that disagreement. This keeps the three
 mechanical indexes current after edits so the next lookup is trustworthy.
 
@@ -21,7 +21,7 @@ anything, never blocks. Same incremental shape for all three; no LLM needed for
 | **codegraph** | `.codegraph/` exists + `codegraph` on PATH | `codegraph sync` |
 | **graphify** | `graphify-out/` exists + `graphify` on PATH | `graphify update .` |
 
-## Automatic (already wired — no action needed)
+## Automatic (already wired: no action needed)
 
 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
@@ -30,7 +30,7 @@ ON by default; disable with `DEVRITES_REFRESH_INDEXES=off`.
 
 ## Manual / thorough refresh (this skill)
 
-Force a synchronous refresh now and print the report — resolve the hook across install layouts:
+Force a synchronous refresh now and print the report: resolve the hook across install layouts:
 
 ```bash
 devrites-engine hook refresh-indexes --force .
@@ -46,6 +46,6 @@ Then the one case the hook can't cover:
 - codegraph and codebase-memory-mcp each have their own background watcher; the explicit
   reindex is the belt-and-suspenders fallback for when a watcher isn't running. graphify has no
   default watcher, so this is its primary freshness path.
-- The index lags writes by ~1s after a refresh — don't re-query in the same instant you edit.
-- Output hygiene (`prose-style.md`): don't name these tools to the user — say what changed
+- The index lags writes by ~1s after a refresh: don't re-query in the same instant you edit.
+- Output hygiene (`prose-style.md`): don't name these tools to the user: say what changed
   ("re-indexed the edited files"), not which tool did it.

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

@@ -4,7 +4,7 @@ description: Verify uncertain framework/library behavior against official docs o
 user-invocable: false
 ---
 
-# devrites-source-driven — verify, don't guess
+# devrites-source-driven: verify, don't guess
 
 A confident wrong assumption about a library is a bug waiting to ship. When behavior
 matters and isn't certain, check the source of truth.
@@ -17,35 +17,35 @@ matters and isn't certain, check the source of truth.
 - An error message points at framework behavior you don't fully understand.
 
 ## How
-1. **Find the version** the project actually uses (lockfile, manifest) — behavior is
+1. **Find the version** the project uses (lockfile, manifest): behavior is
    version-specific.
 2. **Consult the source of truth**, in order: the installed package's own source/types
    in `node_modules`/gem/site-packages; context7 if available (`resolve-library-id` →
    `query-docs`) for current upstream docs; official docs for *that version*; the project's
    existing usage of the same API.
-3. **Confirm the specific fact** — the signature, the default, the edge behavior — not a
+3. **Confirm the specific fact:** the signature, the default, the edge behavior, not a
    general impression.
 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:
+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.
+- 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
+- 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**
+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

package/pack/generated/claude/skills/devrites-ux-shape/SKILL.md

@@ -4,10 +4,10 @@ description: Plan UX/UI before code: design direction, design brief, visual dire
 user-invocable: false
 ---
 
-# devrites-ux-shape — plan the UX/UI before code
+# devrites-ux-shape: plan the UX/UI before code
 
 Decide what the UI *is* and how it should look and behave **before** code, and write it to
-the feature's `design-brief.md` — the contract the build (`devrites-frontend-craft`),
+the feature's `design-brief.md`: the contract the build (`devrites-frontend-craft`),
 polish, and seal all check against. This is "shape before code" raised to a **feature-level
 artifact**: produced once at spec time, refined per slice. It is **woven into the
 lifecycle** (`/rite-spec` calls it when UI is detected; `/rite-build` refines it), not a
@@ -18,59 +18,59 @@ separate phase the user runs.
   (`../rite-build/reference/frontend-trigger.md`). Output: `design-brief.md` + a
   confirmation pause.
 - `/rite-build` / `devrites-frontend-craft` read the brief as the **build target** and
-  refine it for the slice's surface — they don't re-derive it.
+  refine it for the slice's surface. They don't re-derive it.
 - Skip entirely for backend / data / CLI / infra-only features.
 
-## 1. Foundation — discover, don't impose
+## 1. Foundation: discover, don't impose
 Reuse what's there first. Read the design system + register and any references the spec
 gathered:
 - Design system + register (tokens, components, type, spacing, neighbors; brand-vs-product)
   → `../devrites-frontend-craft/reference/design-references.md`.
-- `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` if present — anchors that reduce questions.
+- `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` if present: anchors that reduce questions.
   `DESIGN.md` is the project's **rolled-up design memory** (tokens, calibration baseline,
   proven component behaviors) earlier features sealed via `../rite-ship/reference/design-memory.md`;
-  treat it as the inherited system — read it before re-discovering, depart only on signal.
-- `references.md` + `references/` — the screenshots / Figma / video / links the human
+  treat it as the inherited system: read it before re-discovering, depart only on signal.
+- `references.md` + `references/`: the screenshots / Figma / video / links the human
   supplied. Honor each recorded role: **target** = fidelity contract, **constraint** =
   required rule, **inspiration** = extract only the cited principle.
 
-## 2. Discovery — one round, assert-then-confirm
-Understand the feature deeply enough to make excellent design calls — **no code, no
+## 2. Discovery: one round, assert-then-confirm
+Understand the feature deeply enough to make excellent design calls: **no code, no
 markup**. Use the `devrites-interview` cadence: 2-3 questions per round, best-guess
 attached, stop when answers converge. One round is the default; add a second only for
 material gaps. When `PRODUCT.md` + the spec already pin an answer, **assert it and ask to
-confirm** ("reads as Restrained — confirm?"), don't offer a four-option menu. Cover:
-- **Purpose & user** — who, in what state of mind (rushed / exploring / anxious / focused).
-- **Content & data** — realistic ranges (0 / typical / many), dynamic content, real
+confirm** ("reads as Restrained: confirm?"), don't offer a four-option menu. Cover:
+- **Purpose & user:** who, in what state of mind (rushed / exploring / anxious / focused).
+- **Content & data:** realistic ranges (0 / typical / many), dynamic content, real
   media/assets the surface needs.
-- **Preserve + anti-goals** — identity, IA, behavior, content voice, SEO/analytics hooks,
+- **Preserve + anti-goals:** identity, IA, behavior, content voice, SEO/analytics hooks,
   existing accessibility wins, or assets that must survive; what this must NOT become;
   the biggest risk of getting it wrong.
 
-## 3. Design direction — the direction set (commit, don't hedge)
+## 3. Design direction: the direction set (commit, don't hedge)
 One deliberate visual decision on five fronts, each anchored in an existing reference so
 the call is checkable, not taste:
-- **Scene sentence** — who / where / ambient light / mood, per
+- **Scene sentence:** who / where / ambient light / mood, per
   `../devrites-frontend-craft/reference/design-references.md`. Forces dark-vs-light and
   tone from the scene, not the category.
-- **Color strategy** — Restrained / Committed / Multi-role / Saturated, per the
+- **Color strategy:** Restrained / Committed / Multi-role / Saturated, per the
   color-commitment table in `../devrites-frontend-craft/reference/quality-standards.md`.
   Pick from the scene; register doesn't decide it.
-- **Calibration** — density (Airy / Balanced / Dense) and motion (Minimal / Standard /
+- **Calibration:** density (Airy / Balanced / Dense) and motion (Minimal / Standard /
   Expressive), per the calibration table in the same quality-standards file. Set both from
   the scene so the build targets a calibration, not a guess (a 2am SRE → Dense + Minimal; a
   launch hero → Airy + Expressive).
-- **Named anchor references** — 2-3 *specific* products / brands / objects to steer toward
+- **Named anchor references:** 2-3 *specific* products / brands / objects to steer toward
   (not adjectives like "modern" or "clean"), plus the saved `references/` files.
-- **Visual thesis** — the focal point and hierarchy in one sentence, plus one memorable
+- **Visual thesis:** the focal point and hierarchy in one sentence, plus one memorable
   move (or `none — system continuity`) and the obvious-but-wrong direction rejected. This
   creates intentional distinction without forcing novelty into product UI.
 
 Respect the existing identity (default, ~90%); depart only on an explicit signal.
 
-## 4. Scope — task-scoped, never persisted
+## 4. Scope: task-scoped, never persisted
 Name the output target so sketch-vs-ship isn't guessed: **fidelity** (sketch / mid-fi /
-high-fi / production — DevRites default is production), **breadth** (one screen / a flow /
+high-fi / production. DevRites default is production), **breadth** (one screen / a flow /
 a surface), **interactivity**, **time intent**. These ride in the brief only; they do not
 change the project's design system, and never get written to `PRODUCT.md` / `DESIGN.md`.
 
@@ -79,33 +79,33 @@ List every state the feature needs and what the user must see/feel in each (defa
 loading initial+subsequent, empty→next-action, error→recovery, success, disabled/
 no-permission, long-content/overflow), the information hierarchy (what's seen 1st / 2nd /
 3rd; primary action unmistakable), responsive reflow, a11y must-haves, and the interaction
-model (inline vs navigated vs — rarely — modal; optimistic vs pending; feedback). Name the
+model (inline vs navigated vs (rarely) modal; optimistic vs pending; feedback). Name the
 representative states, viewports, input modes, and target R-ids that will prove the result;
 "looks polished" is not a proof target. Canonical state list:
 `../devrites-frontend-craft/reference/shape.md`.
 
-## 6. Visual-direction probe — capability-gated
+## 6. Visual-direction probe: capability-gated
 When the work is net-new or directionally ambiguous and fidelity ≥ mid-fi, pressure-test
-the lane with something concrete instead of words — pull Figma context, generate image
+the lane with something concrete instead of words: pull Figma context, generate image
 probes, screenshot reference sites, or route a code-fidelity question to `/rite-prototype`.
 **Capability-gated**: announce the skip in one line if no tool is available. Flow:
 [reference/visual-direction-probe.md](reference/visual-direction-probe.md).
 
 ## 7. AI-slop pre-check
 Run the two-altitude category-reflex check (`../rite-polish/reference/anti-ai-slop.md`) on
-the chosen direction *before* writing the brief — if the palette/theme is guessable from
+the chosen direction *before* writing the brief, if the palette/theme is guessable from
 the category, rework the scene sentence and color strategy. Cheaper to catch the slop in
 the brief than in the build.
 
 ## 8. Write the brief + gate
-Write `design-brief.md` ([reference/brief-template.md](reference/brief-template.md)) —
+Write `design-brief.md` ([reference/brief-template.md](reference/brief-template.md)):
 **compact** (3-5 bullets) when discovery was crisp, **full** when the surface is ambiguous
 or multi-screen. Don't pad a clear brief to look thorough; don't skip the pause to look
 fast. Then honor the run mode (`../devrites-lib/reference/standards/afk-hitl.md`):
-- **HITL** — present the brief and **STOP for explicit confirmation**. The pause is the
+- **HITL:** present the brief and **STOP for explicit confirmation**. The pause is the
   point: shape ends at the user's "go", not at your own certainty. Disagreement → revisit
   the relevant discovery question.
-- **AFK** — assert the best-guess direction, record it in `decisions.md` + an advisory
+- **AFK:** assert the best-guess direction, record it in `decisions.md` + an advisory
   `questions.md` entry, and proceed. A direction touching the irreversible-risk list still
   pauses.
 
@@ -124,11 +124,11 @@ Next: /rite-define (UI slices map to the brief's states) — or /rite-build refi
 ```
 
 ## NEVER (ux-shape)
-- Never write code, markup, or a component here — produce the thinking, not the UI.
+- Never write code, markup, or a component here: produce the thinking, not the UI.
 - Never finalize the brief without naming the **primary action** and the **full state set**
   (not just the happy path).
-- Never decide visual direction by taste when the project has a system — discover first.
-- Never treat an **inspiration** reference as a fidelity target — honor its recorded role.
-- Never skip the HITL confirmation pause "because the brief is obviously right" — ask once,
+- Never decide visual direction by taste when the project has a system: discover first.
+- Never treat an **inspiration** reference as a fidelity target: honor its recorded role.
+- Never skip the HITL confirmation pause "because the brief is obviously right": ask once,
   wait.
-- Never re-derive the brief from scratch in `/rite-build` — refine the existing one.
+- Never re-derive the brief from scratch in `/rite-build`: refine the existing one.

package/pack/generated/claude/skills/devrites-ux-shape/reference/brief-template.md

@@ -1,4 +1,4 @@
-# `design-brief.md` template — the UX/UI contract
+# `design-brief.md` template: the UX/UI contract
 
 The feature-level design decision, produced **before** code by `devrites-ux-shape` (at
 `/rite-spec` when UI is detected) and the **target** the build, polish, and seal check
@@ -97,12 +97,12 @@ Genuinely unresolved only. If you'd write "Recommend: X", decide X instead.
 ```
 
 ## How downstream phases use it
-- `/rite-define` — UI slices map to the **Key states**, **Interaction model**, and **Proof
+- `/rite-define`: UI slices map to the **Key states**, **Interaction model**, and **Proof
   targets**; each UI slice names the visual acceptance it proves.
-- `/rite-build` + `devrites-frontend-craft` — build **to** the brief; refine per slice;
+- `/rite-build` + `devrites-frontend-craft`: build **to** the brief; refine per slice;
   append refinements above instead of re-deriving.
-- `/rite-prove` + `browser-evidence.md` — render the proof targets, compare against the
+- `/rite-prove` + `browser-evidence.md`: render the proof targets, compare against the
   brief + target references, and close material deltas.
-- `/rite-polish` — Phase 4 reads the brief so polish honors the agreed direction.
-- `/rite-seal` + `devrites-frontend-reviewer` — check the UI matches the brief (states
+- `/rite-polish`: Phase 4 reads the brief so polish honors the agreed direction.
+- `/rite-seal` + `devrites-frontend-reviewer`: check the UI matches the brief (states
   covered, direction held, references matched).