devrites 1.19.0

package/pack/.claude/skills/devrites-lib/scripts/test-integrity.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# test-integrity.sh — anti-reward-hacking gate for /rite-build, /rite-prove, /rite-seal.
+# Proves the slice did not reach green by WEAKENING its tests. Diffs the test files
+# against the slice base (the reconcile.sh snapshot tree if present, else HEAD) and
+# flags any test file that was deleted, had a skip/focus marker added, or lost
+# assertions. Turns "never weaken a failing test" (rules/testing.md) into an exit code
+# instead of a prose promise the model can rationalize past — same doctrine as
+# reconcile.sh / readiness.sh. Read-only.
+#
+# Usage:
+#   test-integrity.sh [slug]            (alias: test-integrity.sh check [slug])
+#     slug — optional; defaults to .devrites/ACTIVE
+#
+# Exit codes:
+#   0  clean — no test file deleted, skipped, or de-asserted since the base
+#   2  no active workspace / bad args
+#   3  WEAKENED — a test was deleted, skip/.only-marked, or lost assertions: Critical.
+#      Revert the weakening; fix the code (or route the change as a blocking question).
+set -u
+
+a1="${1:-}"
+case "$a1" in
+  check) slug="${2:-}" ;;
+  ""|-*) slug="" ;;
+  *) slug="$a1" ;;
+esac
+[ -n "$slug" ] || slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || { echo "test-integrity: no active workspace (pass a slug or set .devrites/ACTIVE)." >&2; exit 2; }
+
+d=".devrites/work/$slug"
+[ -d "$d" ] || { echo "test-integrity: no workspace at $d." >&2; exit 2; }
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$root" ]; then
+  echo "test-integrity: not a git repo — gate skipped, eyeball the test diff by hand." >&2
+  exit 0
+fi
+
+base_tree="$(cat "$d/.reconcile-base" 2>/dev/null || true)"
+ref="${base_tree:-HEAD}"
+
+is_test_file() {
+  case "$1" in
+    *_test.*|*.test.*|*.spec.*|*_spec.*|*Test.*|*Tests.*|*Spec.*) return 0 ;;
+    */__tests__/*|*/tests/*|*/test/*|*/spec/*|test_*) return 0 ;;
+    *test*|*spec*) return 0 ;;
+  esac
+  return 1
+}
+
+SKIP_RE='(\bit|\bdescribe|\btest|\bcontext)\.skip|\bxit\b|\bxdescribe\b|\.only\b|@pytest\.mark\.skip|@unittest\.skip|\bpytest\.skip\b|t\.Skip\(|#\[ignore\]|@Ignore\b|@Disabled\b|\bfdescribe\b|\bfit\('
+ASSERT_RE='assert|expect\(|\.should\b|\brequire\.|EXPECT_|ASSERT_|XCTAssert|t\.Error|t\.Fatal'
+
+count() { printf '%s' "${1:-}" | grep -oE "$2" 2>/dev/null | wc -l | tr -d ' '; }
+
+weak=0
+report=""
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  is_test_file "$f" || continue
+  old="$(git -C "$root" show "$ref:$f" 2>/dev/null || true)"
+  [ -n "$old" ] || continue           # new test file — adding tests is never a weakening
+  if [ ! -f "$root/$f" ]; then
+    weak=$((weak+1)); report="${report}  - ${f}: test file DELETED
+"; continue
+  fi
+  new="$(cat "$root/$f")"
+  os="$(count "$old" "$SKIP_RE")"; ns="$(count "$new" "$SKIP_RE")"
+  oa="$(count "$old" "$ASSERT_RE")"; na="$(count "$new" "$ASSERT_RE")"
+  if [ "${ns:-0}" -gt "${os:-0}" ]; then
+    weak=$((weak+1)); report="${report}  - ${f}: skip/focus markers added (${os}→${ns})
+"
+  elif [ "${na:-0}" -lt "${oa:-0}" ]; then
+    weak=$((weak+1)); report="${report}  - ${f}: assertions dropped (${oa}→${na})
+"
+  fi
+done < <(git -C "$root" diff --name-only "$ref" 2>/dev/null)
+
+if [ "$weak" -gt 0 ]; then
+  echo "test-integrity: WEAKENED — $weak test file(s) lost coverage since the slice base:" >&2
+  printf '%s' "$report" >&2
+  echo "A test weakened to pass a gate is a Critical finding. Revert it; fix the code or raise a blocking question." >&2
+  exit 3
+fi
+echo "test-integrity: OK — no test deleted, skipped, or de-asserted since the base."
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/tick-afk.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Decrement the AFK slice budget in state.md — called by /rite-build's record
+# step (workflow step 6) after a slice is built under AFK. The mutable remaining count lives in
+# state.md (`AFK slices remaining: <n>`); `.devrites/AFK`'s `max_slices` is the
+# read-only initial budget and is never rewritten in place.
+#
+# Usage: tick-afk.sh <state.md path>
+#
+# Reads "AFK slices remaining: <n>", decrements it, writes it back in place,
+# and prints the new value.
+#
+# Exit codes:
+#   0  decremented, budget remains (new value > 0); or no AFK budget set (no-op)
+#   3  budget exhausted (new value reached 0) — caller must force a HITL stop
+
+set -euo pipefail
+
+sfile="${1:-}"
+if [ -z "$sfile" ] || [ ! -f "$sfile" ]; then
+  printf 'tick-afk: state.md not found at %s\n' "${sfile:-<unset>}" >&2
+  exit 5
+fi
+
+# Defensive: a state.md without the field means no AFK budget is in effect.
+# Don't invent one; let the build proceed (HITL or unbudgeted AFK).
+# state.md renders fields as markdown bullets ("- AFK slices remaining: <n>").
+# Tolerate an optional leading "- " and a trailing " | none" / comment.
+cur="$(awk 'match($0, /^[[:space:]]*-?[[:space:]]*AFK slices remaining:[[:space:]]*/) {
+              rest = substr($0, RLENGTH + 1); sub(/[[:space:]].*$/, "", rest); print rest; exit }' "$sfile")"
+if [ -z "$cur" ] || [ "$cur" = "none" ]; then
+  printf 'tick-afk: no "AFK slices remaining" budget set in %s — no-op\n' "$sfile"
+  exit 0
+fi
+if ! printf '%s' "$cur" | grep -qE '^[0-9]+$'; then
+  printf 'tick-afk: "AFK slices remaining" is not a number (%s) in %s\n' "$cur" "$sfile" >&2
+  exit 5
+fi
+
+new=$(( cur - 1 ))
+[ "$new" -lt 0 ] && new=0
+
+# Rewrite the field in place. Awk rewrites the file atomically via a temp file.
+awk -v n="$new" '
+  /^[[:space:]]*-?[[:space:]]*AFK slices remaining:/ { print "- AFK slices remaining: " n; next }
+  { print }
+' "$sfile" > "$sfile.tmp" && mv "$sfile.tmp" "$sfile"
+
+printf '%s\n' "$new"
+
+# Budget exhausted — force the caller to stop and revert to HITL.
+[ "$new" -le 0 ] && exit 3
+exit 0

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

