devrites 1.19.0

package/pack/.claude/skills/devrites-lib/scripts/coverage.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# coverage.sh — render the AC -> slice(s) -> test -> evidence-status traceability matrix
+# for a feature, from the workspace artifacts. The living map /rite-prove and /rite-seal
+# walk to prove every acceptance criterion is covered and proven. Read-only; deterministic.
+#
+# Convention (pairs with check-acceptance.sh): acceptance criteria carry a stable id —
+#   spec.md  "## Acceptance criteria"  ->  - [ ] [AC1] <criterion>
+#   tasks.md slice                     ->  Satisfies: AC1, AC2
+#   seal.md  "## Acceptance Criteria"  ->  - [x] [AC1] <criterion> — evidence: <...>
+# A criterion is proven iff its [ACn] id is checked ([x]) in seal.md.
+#
+# Usage: coverage.sh [slug]    (slug defaults to .devrites/ACTIVE)
+# Exit:  0 rendered · 2 no workspace
+set -u
+
+slug="${1:-}"
+[ -n "$slug" ] || slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || { echo "coverage: no active workspace." >&2; exit 2; }
+d=".devrites/work/$slug"
+[ -d "$d" ] || { echo "coverage: no workspace at $d." >&2; exit 2; }
+
+spec="$d/spec.md"; tasks="$d/tasks.md"; seal="$d/seal.md"
+
+[ -f "$spec" ] || { echo "coverage: no spec.md — nothing to map." >&2; exit 2; }
+
+echo "# Coverage matrix: $slug"
+echo
+echo "| AC | Slice(s) | Proven in seal? |"
+echo "|----|----------|-----------------|"
+
+# Each [ACn] id mentioned in spec.md.
+grep -oE '\[AC[0-9]+\]' "$spec" 2>/dev/null | tr -d '[]' | sort -u | while IFS= read -r ac; do
+  [ -n "$ac" ] || continue
+  # Slices whose "Satisfies:" line names this AC.
+  slices=""
+  if [ -f "$tasks" ]; then
+    slices="$(awk -v ac="$ac" '
+      /^##[[:space:]]*Slice/ { s=$0; sub(/^##[[:space:]]*/,"",s) }
+      /^[[:space:]]*Satisfies:/ { if (index($0, ac)) { gsub(/^##[[:space:]]*/,"",s); print s } }
+    ' "$tasks" | paste -sd ';' - 2>/dev/null)"
+  fi
+  [ -n "$slices" ] || slices="— (UNCOVERED)"
+  proven="pending"
+  if [ -f "$seal" ] && grep -qE "^[[:space:]]*-[[:space:]]*\[x\][[:space:]]*\[$ac\]" "$seal" 2>/dev/null; then
+    proven="yes"
+  fi
+  printf '| %s | %s | %s |\n' "$ac" "$slices" "$proven"
+done
+
+echo
+echo "_Generated by coverage.sh from spec.md / tasks.md / seal.md. UNCOVERED rows block /rite-vet's analyze gate._"

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# devrites — tool-agnostic CLI over the .devrites/ workflow state.
+#
+# The DevRites discipline lives in the .devrites/ Markdown files + these state
+# scripts, NOT in the Claude Code harness. This CLI is the portable surface over
+# them: any agent (Cursor, Codex, Gemini CLI, CI) or a human can orient, gate,
+# and advance a DevRites workflow by calling `devrites <command>` — no skill
+# prose required. (The MCP wrapper in mcp/devrites-mcp.mjs exposes the same ops
+# as MCP tools.)
+#
+# Run from the project root. Sibling scripts resolve by this file's location;
+# the .devrites/ workspace resolves relative to CWD, like the rest of the pack.
+#
+# Commands & exit codes are listed by `devrites help`.
+
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+usage() {
+  cat <<'EOF'
+devrites — drive the .devrites/ workflow from any tool (run at the project root)
+
+  orient [slug]          orientation digest for the active feature (read-only)
+  status [slug]          alias for orient
+  progress [slug]        progress footer — slice meter + flow ribbon (read-only)
+  ready [slug]           build-readiness gate    (0 ready · 2 no-plan · 3 awaiting · 4 blocked · 5 none)
+  evidence-fresh [slug]  evidence-freshness gate (0 fresh · 3 stale)
+  acceptance [slug|dir]  acceptance-criteria gate (0 all proven · 1 gap)
+  tick-afk [slug]        decrement the AFK slice budget (3 = exhausted)
+  resolve <args...>      answer / --drop / --batch a questions.md entry
+  close [slug]           archive the workspace + clear ACTIVE
+  active                 print the active slug
+  list                   list workspace slugs under .devrites/work/
+  use <slug>             re-point .devrites/ACTIVE to <slug>
+  help                   this text
+EOF
+}
+
+active_slug() { { cat .devrites/ACTIVE 2>/dev/null || true; } | tr -d '[:space:]'; }
+resolve_slug() { local s="${1:-}"; [ -n "$s" ] || s="$(active_slug)"; printf '%s' "$s"; }
+
+cmd="${1:-help}"; [ $# -gt 0 ] && shift || true
+
+case "$cmd" in
+  orient|status)  exec bash "$HERE/preamble.sh" "$@" ;;
+  progress)       exec bash "$HERE/progress.sh" "$@" ;;
+  ready)          exec bash "$HERE/readiness.sh" "$@" ;;
+  evidence-fresh) exec bash "$HERE/evidence-fresh.sh" "$@" ;;
+  acceptance)
+    a="${1:-}"
+    if [ -n "$a" ] && [ -d "$a" ]; then d="$a"
+    else s="$(resolve_slug "${a:-}")"; [ -n "$s" ] || { echo "devrites: no active feature" >&2; exit 5; }; d=".devrites/work/$s"; fi
+    exec bash "$HERE/check-acceptance.sh" "$d" ;;
+  tick-afk)
+    s="$(resolve_slug "${1:-}")"; [ -n "$s" ] || { echo "devrites: no active feature" >&2; exit 5; }
+    exec bash "$HERE/tick-afk.sh" ".devrites/work/$s/state.md" ;;
+  resolve)        exec bash "$HERE/resolve.sh" "$@" ;;
+  close)
+    s="$(resolve_slug "${1:-}")"; [ -n "$s" ] || { echo "devrites: no slug and no ACTIVE" >&2; exit 4; }
+    exec bash "$HERE/close-out.sh" "$s" ;;
+  active)         a="$(active_slug)"; [ -n "$a" ] && printf '%s\n' "$a" || echo "(none)" ;;
+  list)           if [ -d .devrites/work ]; then ls -1 .devrites/work; else echo "(no .devrites/work)"; fi ;;
+  use)
+    s="${1:-}"; [ -n "$s" ] || { echo "usage: devrites use <slug>" >&2; exit 2; }
+    [ -d ".devrites/work/$s" ] || { echo "devrites: no workspace .devrites/work/$s" >&2; exit 5; }
+    printf '%s\n' "$s" > .devrites/ACTIVE; echo "active: $s" ;;
+  help|-h|--help) usage ;;
+  *) echo "devrites: unknown command '$cmd' (try: devrites help)" >&2; usage >&2; exit 2 ;;
+esac

