devrites 3.0.4 → 3.0.6

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

@@ -1,8 +1,8 @@
-# Spec grammar — testable requirements, parseable by tooling
+# 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
+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
@@ -11,24 +11,24 @@ 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
+## 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
+- **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
+- **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
+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)).
 
@@ -49,26 +49,26 @@ The system SHALL reject any session token older than 15 minutes of inactivity.
 
 The rules the validator enforces (`devrites-engine spec-validate`):
 
-- **`### Requirement: <name>`** — a level-3 heading. Its block MUST carry a **SHALL** or
+- **`### 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
+- **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: <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
+- **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
+## 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**
+(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
+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
@@ -80,10 +80,10 @@ support proof, but they are not the criterion unless the spec's surface is expli
 
 - **`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
+  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
+  prove and the test analyst's unit of "is this 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
@@ -92,8 +92,8 @@ support proof, but they are not the criterion unless the spec's surface is expli
 ## 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
+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.
 
@@ -109,16 +109,16 @@ a separate **`## Success metrics`** heading:
 ```
 
 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 —
+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
+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`
+## The validator: `devrites-engine spec-validate`
 
 Deterministic, zero-token. Run it on the workspace (or a spec path) at the spec readiness gate:
 
@@ -126,18 +126,18 @@ Deterministic, zero-token. Run it on the workspace (or a spec path) at the spec
 devrites-engine spec-validate .devrites/work/<slug>
 ```
 
-Exit codes: `0` valid (or no structured requirements — nothing to lint), `1` grammar
+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
+## Delta form: when the capability ledger already holds this behavior
 
-The Requirement / Scenario block is the unit the **capability ledger** stores — the living
+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.
+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:
@@ -158,22 +158,22 @@ The system SHALL default to the OS colour-scheme on first load.
 Removed — superseded by system-preference detection.
 ```
 
-Fold semantics on `devrites-engine ledger sync` — **ADDED** appends, **MODIFIED** replaces the
+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
+  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
+- **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
+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
@@ -181,5 +181,5 @@ 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
+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/codex/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/codex/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/codex/skills/devrites-prose-craft/SKILL.md

@@ -10,13 +10,13 @@ This is the Codex mirror of a DevRites skill. In Codex:
 
 - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
 - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
-- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
-- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
 - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
-- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
 
 
-# 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.
@@ -26,15 +26,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/codex/skills/devrites-refresh-indexes/SKILL.md

@@ -10,16 +10,16 @@ This is the Codex mirror of a DevRites skill. In Codex:
 
 - Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
 - Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
-- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
-- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here: Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review**: an inline pass shares the calling context and is weaker evidence.
 - Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
-- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers: NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
 
 
-# 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.
 
@@ -33,7 +33,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
@@ -42,7 +42,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 .
@@ -58,6 +58,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.