@@ -0,0 +1,105 @@
+---
+name: devrites-prose-craft
+description: Write the artifacts and chat replies a senior engineer would — direct, specific, human voice — not the default LLM tells (filler openers, false contrasts, fake profundity, em-dash tics, hedging). Use when a DevRites phase writes prose (spec.md, plan.md, decisions.md, review.md, seal.md, commit/PR bodies) or composes a user-facing reply, and as the catch pass in /rite-polish. Calibrated for technical writing — keeps precise lists, exact terms, and spec structure. Not for code comments and naming (the build-time anti-slop charter covers those) or UI craft (use devrites-frontend-craft).
+user-invocable: false
+---
+
+# devrites-prose-craft — prose that reads human
+
+Strip the default LLM voice from everything DevRites writes. The reader is a teammate, not a
+search engine; the artifact is documentation a person will rely on, not content to fill a box.
+This is the prose sibling of [`devrites-frontend-craft`](../devrites-frontend-craft/SKILL.md):
+craft applied to words instead of UI.
+
+The always-available core is [`.claude/rules/prose-style.md`](../../rules/prose-style.md) — the
+two registers and the cut-list. This skill carries the depth: the full banned-phrase and
+structure references, and the before/after examples. Read the rule first; load a reference
+when you need the full list.
+
+## 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.
+
+## The two registers (calibrated — this is the adaptation that matters)
+DevRites writes in two voices; apply the cut-list to both, but the precision rules differ.
+
+- **Prose** — replies and narrative artifact sections. Optimize for a human voice: direct,
+  specific, active, varied rhythm.
+- **Technical** — acceptance criteria, task slices, API/data contracts, schema, config, test
+  names. Optimize for **precision**. Numbered criteria, complete enumerations, exact
+  identifiers, and domain terms are correct here — **keep them**. Never humanize a spec into
+  vagueness.
+
+The shared rule: cut what carries no information; keep what the reader needs. In prose that
+kills filler; in technical writing it keeps the precise list.
+
+## The cut-list (summary — full lists in references)
+1. **Throat-clearing openers.** "Here's the thing", "It's worth noting", "Let me be clear".
+   State the point. → [`reference/banned-phrases.md`](reference/banned-phrases.md)
+2. **False binary contrast.** "It's not X, it's Y", "not just X but Y", "the question isn't X".
+   State Y directly; drop the negation. → [`reference/structures.md`](reference/structures.md)
+3. **Fake profundity & vague declaratives.** "Let that sink in", "the implications are
+   significant". Show the specific thing or cut the sentence.
+4. **Marketing adjectives on engineering work.** "robust", "scalable", "seamless",
+   "production-ready", "comprehensive". Say what it does and what proves it.
+5. **Hedging stacks & meta-narration.** "it's important to note that, generally"; "in this
+   section we'll…". Make the claim or delete the announcement.
+6. **False agency.** "the data tells us", "the decision emerges". Name who acts.
+7. **Em-dash tics.** A tool, not a tic — at most one per paragraph; multiple is the tell.
+8. **Active voice, varied rhythm.** Named actor at the front; mix sentence lengths; don't
+   stack staccato fragments for drama.
+
+## Strong verbs (technical register)
+Weak verb + adverb → one precise verb. The swap kills filler and sharpens the claim:
+
+| Weak | Strong |
+|---|---|
+| "helps with" / "works to" | powers · enforces · gates · blocks |
+| "makes use of" / "utilizes" | uses |
+| "is responsible for" | owns · writes · renders |
+| "in order to" | to |
+| "has the ability to" | can |
+| "provides support for" | supports |
+| "a number of" / "a variety of" | the actual count |
+
+**Signal, not verdict.** The cut-list flags *signals* of LLM prose, not proof — a precise technical
+list, an exact identifier, or a numbered acceptance criterion can trip a "tell" pattern and still be
+correct. When a flagged construct carries real information (a genuine three-item list, a real
+contrast the spec needs), keep it. Over-correcting precise spec structure into smooth prose is its
+own slop (this is the same calibration as the two registers above).
+
+## Quick check before delivering prose
+- Filler opener or recap of what you just said? Cut it.
+- "Not X, it's Y" anywhere? Rewrite to state Y.
+- A claim of significance with no specific named? Replace with the specific, or cut.
+- A marketing adjective standing in for evidence? Replace with what proves it.
+- Passive voice hiding the actor? Front the actor.
+- More than one em-dash in a paragraph? Reduce to one.
+- Vague attribution ("studies show", "best practice says") with no source named? Cite or cut.
+- Topic-swap test: would the sentence read true for any other feature? Then name the specific.
+- **Technical register intact?** Acceptance criteria still numbered, identifiers exact, real
+  enumerations complete, one name per entity — confirm the calibration didn't strip precision.
+
+Examples (including a slop `spec.md` vs a clean one): [`reference/examples.md`](reference/examples.md).
+
+## Default vs departure
+Match the project's existing writing where it has a voice (its README, ADRs, code comments).
+A house style — even a plain one — beats a "better" foreign voice. Only depart when the
+existing prose is itself slop. When unsure, write flatter and more direct.