package/pack/.claude/skills/devrites-lib/scripts/doctor.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# doctor.sh — DevRites health diagnose. READ-ONLY. Never writes, never blocks.
+#
+# Checks install integrity + the active .devrites/ workspace for the inconsistencies that
+# silently waste a session: a stale ACTIVE pointer, a corrupt workspace, an orphaned gate,
+# or broken hook wiring. Two surfaces wrap this one core:
+#   - the SessionStart orient hook calls it and surfaces issues only when there are any
+#     (silent-when-healthy);
+#   - the /rite-doctor skill calls it with --verbose for a full report on demand.
+#
+# Usage: doctor.sh [--root DIR] [--verbose]
+# Output: one "issue: <what> — <fix>" line per problem (always); with --verbose, also a
+#   "ok: <check>" line per passing check.
+# Exit:   0 = healthy (no issues);  1 = one or more issues found.
+set -u
+
+ROOT="."
+VERBOSE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root) ROOT="$2"; shift 2 ;;
+    --root=*) ROOT="${1#--root=}"; shift ;;
+    --verbose|-v) VERBOSE=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+issues=0
+issue() { printf 'issue: %s\n' "$1"; issues=$((issues + 1)); }
+ok()    { [ "$VERBOSE" -eq 1 ] && printf 'ok: %s\n' "$1"; return 0; }
+
+DR="$ROOT/.devrites"
+
+# Not a DevRites project at all → nothing to diagnose (stay silent, healthy).
+if [ ! -d "$DR" ]; then
+  ok "no .devrites/ — not a DevRites project"
+  exit 0
+fi
+
+# Resolve the installed pack base (user project = .claude/; dev repo = pack/.claude/).
+BASE="$ROOT/.claude"
+[ -d "$BASE/skills/devrites-lib" ] || BASE="$ROOT/pack/.claude"
+
+# 1. Install integrity — the core shared scripts must be present.
+missing=""
+for s in preamble.sh progress.sh readiness.sh conventions.py; do
+  [ -f "$BASE/skills/devrites-lib/scripts/$s" ] || missing="$missing $s"
+done
+if [ -n "$missing" ]; then
+  issue "install incomplete — missing devrites-lib script(s):$missing — reinstall DevRites"
+else
+  ok "devrites-lib core scripts present"
+fi
+
+# 2. Broken hook wiring — every devrites hook referenced in settings.json must exist on disk.
+SET="$ROOT/.claude/settings.json"
+if [ -f "$SET" ]; then
+  for h in $(grep -oE 'devrites-[a-z-]+\.sh' "$SET" 2>/dev/null | sort -u); do
+    [ -f "$ROOT/.claude/hooks/$h" ] || issue "settings.json wires missing hook: .claude/hooks/$h — reinstall or remove the hook entry"
+  done
+  ok "hook wiring checked"
+fi
+
+# 3. ACTIVE pointer — if set, it must name a real workspace.
+slug="$(cat "$DR/ACTIVE" 2>/dev/null | tr -d '[:space:]')"
+if [ -z "$slug" ]; then
+  ok "no active feature (ACTIVE empty)"
+else
+  WS="$DR/work/$slug"
+  if [ ! -d "$WS" ]; then
+    issue "stale ACTIVE — points at '$slug' but .devrites/work/$slug/ is gone — run /rite-status or 'rite use <slug>'"
+  else
+    ok "active feature '$slug' workspace present"
+    # 4. Corrupt workspace — an active workspace must have state.md.
+    if [ ! -f "$WS/state.md" ]; then
+      issue "corrupt workspace '$slug' — state.md missing — the phase cursor is lost"
+    else
+      ok "workspace '$slug' has state.md"
+      # 5. Orphaned gate — an open validating/blocking question while the feature reads done/shipped.
+      if [ -f "$WS/questions.md" ] && grep -qiE '^status:[[:space:]]*open' "$WS/questions.md" 2>/dev/null \
+         && grep -qiE '^gate:[[:space:]]*(validating|blocking)' "$WS/questions.md" 2>/dev/null \
+         && grep -qiE '(phase|status):[[:space:]]*(done|shipped)' "$WS/state.md" 2>/dev/null; then
+        issue "orphaned gate in '$slug' — an open validating/blocking question remains while state reads done/shipped — resolve it via /rite-resolve"
+      else
+        ok "no orphaned gates in '$slug'"
+      fi
+    fi
+  fi
+fi
+
+[ "$issues" -gt 0 ] && exit 1
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/evidence-fresh.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Evidence-freshness gate for DevRites — enforces the rule in
+# rite-seal/reference/final-evidence.md ("evidence must post-date the code it
+# proves; if any touched file is newer than the proof it is a NO-GO until
+# re-proven") as a deterministic exit code, instead of a prose mtime comparison
+# the model must remember to perform. Used by /rite-seal; usable by /rite-prove.
+# Read-only.
+#
+# Usage: evidence-fresh.sh [slug]
+#   slug — optional; defaults to .devrites/ACTIVE
+#
+# Compares the newest mtime among files referenced in touched-files.md
+# (backtick-quoted paths that still exist) against evidence.md /
+# browser-evidence.md. If any touched file is newer, the proof is stale.
+#
+# Exit codes:
+#   0  fresh (evidence post-dates every touched file) — or nothing to compare
+#   3  STALE — a touched file is newer than the proof → re-run /rite-prove
+#   5  no workspace / no evidence to check
+
+set -euo pipefail
+
+slug="${1:-$(cat .devrites/ACTIVE 2>/dev/null || true)}"
+d=".devrites/work/$slug"
+if [ -z "$slug" ] || [ ! -d "$d" ]; then
+  printf 'evidence-fresh: no active workspace (slug=%s)\n' "${slug:-<unset>}" >&2
+  exit 5
+fi
+
+ev="$d/evidence.md"; bev="$d/browser-evidence.md"; tf="$d/touched-files.md"
+if [ ! -f "$ev" ] && [ ! -f "$bev" ]; then
+  printf 'evidence-fresh: no evidence.md / browser-evidence.md in %s — run /rite-prove\n' "$d" >&2
+  exit 5
+fi
+
+# Portable mtime in epoch seconds: GNU coreutils `stat -c`, BSD/macOS `stat -f`.
+mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; }
+
+newest_ev=0
+for f in "$ev" "$bev"; do
+  [ -f "$f" ] || continue
+  m=$(mtime "$f"); [ "$m" -gt "$newest_ev" ] && newest_ev=$m
+done
+
+if [ ! -f "$tf" ]; then
+  printf 'evidence-fresh: no touched-files.md — nothing to compare (treating as fresh).\n'
+  exit 0
+fi
+
+newest_code=0; newest_path=""
+while IFS= read -r p; do
+  [ -n "$p" ] && [ -f "$p" ] || continue
+  m=$(mtime "$p")
+  if [ "$m" -gt "$newest_code" ]; then newest_code=$m; newest_path="$p"; fi
+done < <(grep -oE '`[^`]+`' "$tf" 2>/dev/null | tr -d '`')
+
+if [ "$newest_code" -gt "$newest_ev" ]; then
+  printf 'evidence-fresh: STALE — %s is newer than the proof. Re-run /rite-prove before GO.\n' "$newest_path" >&2
+  exit 3
+fi
+
+printf 'evidence-fresh: OK — evidence post-dates every touched file.\n'
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/footprint.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# footprint.sh — the fan-out footprint for a feature: how heavy the run was, in numbers
+# DevRites can actually count. NO token or dollar figure is ever produced (DevRites can't
+# truthfully source one — inventing it would violate the proof thesis). Deterministic:
+# every number comes from the append-only dispatch log the orchestrator writes.
+#
+#   footprint.sh log    <slug> <kind> [label]   # append one dispatch record (orchestrator)
+#   footprint.sh render <slug>                   # print the one-line footprint (read-only)
+#
+# kind ∈ wright | reviewer | audit | doubt. The log lives at
+# .devrites/work/<slug>/footprint.log as "<epoch> <kind> <label>" lines.
+set -u
+
+cmd="${1:-}"; slug="${2:-}"
+[ -n "$cmd" ] && [ -n "$slug" ] || { echo "usage: footprint.sh log|render <slug> [...]" >&2; exit 2; }
+
+dir=".devrites/work/$slug"
+log="$dir/footprint.log"
+
+case "$cmd" in
+  log)
+    kind="${3:-}"; label="${4:-}"
+    [ -n "$kind" ] || { echo "usage: footprint.sh log <slug> <kind> [label]" >&2; exit 2; }
+    [ -d "$dir" ] || exit 0   # no workspace → nothing to record (never fail the caller)
+    printf '%s %s %s\n' "$(date +%s)" "$kind" "$label" >> "$log"
+    ;;
+  render)
+    [ -f "$log" ] || { echo "Footprint: n/a (no dispatch records)"; exit 0; }
+    awk '
+      { n++; c[$2]++; e=$1; if (min=="" || e<min) min=e; if (e>max) max=e }
+      END {
+        mins = (max>min) ? int((max-min)/60) : 0
+        w=c["wright"]+0; r=c["reviewer"]+0; a=c["audit"]+0; d=c["doubt"]+0
+        parts=""
+        if (w) parts = parts sep w " wright"; sep=" · "
+        if (r) { parts = parts sep r " reviewer" (r==1?"":"s"); sep=" · " }
+        if (a) { parts = parts sep a " audit" (a==1?"":"s"); sep=" · " }
+        if (d) { parts = parts sep d " doubt"; sep=" · " }
+        printf "Footprint: %d subagent%s (%s) · %d slice%s · ~%dm active\n", \
+               n, (n==1?"":"s"), parts, w, (w==1?"":"s"), mins
+      }' "$log"
+    ;;
+  *)
+    echo "usage: footprint.sh log|render <slug> [...]" >&2; exit 2 ;;
+esac

