devrites 2.6.1 → 3.0.1

package/pack/generated/codex/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/generated/codex/skills/devrites-prose-craft/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: devrites-prose-craft
+description: Internal DevRites skill; DevRites agents invoke it explicitly, not by prompt match.
+user-invocable: false
+---
+
+## Codex compatibility
+
+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.
+- 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.
+
+
+# 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.
+
+## When this fires
+- A text-generating phase composes an artifact: `$rite-spec` (overview, rationale),
+  `$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).
+- `$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
+  the text untouched. Mirrors `devrites-audit`'s read-only stance.
+
+Order findings by severity: **P0** credibility-killers (vague attribution, a marketing
+adjective standing in for evidence, a false/unsourced claim) → **P1** obvious tells (negative
+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.
+
+## 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/generated/codex/skills/devrites-prose-craft/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pack/generated/codex/skills/devrites-prose-craft/reference/banned-phrases.md

@@ -0,0 +1,95 @@
+# Phrases & words to cut
+
+Load this when scrubbing prose. The lists are calibrated for a coding agent: the **AI
+vocabulary** section marks which words are *always* slop versus which are legitimate in
+technical writing, so the skill doesn't flatten a real spec into vagueness.
+
+## Throat-clearing openers (cut — state the point)
+
+- "Here's the thing:" / "Here's what / why / how [X]"
+- "It's worth noting that" / "It's important to note that"
+- "Let me be clear" / "I'll be honest" / "To be honest"
+- "The uncomfortable truth is" / "The reality is" / "It turns out"
+- "Make no mistake" / "At its core" / "At the end of the day"
+- "When it comes to [X]" / "In today's [fast-paced / digital] world"
+
+Any "here's what/this/that" or "it's worth noting" is runway before the point. Delete it and
+start at the point.
+
+## Emphasis crutches (delete — they add no information)
+
+- "Let that sink in." / "Full stop." / "Period."
+- "This matters because" / "Here's why that matters"
+- "This is the deepest problem" / "the stakes are high" / "the consequences are real"
+
+## Hedging stacks (make the claim or cut it)
+
+- "it's important to note that, generally, in most cases…"
+- "perhaps", "could potentially", "it could be argued that", "one might say"
+
+Stacked hedges read as a model covering itself. One honest qualifier is fine; a stack is slop.
+
+## Sycophancy & chatbot artifacts (remove entirely)
+
+These leak the assistant register into artifacts and replies:
+
+- "Great question!" / "You're absolutely right!" / "Certainly!" / "Of course!"
+- "I hope this helps!" / "Let me know if you need anything else" / "Feel free to reach out"
+
+A `decisions.md` entry or a `seal.md` verdict is a document, not a chat turn. No pleasantries.
+
+## Business jargon → plain language
+
+| Avoid | Use instead |
+|---|---|
+| Navigate (challenges) | handle, address |
+| Unpack (the analysis) | explain, examine |
+| Lean into | accept, commit to |
+| Landscape (figurative) | situation, field, area |
+| Game-changer | significant, important |
+| Deep dive | analysis, examination |
+| Circle back / revisit later | return to |
+| Moving forward | next, from now on |
+| On the same page | aligned, agreed |
+
+## AI vocabulary — calibrated (this is the adaptation that matters)
+
+Word lists are blunt instruments. A coding agent must not "fix" a spec that legitimately says
+a system is *robust* under load or exposes a *comprehensive* API. Three tiers:
+
+**Tier 1 — always slop, replace on sight (figurative filler, never load-bearing in a spec):**
+delve / delve into, tapestry, beacon, embark, testament to, realm, landscape (figurative),
+pave the way, shed light on, game-changer, unlock the potential, ever-evolving, vibrant,
+multifaceted, holistic, paradigm (as praise), groundbreaking, transformative, cutting-edge.
+
+**Tier 2 — slop in prose, legitimate in technical context (keep the meaning, judge by use):**
+robust, comprehensive, seamless, leverage, harness, facilitate, underpin, streamline,
+foster, utilize, ecosystem, scalable.
+- In a sentence selling the work ("a robust, scalable, seamless solution") → cut; say what it
+  does and what proves it.
+- In a precise technical claim ("the retry path is robust to a dropped connection — see
+  `evidence.md`") → keep. The word carries a real, tested meaning.
+
+**Tier 3 — flag by density, not per-word:** ordinary words (`important`, `key`, `various`,
+`significant`) become slop only when they cluster. If a paragraph leans on three of them, it's
+saying nothing — name the specific thing instead.
+
+**Co-occurrence tell:** these words travel in packs. Where you find one Tier-1 word, look for
+its neighbours (delve / boasts / bolstered / crucial / pivotal cluster together). One sighting
+means scan the whole passage.
+
+**Match inflected forms.** Each entry covers the word *and* its variants — adverb (`-ly`),
+gerund (`-ing`), plural, conjugations: `delve` also catches `delving` / `delved`; `leverage`
+catches `leveraging` / `leveraged`. The exception is a variant with a distinct, legitimate
+meaning (`real` the intensifier vs `real` meaning factual) — judge it by use, same as the
+tier calibration above.
+
+## Adverbs (cut empty intensifiers; keep load-bearing ones)
+
+Cut the emphasis adverbs that add nothing: really, very, just, literally, genuinely, honestly,
+simply, actually, truly, fundamentally, inherently, inevitably, basically.
+
+Keep adverbs that change meaning or precision: "validate **server-side**", "fail **closed**",
+"runs **concurrently**", "**explicitly** typed". The rule is "cut the empty intensifier", not
+"delete every -ly word" — over-applying the no-adverb rule is its own kind of damage in
+technical writing.

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

@@ -0,0 +1,102 @@
+# Before / after — DevRites artifacts & replies
+
+Real shapes DevRites emits. Each pair keeps the technical content and strips the voice. Note
+how the calibration preserves precise lists and identifiers while cutting the prose slop.
+
+## 1. `spec.md` overview
+
+**Before (slop):**
+> In today's fast-paced data landscape, this feature delivers a robust, scalable, and seamless
+> CSV export capability. It's not just about exporting data — it's about empowering users to
+> unlock the full potential of their information. This is a pivotal step forward.
+
+**After:**
+> Export the report table to CSV. Users currently copy rows by hand; this adds a one-click
+> download. Scope: the reports table only, server-side streaming so memory stays flat on large
+> exports.
+
+Cut the jargon, the negative-parallelism hook, and the importance inflation. Kept what the
+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:**
+> - 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.
+
+## 3. `decisions.md` entry
+
+**Before (slop):**
+> We made the strategic decision to leverage a streaming approach. This robust solution
+> seamlessly handles large datasets and represents a best-in-class architecture that will
+> empower the system to scale effortlessly.
+
+**After:**
+> Stream rows to the response instead of buffering the full file. Buffering OOM-ed on a
+> 1M-row export in testing (see `evidence.md`). Trade-off: streaming rules out a total-row
+> count in the header. Revisit if the UI needs an upfront progress bar.
+
+Named the decision, the reason (with evidence), and the trade-off. That's what an ADR is for.
+
+## 4. `review.md` / `seal.md` finding
+
+**Before (slop):**
+> It's worth noting that the error handling here could potentially be more robust. This is a
+> critical area that fundamentally matters for production readiness.
+
+**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 (AC-003). Catch the parse error
+> narrowly; let the rest propagate.
+
+Severity label, `file:line`, the specific problem, the fix. No hedging, no "fundamentally".
+
+## 5. Chat reply
+
+**Before (slop):**
+> Great question! I've gone ahead and implemented the export feature. It's not just functional
+> — it's production-ready. Let me know if you need anything else!
+
+**After:**
+> Built slice 3 (CSV streaming). Tests pass (`npm test -- export` → 14 passing), peak memory
+> 38 MB on the 1M-row fixture. Next: slice 4 (pagination). Want me to continue?
+
+Dropped the pleasantries and the "not just X" inflation. Led with what's done and the evidence.
+
+## 6. Commit body
+
+**Before (slop):**
+> This commit introduces a comprehensive and robust solution that seamlessly enables users to
+> leverage powerful new export capabilities.
+
+**After:**
+> Buffering the whole CSV OOM-ed on >100k rows. Stream rows to the response so memory stays
+> flat. Rules out an upfront total-count header; tracked in #123.
+
+Followed `git-workflow.md`: the *why*, wrapped, in plain language.
+
+## 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.
+3. Drop negative-parallelism hooks ("not just X, it's Y") and importance labels ("pivotal").
+4. Keep the technical register intact: exact identifiers, status codes, numbered criteria,
+   real enumerations. Precision is not slop.

package/pack/generated/codex/skills/devrites-prose-craft/reference/structures.md

@@ -0,0 +1,134 @@
+# Structures to avoid
+
+The sentence- and paragraph-level shapes that mark machine-written prose. Each row is a
+pattern and its fix. Calibrated: the slop is the *decorative* version; the genuine structural
+version (a real enumeration, a real contrast that carries information) stays.
+
+## Negative parallelism — the "not X, it's Y" family
+
+The single most recognizable tell. It mimics insight by manufacturing a contrast.
+
+| Pattern | Fix |
+|---|---|
+| "It's not X, it's Y." / "It isn't X. It's Y." | State Y. "Y is the cause." |
+| "Not just X, but Y." / "Not only X but also Y." | State both plainly, or just Y if X is filler. |
+| "The question isn't X. It's Y." | Ask the real question once, or state the answer. |
+| "This isn't about X. It's about Y." | "This is about Y." |
+| "X isn't the problem. Y is." | "Y is the problem." |
+| "No X. No Y. Just Z." | "Z." or a normal sentence naming Z. |
+
+Drop the negation; lead with the thing you actually mean.
+
+## Rule of three / decorative tricolon
+
+AI defaults to three-item adjective or benefit triplets. The fix depends on whether the three
+items are *real*.
+
+- **Decorative triad** — "innovative, transformative, and groundbreaking", "fast, reliable, and
+  scalable" as a flourish → cut to the one that's true and provable, or delete.
+- **Real enumeration** — three acceptance criteria, three slices, three status codes the
+  endpoint returns → **keep all three.** This is precision, not slop. The technical register
+  needs the complete list.
+
+Test: if removing one item loses information a reader needs, it's a real list — keep it. If the
+three are interchangeable adjectives, it's a triad — cut it.
+
+## Importance inflation
+
+Announcing significance instead of showing it. Let the reader judge weight.
+
+| Pattern | Fix |
+|---|---|
+| "a pivotal moment", "a broader movement" | Describe what happened; drop the significance label. |
+| "The implications are significant." | Name the specific implication. |
+| "This is a critical step." | Show why it's required (the dependency, the gate, the risk). |
+
+## Vague attribution — cite the source or drop it
+
+The prose twin of DevRites's evidence discipline (`devrites-source-driven`, `evidence.md`). An
+unnamed authority is not a source; it inflates one person's claim into consensus.
+
+| Pattern | Fix |
+|---|---|
+| "Experts believe…", "Studies show…", "Research suggests…" | Name the study/doc/benchmark, or cut the appeal and state the claim on its own merits. |
+| "Best practice says…", "The community recommends…", "It's widely agreed…" | Link the source (an RFC, the framework docs, a measured result), or make the call yourself and own it in `decisions.md`. |
+
+If you can't name who holds the view, you don't have a source — you have a guess. State it as one.
+
+## Abstract category nouns — name the specific items
+
+"Various factors", "several considerations", "a number of issues" say nothing. Replace the
+category word with the actual items.
+
+| Pattern | Fix |
+|---|---|
+| "improvements across various metrics" | "cuts p95 latency 120ms→80ms and halves the query count" |
+| "there are several considerations" | List the considerations, or name the one that matters. |
+| "performance issues", "some edge cases" | Name the N+1 query; name the empty-input and the 10k-row cases. |
+
+Offender words to catch: factors, aspects, considerations, issues, elements, things, areas,
+metrics (unnamed). In a spec or `decisions.md`, the specific item is the whole point.
+
+## False agency — name who acts
+
+Giving inanimate things human verbs. Common in machine prose because it avoids naming the actor.
+
+| Pattern | Fix |
+|---|---|
+| "the data tells us" | "the grader reads X and returns Y" |
+| "the decision emerges" | "we chose X because…" |
+| "the complaint becomes a fix" | "the team fixed it in slice 3" |
+| "the test ensures correctness" | "the test asserts `total === 42`" |
+
+Front the actor: the script, the gate, the function, the engineer, or "you".
+
+## Dramatic fragmentation & rhetorical setups
+
+| Pattern | Fix |
+|---|---|
+| "[Noun]. That's it. That's the [thing]." | One complete sentence. |
+| "X. And Y. And Z." (staccato for drama) | Join into normal sentences; vary length. |
+| "The result? Devastating." (self-posed Q&A) | Fold into a statement. |
+| "What if [reframe]?" as a hook | Make the point directly. |
+| "Think about it:" / "Here's what I mean:" | Delete; the next sentence already does the work. |
+
+## Inflated constructions
+
+Three small tells that pad a plain sentence into something that sounds weightier than it is.
+
+| Pattern | Fix |
+|---|---|
+| **Copula-dodge** — "X serves as / functions as / stands as / boasts / features…" | Use the plain verb. "The gateway **is** the entry point", "the module **has** three handlers". |
+| **Participle tail** — "…, highlighting its importance", "…, reflecting broader trends", "…, underscoring its role as a dynamic hub" | Cut the trailing `-ing` clause; it adds fake depth, not information. |
+| **Aphorism formula** — "X is the Y of Z" ("caching is the heartbeat of the system"), "X is not a tool but a Y" | State the actual property. "The cache holds the hot rows so the DB isn't hit on every request." |
+| **Invented concept label** — coining a pseudo-term as if it's established: "the N+1 tax", "the supervision paradox", "the abstraction trap" | Name the concrete thing and skip the coined label, or define it once if it genuinely recurs. |
+
+## Passive voice (prose register)
+
+Every prose sentence wants a subject doing something. Passive hides the actor and drains energy.
+
+| Pattern | Fix |
+|---|---|
+| "It was decided that…" | "We decided…" |
+| "Mistakes were made." | Name who, and what. |
+| "The endpoint is called by the client." | "The client calls the endpoint." |
+
+Calibration: passive is fine when the actor is genuinely unknown or irrelevant ("the row is
+deleted on cascade"). Don't contort a sentence to name an actor that doesn't matter.
+
+## Rhythm
+
+- Don't run three same-length sentences in a row; don't stack three short fragments for effect.
+- Don't end every paragraph on a punchy one-liner. Vary where the weight lands.
+- **Em-dashes:** at most one per paragraph, used where a comma or period won't do. Multiple per
+  paragraph is the tell. (Catch both the em-dash `—` and the `--` substitute.)
+- Don't open consecutive sentences with the same Wh- word ("What makes this… What this means…")
+  as a crutch; lead with the subject.
+
+## Formatting tells
+
+- **No "Bold term: explanation" bullet lists** as the default structure for prose — the most
+  recognizable AI formatting pattern. Use real prose, or a plain bullet, unless the document's
+  existing style genuinely uses definition lists (a glossary, an API reference).
+- No emoji in headings or section titles (artifacts and code both).
+- Don't over-bold. Bold the one load-bearing term, not every noun.

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

@@ -0,0 +1,63 @@
+---
+name: devrites-refresh-indexes
+description: Internal DevRites skill; DevRites agents invoke it explicitly, not by prompt match.
+user-invocable: false
+---
+
+## Codex compatibility
+
+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.
+- 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.
+
+
+# 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
+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.
+
+All three are **optional** (per `tooling.md`): each is refreshed only if its binary is on PATH
+**and** it already tracks this repo. None present → this is a silent no-op. Never installs
+anything, never blocks. Same incremental shape for all three; no LLM needed for code.
+
+| Index | Tracks repo when | Refresh |
+|---|---|---|
+| **codebase-memory-mcp** (primary) | binary present + repo in `list_projects` (or `.codebase-memory/`) | `codebase-memory-mcp cli index_repository '{"repo_path":"<root>"}'` |
+| **codegraph** | `.codegraph/` exists + `codegraph` on PATH | `codegraph sync` |
+| **graphify** | `graphify-out/` exists + `graphify` on PATH | `graphify update .` |
+
+## 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
+last refresh, else stamps + locks and spawns a **detached** worker so the turn never blocks.
+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:
+
+```bash
+devrites-engine hook refresh-indexes --force .
+```
+
+Then the one case the hook can't cover:
+
+- **Docs / papers / images changed** (not just code) → `graphify update` only re-runs AST. Run
+  the full semantic re-extraction: `/graphify --update` (re-extracts only changed files).
+
+## Notes
+
+- 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
+  ("re-indexed the edited files"), not which tool did it.

package/pack/generated/codex/skills/devrites-refresh-indexes/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false