package/pack/.claude/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/.claude/skills/devrites-prose-craft/reference/examples.md

@@ -0,0 +1,88 @@
+# 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:**
+> - [AC1] A `GET /reports/:id/export?format=csv` returns `200` with `Content-Type: text/csv`.
+> - [AC2] Rows stream; peak memory stays under 50 MB for a 1M-row export.
+> - [AC3] An unknown `format` returns `400` with `{ "error": "unsupported format" }`.
+
+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 (AC3). 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.
+
+## The pattern across all six
+
+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/.claude/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/.claude/skills/devrites-refresh-indexes/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: devrites-refresh-indexes
+description: Keep the optional code-intelligence indexes — codebase-memory-mcp, codegraph, graphify — current after code changes so the next structural lookup reads live code, not a stale graph. Use when the index looks stale (a structural lookup disagrees with the live code), after a large change before a structural query, or the user says "reindex" / "the graph is stale" / "refresh the index". The Stop hook does this automatically; this skill is the manual force + the reference for it. Not for agentmemory (a separate, judgment-based store).
+user-invocable: false
+---
+
+# 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-refresh-indexes.sh` 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
+H=".claude/hooks/devrites-refresh-indexes.sh"
+[ -f "$H" ] || H="${CLAUDE_PLUGIN_ROOT:-}/pack/.claude/hooks/devrites-refresh-indexes.sh"
+[ -f "$H" ] || H="pack/.claude/hooks/devrites-refresh-indexes.sh"
+bash "$H" --force .
+```
+
+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/.claude/skills/devrites-source-driven/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: devrites-source-driven
+description: Verify uncertain framework or library behavior against official docs or installed source before relying on it, then record the source in `evidence.md` / `decisions.md`. Use when the user says "check the docs", "is this still the API", "don't guess", "cite the source", "verify this assumption", or build encounters an unfamiliar framework call. Not for project-internal code or trivial stdlib calls.
+user-invocable: false
+---
+
+# 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.
+
+## When to trigger
+- You're about to rely on an API signature, default, config key, or behavior you're not
+  sure of.
+- The docs in memory might be stale (the project pins a different version).
+- Tests can't easily prove the assumption, but it drives the implementation.
+- 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
+   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
+   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.
+
+## Rules
+- Prefer the **installed** source over remembered docs — it can't be out of date.
+- Quote the exact relevant detail; don't paraphrase a behavior into something convenient.
+- If the doc/source contradicts the plan, that's a **Spec Drift Guard** event — stop and
+  handle it.
+- Don't rabbit-hole: confirm the one fact you need, record it, return.