package/pack/.claude/skills/devrites-lib/scripts/learnings.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# learnings.sh — the cross-feature learning ledger for /rite-learn. Recurring corrections,
+# dismissed review findings, and dead-ends are durable signal that today dies with each
+# archived feature; this captures them in .devrites/learnings.md (loaded by the review
+# skills before a fan-out) and mines archived features for repeated patterns worth
+# promoting to a project rule. `add`/`mine` only; the promotion decision stays human.
+#
+#   learnings.sh add  <slug> "<text>" [tag]   # append a dated entry to the ledger
+#   learnings.sh list                          # print the ledger
+#   learnings.sh mine [archive-dir]            # cluster repeated finding phrases from archived features
+#   learnings.sh nudge [archive-dir]           # silent unless a class recurs >=3x AND new signal since last review
+#
+# Ledger: .devrites/learnings.md (created on first add). `list`/`mine`/`nudge` are read-only.
+# `nudge` snoozes on .devrites/.learnings-reviewed (touched by /rite-learn) so it never nags.
+#
+# Exit codes: 0 ok · 2 bad args
+set -u
+
+ledger=".devrites/learnings.md"
+cmd="${1:-}"
+
+case "$cmd" in
+  add)
+    slug="${2:-}"; text="${3:-}"; tag="${4:-note}"
+    [ -n "$text" ] || { echo "usage: learnings.sh add <slug> \"<text>\" [tag]" >&2; exit 2; }
+    if [ ! -f "$ledger" ]; then
+      mkdir -p "$(dirname "$ledger")"
+      printf '# DevRites learnings ledger\n\nProject-local lessons mined from shipped features — recurring corrections,\ndismissed-finding classes, and dead-ends. Loaded by the review skills before a fan-out so\nthe same false positive or the same mistake does not recur. Untrusted prior: live code\nalways overrides a ledger entry (see rules/security.md).\n\n' > "$ledger"
+    fi
+    printf -- '- [%s] (%s · %s) %s\n' "$(date +%Y-%m-%d)" "$tag" "${slug:-?}" "$text" >> "$ledger"
+    echo "learnings: recorded."
+    ;;
+  list)
+    [ -f "$ledger" ] && cat "$ledger" || echo "learnings: ledger empty ($ledger not present)."
+    ;;
+  mine)
+    arch="${2:-.devrites/archive}"
+    [ -d "$arch" ] || { echo "learnings: no archive at $arch — nothing to mine."; exit 0; }
+    echo "learnings: repeated finding/decision phrases across archived features (count >= 2):"
+    # Pull short finding/dead-end lines, normalize (lowercase, strip ids/paths/numbers), cluster.
+    grep -rhiE '^[-*] |finding|dead end|drift|dismiss' \
+      "$arch"/*/decisions.md "$arch"/*/drift.md "$arch"/*/review.md 2>/dev/null \
+      | sed -E 's/^[-*[:space:]]+//; s/`[^`]*`//g; s/[0-9]+//g; s/[[:space:]]+/ /g' \
+      | tr '[:upper:]' '[:lower:]' \
+      | awk '{ $1=$1; if (length($0) > 12) print substr($0,1,80) }' \
+      | sort | uniq -c | sort -rn \
+      | awk '$1 >= 2 { printf "  %2d×  %s\n", $1, substr($0, index($0,$2)) }' \
+      | head -25
+    echo "(review these — a stable recurring class is a candidate for a project rule or a ledger entry.)"
+    ;;
+  nudge)
+    arch="${2:-.devrites/archive}"
+    [ -d "$arch" ] || exit 0
+    # Cross-feature only: need >=2 shipped features before a "recurring across features" nudge.
+    [ "$(ls -d "$arch"/*/ 2>/dev/null | wc -l | tr -d ' ')" -ge 2 ] || exit 0
+    # Snooze: stay silent if reviewed since the newest archived file changed.
+    marker=".devrites/.learnings-reviewed"
+    if [ -f "$marker" ] && [ -z "$(find "$arch" -type f -newer "$marker" 2>/dev/null | head -1)" ]; then
+      exit 0
+    fi
+    top="$(grep -rhiE '^[-*] |finding|dead end|drift|dismiss' \
+            "$arch"/*/decisions.md "$arch"/*/drift.md "$arch"/*/review.md 2>/dev/null \
+          | sed -E 's/^[-*[:space:]]+//; s/`[^`]*`//g; s/[0-9]+//g; s/[[:space:]]+/ /g' \
+          | tr '[:upper:]' '[:lower:]' \
+          | awk '{ if (length($0) > 12) print substr($0,1,60) }' \
+          | sort | uniq -c | sort -rn | awk '$1 >= 3 { print; exit }')"
+    [ -z "$top" ] && exit 0
+    n="$(printf '%s' "$top" | awk '{print $1}')"
+    phrase="$(printf '%s' "$top" | sed -E 's/^[[:space:]]*[0-9]+[[:space:]]+//' | cut -c1-48)"
+    printf 'learnings: a pattern recurs %sx across shipped features ("%s…") — review + maybe promote it to a rule with /rite-learn.\n' "$n" "$phrase"
+    ;;
+  *)
+    echo "usage: learnings.sh add|list|mine|nudge [...]" >&2; exit 2 ;;
+esac

package/pack/.claude/skills/devrites-lib/scripts/mutation-gate.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# mutation-gate.sh — certify the tests are strong enough to back "done": run the project's
+# mutation runner scoped to the changed files and surface survived mutants (a behaviour no
+# test actually checks). Coverage says a line RAN; mutation says it is CHECKED. Advisory by
+# default (a survivor is a finding for the test reviewer, not an auto-fail) — set
+# DEVRITES_MUTATION=enforce to make a sub-threshold score a hard NO-GO. No runner installed
+# -> exit 0 with a note (never block a project that has no mutation tooling). Best-effort:
+# wraps the runner, does not reimplement it.
+#
+# Usage: mutation-gate.sh [slug]   (slug defaults to .devrites/ACTIVE)
+# Env:   DEVRITES_MUTATION=enforce   DEVRITES_MUTATION_MIN=<percent, default 60>
+# Exit:  0 advisory/clean/no-tool · 2 no workspace · 3 enforce + below threshold
+set -u
+
+slug="${1:-}"
+[ -n "$slug" ] || slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || { echo "mutation-gate: no active workspace." >&2; exit 2; }
+d=".devrites/work/$slug"
+[ -d "$d" ] || { echo "mutation-gate: no workspace at $d." >&2; exit 2; }
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+enforce="${DEVRITES_MUTATION:-advisory}"
+min="${DEVRITES_MUTATION_MIN:-60}"
+
+tool=""
+if [ -f "${root:-.}/stryker.conf.json" ] || [ -f "${root:-.}/stryker.config.js" ] || [ -f "${root:-.}/stryker.config.mjs" ]; then
+  command -v npx >/dev/null 2>&1 && tool="stryker"
+elif command -v mutmut >/dev/null 2>&1; then tool="mutmut"
+elif command -v cosmic-ray >/dev/null 2>&1; then tool="cosmic-ray"
+elif command -v pitest >/dev/null 2>&1 || [ -f "${root:-.}/pom.xml" ]; then tool="pitest"
+fi
+
+if [ -z "$tool" ]; then
+  echo "mutation-gate: no mutation runner detected (stryker / mutmut / cosmic-ray / pitest) — advisory skipped."
+  echo "  Strengthen the criticals by hand-mutating (flip a comparison, drop a guard) and confirming a test goes red (rules/testing.md)."
+  exit 0
+fi
+
+echo "mutation-gate: detected '$tool'. Run it scoped to the slice's changed files and read the mutation score:"
+case "$tool" in
+  stryker)    echo "  npx stryker run --mutate \"\$(git diff --name-only HEAD | paste -sd, -)\"" ;;
+  mutmut)     echo "  mutmut run --paths-to-mutate \"\$(git diff --name-only HEAD | tr '\\n' ' ')\" && mutmut results" ;;
+  cosmic-ray) echo "  (configure session over the changed files, then: cosmic-ray exec ... && cr-report ...)" ;;
+  pitest)     echo "  mvn org.pitest:pitest-maven:mutationCoverage -DtargetClasses=<changed>" ;;
+esac
+echo "  Record the score + any survived mutants in evidence.md; a survivor is a behaviour no test checks (a finding for the test reviewer)."
+echo "  Mode: ${enforce} (DEVRITES_MUTATION=enforce makes a score < ${min}% a NO-GO)."
+
+# This wrapper does not execute the (potentially very slow) runner itself — the score is
+# read by the caller and banded into the seal verdict. Enforce only short-circuits the
+# advisory text; the deterministic NO-GO is applied by /rite-seal against the recorded score.
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/package-existence.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# package-existence.sh — slopsquatting / hallucinated-dependency gate. Before a slice's
+# new third-party imports are trusted, assert each one is actually DECLARED in the project
+# manifest (not just imported) — the entry point for AI-hallucinated package names that
+# don't exist or typo-squat a real one. Distinct from a known-bad-version (IOC) scanner:
+# this catches the fabricated/undeclared dep. Manifest check is deterministic + offline;
+# a registry-existence probe is best-effort and skipped without network.
+#
+# Usage: package-existence.sh [slug]   (slug defaults to .devrites/ACTIVE)
+# Exit:  0 clean / nothing to check · 2 no workspace · 3 undeclared import found
+set -u
+
+slug="${1:-}"
+[ -n "$slug" ] || slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || { echo "package-existence: no active workspace." >&2; exit 2; }
+d=".devrites/work/$slug"
+[ -d "$d" ] || { echo "package-existence: no workspace at $d." >&2; exit 2; }
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$root" ] || { echo "package-existence: not a git repo — skipped." >&2; exit 0; }
+base_tree="$(cat "$d/.reconcile-base" 2>/dev/null || true)"
+ref="${base_tree:-HEAD}"
+
+# Manifest text to grep declared deps against (JS/TS, Python, Go, Rust).
+manifests=""
+for m in package.json requirements.txt pyproject.toml Pipfile go.mod Cargo.toml; do
+  [ -f "$root/$m" ] && manifests="$manifests $root/$m"
+done
+[ -n "$manifests" ] || { echo "package-existence: no recognized manifest — skipped." >&2; exit 0; }
+
+declared() { grep -qiE "(^|[^[:alnum:]_-])$(printf '%s' "$1" | sed 's/[.[\*^$()+?{|]/\\&/g')([^[:alnum:]_-]|\$)" $manifests 2>/dev/null; }
+
+# Newly-added import lines in the diff (lines starting with '+', not the +++ header).
+added="$(git -C "$root" diff "$ref" 2>/dev/null | grep -E '^\+' | grep -vE '^\+\+\+')"
+
+# Extract bare top-level package names from common import forms.
+pkgs="$(printf '%s\n' "$added" | grep -oE \
+  "from +['\"][^'\".]+|require\(['\"][^'\".]+|import +[A-Za-z0-9_]+|^\+[[:space:]]*import +[a-zA-Z0-9_]+" \
+  2>/dev/null \
+  | sed -E "s/.*['\"]//; s/^\+?[[:space:]]*(from|import|require\()?[[:space:]]*//" \
+  | grep -oE '^[@A-Za-z0-9_][A-Za-z0-9_./-]*' \
+  | sed -E 's#^(@[^/]+/[^/]+).*#\1#; s#^([^@][^/]+)/.*#\1#' \
+  | grep -vE '^(\.|/|[A-Z]:)' \
+  | sort -u)"
+
+# Standard-library / local prefixes that never need a manifest entry.
+STD='^(os|sys|re|json|math|time|datetime|typing|collections|itertools|functools|pathlib|subprocess|logging|fmt|errors|context|strings|strconv|net|http|io|bufio|std|core|alloc|crate|self|super|react|node:|fs|path|util|crypto|events|stream|child_process)$'
+
+bad=0; report=""
+while IFS= read -r p; do
+  [ -n "$p" ] || continue
+  printf '%s' "$p" | grep -qE "$STD" && continue
+  if ! declared "$p"; then
+    bad=$((bad+1)); report="${report}  - ${p}: imported but not declared in any manifest
+"
+  fi
+done <<EOF
+$pkgs
+EOF
+
+if [ "$bad" -gt 0 ]; then
+  echo "package-existence: $bad imported package(s) are NOT declared in a manifest — verify each exists and add it via the package manager:" >&2
+  printf '%s' "$report" >&2
+  echo "An undeclared import is how hallucinated/typo-squatted packages slip in. Confirm the name on the registry before trusting it." >&2
+  exit 3
+fi
+echo "package-existence: OK — every new third-party import is declared in a manifest."
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/preamble.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# DevRites orientation preamble — print the active feature's workspace state.
+# Run first (step 0) by every workspace-operating rite-* skill via the standard
+# resolution snippet. Read-only; never mutates workspace files.
+# Portable across harnesses (no Claude-Code-specific `!`-prefix syntax in SKILL.md).
+#
+# Usage: preamble.sh [slug]
+#   slug — optional override; defaults to .devrites/ACTIVE
+#
+# Paths resolve relative to CWD (the project root), matching the rest of the
+# pack; do not anchor to the git root here — callers/tests run it with CWD set
+# to the workspace root, which is not always a git repo.
+#
+# Output: structured plain text the SKILL.md asks the model to orient from.
+
+set -u
+slug="${1:-$(cat .devrites/ACTIVE 2>/dev/null)}"
+d=".devrites/work/$slug"
+
+if [ -z "$slug" ] || [ ! -d "$d" ]; then
+  echo "No active workspace. Run /rite-spec <feature> to start."
+  exit 0
+fi
+
+echo "## $slug"
+if [ -f "$d/state.md" ]; then
+  echo "### state.md"
+  cat "$d/state.md"
+fi
+
+echo
+echo "### artifacts present"
+for f in brief spec references strategy plan tasks eng-review test-plan questions decisions assumptions drift touched-files evidence browser-evidence design-brief polish-report review seal ship handoff; do
+  if [ -f "$d/$f.md" ]; then
+    echo "  ✓ $f.md"
+  fi
+done
+
+echo
+echo "### run mode"
+if [ -f ".devrites/AFK" ]; then
+  echo "  AFK (sentinel present)"
+  # surface optional config without parsing yaml — print non-comment lines verbatim
+  grep -vE '^\s*(#|$)' .devrites/AFK 2>/dev/null | sed 's/^/    /'
+else
+  echo "  HITL (no sentinel)"
+fi
+
+echo
+echo "### questions"
+q="$d/questions.md"
+if [ -f "$q" ]; then
+  # Tally by gate using "status:" + "gate:" lines that follow each "## q-" header.
+  awk '
+    # Finalize the previous block BEFORE resetting — adjacent "## q-" headers
+    # would otherwise drop every open question except the last.
+    /^## q-/ {
+      if (in_q && status == "open") counts[gate]++
+      in_q=1; status=""; gate=""; next
+    }
+    in_q && /^status:/ { sub(/^status:[[:space:]]*/, "", $0); status=$0 }
+    in_q && /^gate:/   { sub(/^gate:[[:space:]]*/,   "", $0); gate=$0 }
+    in_q && /^##[[:space:]]/ {
+      # a non-question header ends the block — finalize; only counts "open"
+      if (status == "open") counts[gate]++
+      in_q=0
+    }
+    END {
+      if (in_q && status == "open") counts[gate]++
+      printf "  open: %d blocking, %d validating, %d advisory, %d escalating\n", \
+        counts["blocking"]+0, counts["validating"]+0, counts["advisory"]+0, counts["escalating"]+0
+    }
+  ' "$q"
+else
+  echo "  (no questions.md yet)"
+fi