devrites 1.19.0

package/pack/.claude/skills/devrites-interview/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: devrites-interview
+description: One-question-at-a-time interview to extract what the user wants — each question carries a best-guess + structured options; stop at ~95% confidence. Use when the user says "interview me", "grill me", "I'm not sure what I want", or `/rite-spec` / `/rite-define` flags the ask as underspecified. Not for casual clarification or ideation (use `rite-pressure-test`).
+user-invocable: false
+---
+
+# devrites-interview — extract intent
+
+Close the gap between what the user said and what they want, at the cheapest moment —
+before a plan, spec, or code exists.
+
+## Protocol
+- **One question per turn.** Multiple questions get one answered and the rest ignored.
+- **Attach your best guess** to every question, with the reason:
+  > "I'm assuming export is CSV only (covers the stated use case). Right, or also XLSX?"
+  This turns an open question into a cheap correction and exposes your model so the user
+  can fix the premise.
+- **Highest-value question first** — order by how much the answer changes the build. A
+  question that moves the data model or acceptance criteria beats a cosmetic one.
+- **Impact-priority + bounded blocking.** Order unknowns **scope > security/privacy > UX >
+  technical**, and cap **blocking** questions at **≤3** per pass — ask the few that actually gate
+  the spec; **default-and-record** the rest in `assumptions.md` (best-guess + why). A reversible
+  detail never earns a blocking question.
+- **Structured options** when the space is enumerable — present them as the standard ranked
+  **option set** (`rules/afk-hitl.md` → "Option set"): recommended **first**, labelled
+  `(Recommended)`, each with a dimension-tagged rationale (`logic · infra · business ·
+  architecture`, + `security`/`UX`/`risk` when in scope), plus the escape hatch. Render via
+  `AskUserQuestion` when the harness has it:
+  ```
+  1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+  2. <alternative> — <rationale + the trade-off it accepts>
+  3. Something else — I'll describe it
+  ```
+
+## Stop condition
+Stop when **any** holds — don't interrogate past the point of value:
+- **Confidence** — you can predict the next answer (~95%); remaining unknowns are
+  reversible details that don't change the spec.
+- **Convergence** — the last 2–3 answers only rubber-stamped your guesses and didn't
+  move the spec.
+- **Soft cap** — after ~8 material questions, proceed with your best-guess answers logged
+  in `assumptions.md` rather than asking more (hard-stop sooner if the ask is small).
+
+Depth on the few that matter, not breadth for its own sake. If answers stop converging —
+you keep circling one area without progress — **reframe once** (below) instead of asking
+another question.
+
+## Don't ask
+- Things the codebase answers (read it first).
+- Reversible implementation details (decide, log as an assumption).
+- Everything at once "to be thorough."
+
+## When the ask is vague — map the decision tree first
+For a one-line or fuzzy ask (`"design a contact page"`), don't fire isolated questions.
+First sketch the **decision tree** — the branches the answer splits into — and resolve
+each branch **depth-first** with the protocol above. Domain branches per area:
+`rite-spec/reference/interview-patterns.md`.
+
+## Reframe (once, when stuck)
+If the interview isn't converging, spend **one** turn challenging the premise rather than
+refining it — *"is a form even the right answer here, or a mailto / booking link?"* A good
+reframe collapses several open branches. Use it sparingly, then resume the protocol.
+
+## /clarify mode — coverage scan of an existing spec
+When invoked to clarify a written spec (not extract intent from scratch), scan it against the fixed
+taxonomy and mark each **Clear / Partial / Missing**: Functional scope · Data model · Interaction
+(API / UI states) · Non-functional (auth / latency / scale / compliance) · Edge cases (empty /
+boundary / invalid / concurrent / failure). Then ask **≤5 prioritized questions** (impact order
+above), targeting Missing before Partial, one per turn with a best-guess attached. **Integrate each
+answer into the right spec section** as it lands — not just a Q&A log — and append a dated
+**`## Clarifications`** block to `spec.md` (Q + resolution) for durable provenance. Re-run the scan
+after answers; stop when every area is Clear or explicitly deferred, then re-score the affected
+`checklists/<domain>.md`.
+
+## Output
+A short summary the caller can use: objective in one sentence, confirmed decisions,
+still-open (non-blocking) items, recommended next step. If a workspace is active, write
+Q&A to `questions.md`, confirmed calls to `decisions.md`, standing guesses to
+`assumptions.md`. If not, just return the summary — don't create a workspace.
+
+Domain question ladders: `rite-spec/reference/interview-patterns.md`.

package/pack/.claude/skills/devrites-lib/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: devrites-lib
+description: Internal shared-script library for DevRites — not a user command and not model-invocable. It exists only to ship DevRites' cross-cutting helper scripts (notably the read-only orientation preamble that every workspace-operating rite-* skill runs at step 0) on both the bash-installer and plugin channels. No workflow; do not invoke.
+user-invocable: false
+disable-model-invocation: true
+---
+
+# devrites-lib — internal shared scripts (not a command)
+
+This is **not** a skill you run. It is a library directory housing DevRites'
+cross-cutting helper scripts under `scripts/`, placed inside `skills/` so they
+install on **both** distribution channels (the bash installer copies the pack's
+`skills/` tree into the project's `.claude/`; the plugin ships the `skills/`
+tree). Skills resolve these scripts with the standard three-layout snippet:
+the installed `.claude/` path first, then the plugin cache via
+`${CLAUDE_SKILL_DIR}` (best-effort — Claude Code doesn't expose a stable script path to skill-invoked bash on the plugin channel, so the preamble degrades to reading `state.md` there), then the repo source tree for DevRites
+self-development.
+
+## Scripts
+
+All resolve with the standard three-layout snippet (installed `.claude/` path
+first, then `${CLAUDE_SKILL_DIR}`, then the repo `pack/` source).
+
+**Read-only — orient / gate (never mutate the workspace):**
+
+- `scripts/preamble.sh` — orientation digest for the active `.devrites/` feature:
+  prints `state.md`, the artifacts present, the run mode (HITL/AFK), and the
+  open-question tally by gate. Run first (step 0) by every workspace-operating
+  `rite-*` skill so the model orients deterministically instead of re-deriving
+  state from raw Markdown.
+- `scripts/progress.sh` — progress footer; the mirror of `preamble.sh` (which runs
+  first). Run **last** (output step) by every lifecycle `rite-*` skill to render — from
+  `state.md`, with zero model drift — the `── rite-<phase> ──` header rule, the **slice
+  meter** (`Slice 3/5  ██████░░░░  <last-built> ✓`, or `Slices 5/5  ██████████  ✅ ALL
+  BUILT` at completion), and the **flow ribbon** (`spec ✓ define ✓ build ◉ … ship ○`).
+  The meter answers "how many slices left"; the `✅ ALL BUILT` marker answers "is the
+  build done". The skill prints its own what-was-done / next-step / hygiene lines beneath
+  it. Read-only; silent (exit 0) when there is no active workspace. Not for the workspace-less
+  utilities (`/rite-prototype`, `/rite-zoom-out`, `/rite-pressure-test`, `/rite-handoff`,
+  the `/rite` menu) — they have no phase/slice state to render.
+- `scripts/readiness.sh` — build-readiness gate. Exits non-zero on `/rite-build`'s
+  step-0 stop conditions so they hold by exit code, not by prose the model must
+  remember: `2` no `Plan approved` (→ `/rite-define`), `3` `awaiting_human`
+  (→ `/rite-resolve`), `4` `blocked` (→ `/rite-plan`), `5` no workspace, `0` ready.
+- `scripts/evidence-fresh.sh` — evidence-freshness gate for `/rite-seal`. Exits `3`
+  when any file in `touched-files.md` is newer than `evidence.md` /
+  `browser-evidence.md` (stale proof = NO-GO until re-proven), `0` when fresh.
+- `scripts/check-acceptance.sh` — executable acceptance gate. Compiles `spec.md`'s
+  `[ACn]`-tagged criteria and exits `1` unless every one is checked (proven) in `seal.md`;
+  used by `/rite-seal` and by the outcome grader.
+
+**State mutators — write `state.md` / `questions.md` under one contract:**
+
+- `scripts/tick-afk.sh` — decrement the AFK slice budget; exits `3` at 0 (forced HITL stop).
+- `scripts/resolve.sh` — backs the `/rite-resolve` contract (answer / drop / batch).
+- `scripts/close-out.sh` — archive the workspace + clear `ACTIVE` on `/rite-ship`.
+
+### Canonical footer snippet
+
+Every lifecycle `rite-*` skill prints this as the **first lines of its output**, then its
+own fact lines below. Same three-layout resolver as the step-0 preamble:
+
+```bash
+PR=.claude/skills/devrites-lib/scripts/progress.sh
+[ -f "$PR" ] || PR="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/progress.sh"
+[ -f "$PR" ] || PR=pack/.claude/skills/devrites-lib/scripts/progress.sh
+[ -f "$PR" ] && bash "$PR" || true
+```
+
+**Unified entrypoint (tool-agnostic):**
+
+- `scripts/devrites.sh` — one CLI dispatching to all of the above (`orient` / `ready` /
+  `evidence-fresh` / `acceptance` / `tick-afk` / `resolve` / `close` / `active` / `list` /
+  `use`), so any agent or human can drive `.devrites/` without the skill prose. The MCP
+  wrapper `mcp/devrites-mcp.mjs` exposes the read/gate ops as MCP tools. See
+  [`docs/cli-mcp.md`](../../../../docs/cli-mcp.md).

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# analyze.sh — cross-artifact consistency + coverage gate for /rite-vet, run read-only
+# over spec.md / tasks.md (+ coverage.md) BEFORE any code. One pass proving the artifacts
+# are mutually consistent and the plan fully covers the spec, so a gap is caught when it
+# is a one-line plan edit, not a reslice mid-build. Deterministic where it can be; the
+# model walks the rest.
+#
+# Checks (each finding: "[severity] <locus> — issue"):
+#   Coverage      — every [ACn] in spec.md maps to >=1 slice (tasks.md Satisfies:)   CRITICAL
+#   Dangling-ref  — a slice Satisfies: an AC id that does not exist in spec.md         CRITICAL
+#   Orphan-slice  — a slice satisfies no acceptance criterion                          warn
+#
+# Usage: analyze.sh [slug]    (slug defaults to .devrites/ACTIVE)
+# Exit:  0 clean · 1 CRITICAL found (blocks /rite-build) · 2 no workspace
+set -u
+
+slug="${1:-}"
+[ -n "$slug" ] || slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || { echo "analyze: no active workspace." >&2; exit 2; }
+d=".devrites/work/$slug"
+spec="$d/spec.md"; tasks="$d/tasks.md"
+[ -f "$spec" ] && [ -f "$tasks" ] || { echo "analyze: need spec.md + tasks.md in $d." >&2; exit 2; }
+
+spec_acs="$(grep -oE '\[AC[0-9]+\]' "$spec" 2>/dev/null | tr -d '[]' | sort -u)"
+task_acs="$(grep -oE '\bAC[0-9]+\b' "$tasks" 2>/dev/null | sort -u)"
+
+crit=0
+echo "# Cross-artifact analysis: $slug"
+echo
+
+# Coverage: spec ACs with no slice reference.
+echo "## Coverage"
+if [ -z "$spec_acs" ]; then
+  echo "- [warn] spec.md — no [ACn] acceptance ids found; tag criteria as '[AC1] ...' for a machine-checkable gate."
+else
+  while IFS= read -r ac; do
+    [ -n "$ac" ] || continue
+    if printf '%s\n' "$task_acs" | grep -qxF "$ac"; then
+      echo "- [ok] $ac — covered"
+    else
+      echo "- [CRITICAL] $ac (spec.md) — no slice Satisfies it (uncovered)"; crit=$((crit+1))
+    fi
+  done <<EOF
+$spec_acs
+EOF
+fi
+
+# Dangling refs: tasks Satisfies an AC the spec doesn't define.
+echo
+echo "## Consistency"
+if [ -n "$task_acs" ]; then
+  while IFS= read -r ac; do
+    [ -n "$ac" ] || continue
+    if ! printf '%s\n' "$spec_acs" | grep -qxF "$ac"; then
+      echo "- [CRITICAL] $ac (tasks.md) — referenced by a slice but not defined in spec.md (dangling)"; crit=$((crit+1))
+    fi
+  done <<EOF
+$task_acs
+EOF
+fi
+
+# Orphan slices: a slice with no Satisfies line.
+orphans="$(awk '
+  /^##[[:space:]]*Slice/ { if (name!="" && !sat) print name; name=$0; sub(/^##[[:space:]]*/,"",name); sat=0 }
+  /^[[:space:]]*Satisfies:/ { sat=1 }
+  END { if (name!="" && !sat) print name }
+' "$tasks" 2>/dev/null)"
+if [ -n "$orphans" ]; then
+  echo "$orphans" | while IFS= read -r s; do [ -n "$s" ] && echo "- [warn] slice '$s' — satisfies no acceptance criterion (add Satisfies: or justify)"; done
+fi
+
+echo
+if [ "$crit" -gt 0 ]; then
+  echo "## Verdict: BLOCKED — $crit CRITICAL finding(s). Resolve before /rite-build."
+  exit 1
+fi
+echo "## Verdict: clear — spec/tasks consistent and fully mapped."
+exit 0

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

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Executable acceptance criteria — compile spec.md's acceptance criteria into
+# machine-checkable items and verify each is proven (checked) in seal.md. Turns
+# "walk acceptance one by one" (rite-seal/reference/final-evidence.md) into a
+# deterministic check instead of prose the model walks by hand.
+#
+# Convention (optional but recommended): tag each criterion with a stable id —
+#   spec.md  "## Acceptance criteria"   →  - [ ] [AC1] <criterion>
+#   seal.md  "## Acceptance Criteria"   →  - [x] [AC1] <criterion> — evidence: <…>
+# A criterion is "done" iff its [ACn] id is CHECKED ([x]) in seal.md. This is what
+# makes the criterion executable: a stable handle the prove/seal phases grade against.
+# Without ids it falls back to a count/unchecked heuristic and recommends adding them.
+#
+# Usage: check-acceptance.sh <workspace-dir>
+# Exit:  0 every spec criterion proven in seal · 1 gap (uncovered/unproven) ·
+#        2 usage · 5 missing spec.md or seal.md
+
+set -euo pipefail
+
+ws="${1:-}"
+if [ -z "$ws" ] || [ ! -d "$ws" ]; then
+  printf 'usage: check-acceptance.sh <workspace-dir>\n' >&2
+  exit 2
+fi
+spec="$ws/spec.md"; seal="$ws/seal.md"
+[ -f "$spec" ] || { printf 'check-acceptance: no spec.md in %s\n' "$ws" >&2; exit 5; }
+[ -f "$seal" ] || { printf 'check-acceptance: no seal.md in %s — feature not sealed\n' "$ws" >&2; exit 5; }
+
+# Print the body lines under an "## Acceptance Criteria" heading (case-insensitive
+# on "criteria"), up to the next "## " heading. BSD/GNU awk safe (no IGNORECASE).
+ac_section() { awk '/^##[[:space:]]+[Aa]cceptance [Cc]riteria/{s=1;next} /^##[[:space:]]/{s=0} s' "$1"; }
+
+spec_body="$(ac_section "$spec")"
+seal_body="$(ac_section "$seal")"
+
+if [ -z "$spec_body" ]; then
+  printf 'check-acceptance: spec.md has no "## Acceptance criteria" section — nothing to grade\n' >&2
+  exit 1
+fi
+
+spec_ids="$(printf '%s\n' "$spec_body" | grep -oE '\[AC[0-9]+\]' | sort -u || true)"
+
+if [ -n "$spec_ids" ]; then
+  # ID mode — each spec [ACn] must appear on a checked ([x]) line in seal.md.
+  seal_checked="$(printf '%s\n' "$seal_body" | grep -E '^[[:space:]]*-[[:space:]]*\[[xX]\]' | grep -oE '\[AC[0-9]+\]' | sort -u || true)"
+  missing=""
+  for id in $spec_ids; do
+    printf '%s\n' "$seal_checked" | grep -qxF "$id" || missing="$missing $id"
+  done
+  total=$(printf '%s\n' "$spec_ids" | grep -c . || true)
+  if [ -n "$missing" ]; then
+    printf 'check-acceptance: %d/%d criteria proven; UNPROVEN/UNCOVERED:%s (must be checked [x] in seal.md)\n' \
+      "$(( total - $(printf '%s' "$missing" | wc -w) ))" "$total" "$missing" >&2
+    exit 1
+  fi
+  printf 'check-acceptance: OK — all %d acceptance criteria (%s) proven + checked in seal.md\n' "$total" "$(printf '%s' "$spec_ids" | tr '\n' ' ')"
+  exit 0
+fi
+
+# Fallback (no ids) — count spec criteria vs seal checked/unchecked items.
+spec_n=$(printf '%s\n' "$spec_body" | grep -cE '^[[:space:]]*-[[:space:]]' || true)
+seal_total=$(printf '%s\n' "$seal_body" | grep -cE '^[[:space:]]*-[[:space:]]*\[[ xX]\]' || true)
+seal_unchecked=$(printf '%s\n' "$seal_body" | grep -cE '^[[:space:]]*-[[:space:]]*\[[[:space:]]\]' || true)
+
+if [ "$seal_total" -lt "$spec_n" ]; then
+  printf 'check-acceptance: seal.md lists %d acceptance items but spec.md has %d criteria — %d dropped. (Tag criteria [AC1].. to grade by id.)\n' \
+    "$seal_total" "$spec_n" "$(( spec_n - seal_total ))" >&2
+  exit 1
+fi
+if [ "$seal_unchecked" -gt 0 ]; then
+  printf 'check-acceptance: %d acceptance criterion(s) unchecked in seal.md (unproven). (Tag criteria [AC1].. to grade by id.)\n' "$seal_unchecked" >&2
+  exit 1
+fi
+printf 'check-acceptance: OK — %d acceptance items all checked in seal.md (no ids; add [AC1].. for id-level grading)\n' "$seal_total"
+exit 0

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Close a shipped feature: archive its workspace and clear the ACTIVE cursor.
+#
+# Moves .devrites/work/<slug>/ -> .devrites/archive/<slug>/ (preserving every .md
+# audit file) and clears .devrites/ACTIVE so the next /rite-spec starts clean. The
+# audit trail is never deleted — only relocated.
+#
+# Usage: close-out.sh <slug> [devrites-dir]
+#   devrites-dir defaults to .devrites
+#
+# Exit codes:
+#   0  archived (+ ACTIVE cleared if it pointed at <slug>)
+#   4  bad args / workspace missing
+#   5  archive destination already exists (refuse to clobber)
+set -euo pipefail
+
+slug="${1:-}"
+dv="${2:-.devrites}"
+
+if [ -z "$slug" ]; then
+  echo "close-out: usage: close-out.sh <slug> [devrites-dir]" >&2
+  exit 4
+fi
+
+work="$dv/work/$slug"
+arch="$dv/archive/$slug"
+
+if [ ! -d "$work" ]; then
+  echo "close-out: no workspace at $work" >&2
+  exit 4
+fi
+if [ -e "$arch" ]; then
+  echo "close-out: archive already exists at $arch — refusing to clobber" >&2
+  exit 5
+fi
+
+mkdir -p "$dv/archive"
+mv "$work" "$arch"
+
+# Clear ACTIVE only if it still points at the slug we just archived.
+if [ -f "$dv/ACTIVE" ] && [ "$(tr -d '[:space:]' < "$dv/ACTIVE")" = "$slug" ]; then
+  : > "$dv/ACTIVE"
+  echo "close-out: archived $slug -> $arch and cleared ACTIVE"
+else
+  echo "close-out: archived $slug -> $arch (ACTIVE pointed elsewhere — left as-is)"
+fi
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/conventions.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""DevRites conventions ledger — store + deterministic corroboration scorer.
+
+The ledger is a project-scoped, LOCAL record (`.devrites/conventions.md`, gitignored)
+of conventions a *sealed slice proved* about this codebase: build/test commands, naming /
+layering / error-model idioms, recurring gotchas, where things live. `/rite-seal` promotes
+to it on a GO; orient reads it so the wright stops re-deriving the same idioms every slice.
+
+Two things live here (issue B1 modules M1 + M2):
+
+  M1 — corroboration scorer (`band`): a pure, deterministic function from corroboration
+       and contradiction counts to a 0.3–0.9 confidence band. The number is EARNED by how
+       many independent sealed slices proved the convention — never guessed by a model.
+
+  M2 — ledger store (`read` / `promote` / `contradict`): read/update `.devrites/conventions.md`,
+       a human-readable Markdown file with per-entry provenance.
+
+Confidence never raises a convention's *authority*: a high-band entry is still untrusted
+data, and a fresh observation of the live code always overrides it (enforced at orient,
+issue B2 — not here).
+
+Usage:
+  conventions.py band --corroborations C --contradictions K
+  conventions.py read [--root DIR]
+  conventions.py promote   --key K --statement S --kind KIND --slug SLUG --evidence E [--date ISO] [--root DIR]
+  conventions.py contradict --key K --slug SLUG --evidence E [--date ISO] [--root DIR]
+
+Exit codes: 0 ok; 2 usage error; 3 not-found (contradict on an unknown key).
+"""
+import argparse
+import datetime
+import os
+import sys
+
+LEDGER_RELPATH = os.path.join(".devrites", "conventions.md")
+
+HEADER = """# DevRites conventions ledger
+
+Conventions proven by sealed slices on this project. **Local, gitignored, advisory.**
+The confidence band is earned: it reflects how many independent sealed slices corroborated
+the convention — it is not a model's guess. A high band is still untrusted data; a fresh
+observation of the live code always wins over a stale entry here.
+"""
+
+
+# --- M1: deterministic corroboration scorer -------------------------------
+
+def band(corroborations, contradictions):
+    """Pure, total, deterministic. Return a 0.3–0.9 band, or None if retired.
+
+    First proof seeds mid-band; each further independent corroboration raises it
+    toward the 0.9 cap; each contradiction lowers it; net non-positive retires it.
+    """
+    c = int(corroborations)
+    k = int(contradictions)
+    if c - k <= 0:
+        return None  # retired — contradictions caught up with the evidence
+    raw = 0.4 + 0.1 * c - 0.2 * k
+    return max(0.3, min(0.9, round(raw, 1)))
+
+
+# --- M2: ledger store -----------------------------------------------------
+
+def _ledger_path(root):
+    return os.path.join(root, LEDGER_RELPATH)
+
+
+def _parse(text):
+    """Parse the ledger into {key: entry}. entry = dict with fields + proofs list."""
+    entries = {}
+    key = None
+    for line in text.splitlines():
+        if line.startswith("## "):
+            key = line[3:].strip()
+            entries[key] = {
+                "statement": "", "kind": "", "corroborations": 0,
+                "contradictions": 0, "status": "active", "proofs": [],
+            }
+            continue
+        if key is None:
+            continue
+        s = line.strip()
+        if s.startswith("- proof:"):
+            entries[key]["proofs"].append(s[len("- proof:"):].strip())
+        elif s.startswith("- ") and ":" in s:
+            fld, val = s[2:].split(":", 1)
+            fld, val = fld.strip(), val.strip()
+            if fld in ("corroborations", "contradictions"):
+                try:
+                    entries[key][fld] = int(val)
+                except ValueError:
+                    pass
+            elif fld in ("statement", "kind", "status"):
+                entries[key][fld] = val
+    return entries
+
+
+def _serialize(entries):
+    out = [HEADER]
+    for key in sorted(entries):
+        e = entries[key]
+        b = band(e["corroborations"], e["contradictions"])
+        status = "retired" if b is None else "active"
+        e["status"] = status
+        band_str = "retired" if b is None else "%.2f" % b
+        out.append("## %s" % key)
+        out.append("- statement: %s" % e["statement"])
+        out.append("- kind: %s" % e["kind"])
+        out.append("- band: %s" % band_str)
+        out.append("- corroborations: %d" % e["corroborations"])
+        out.append("- contradictions: %d" % e["contradictions"])
+        out.append("- status: %s" % status)
+        for p in e["proofs"]:
+            out.append("- proof: %s" % p)
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _load(root):
+    path = _ledger_path(root)
+    if not os.path.isfile(path):
+        return {}
+    with open(path, "r", encoding="utf-8") as fh:
+        return _parse(fh.read())
+
+
+def _save(root, entries):
+    path = _ledger_path(root)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(_serialize(entries))
+
+
+def _today(date):
+    return date or datetime.date.today().isoformat()
+
+
+def cmd_read(root):
+    path = _ledger_path(root)
+    if not os.path.isfile(path):
+        return 0
+    with open(path, "r", encoding="utf-8") as fh:
+        sys.stdout.write(fh.read())
+    return 0
+
+
+def cmd_orient(root, min_band):
+    """Print a compact digest of ACTIVE conventions for the wright's ORIENT step.
+
+    These are priors, not law: high-band entries are followed unless the slice contract
+    says otherwise, and a fresh observation of the live code always overrides a stale one.
+    Retired entries are omitted. Empty output (exit 0) means no priors to apply.
+    """
+    entries = _load(root)
+    rows = []
+    for key, e in entries.items():
+        b = band(e["corroborations"], e["contradictions"])
+        if b is None or b < min_band:
+            continue
+        rows.append((b, key, e))
+    if not rows:
+        return 0
+    rows.sort(key=lambda r: (-r[0], r[1]))
+    print("# Conventions ledger — proven priors (live code always overrides)")
+    for b, key, e in rows:
+        kind = (" (%s)" % e["kind"]) if e["kind"] else ""
+        print("- [%.2f] %s%s: %s" % (b, key, kind, e["statement"]))
+    return 0
+
+
+def cmd_promote(root, key, statement, kind, slug, evidence, date):
+    entries = _load(root)
+    e = entries.get(key)
+    if e is None:
+        e = {"statement": statement, "kind": kind, "corroborations": 0,
+             "contradictions": 0, "status": "active", "proofs": []}
+        entries[key] = e
+    else:
+        # keep the latest non-empty statement/kind
+        if statement:
+            e["statement"] = statement
+        if kind:
+            e["kind"] = kind
+    # Corroboration counts DISTINCT sealed slices — re-sealing the same slice is idempotent.
+    already = any(p.split(" ", 1)[0] == slug for p in e["proofs"])
+    if not already:
+        e["corroborations"] += 1
+        e["proofs"].append("%s %s — %s" % (slug, _today(date), evidence))
+    _save(root, entries)
+    b = band(e["corroborations"], e["contradictions"])
+    print("promoted '%s' → band %s (%d corroboration(s))"
+          % (key, "retired" if b is None else "%.2f" % b, e["corroborations"]))
+    return 0
+
+
+def cmd_contradict(root, key, slug, evidence, date, drift_file):
+    entries = _load(root)
+    e = entries.get(key)
+    if e is None:
+        print("no such convention: '%s'" % key, file=sys.stderr)
+        return 3
+    e["contradictions"] += 1
+    e["proofs"].append("%s %s — CONTRADICTED: %s" % (slug, _today(date), evidence))
+    _save(root, entries)
+    b = band(e["corroborations"], e["contradictions"])
+    state = "retired" if b is None else "band %.2f" % b
+    when = _today(date)
+    # The orchestrator (rite-build) is the single writer of .devrites bookkeeping; it passes
+    # --drift-file so the contradiction is logged to the feature's drift.md atomically here.
+    if drift_file:
+        os.makedirs(os.path.dirname(os.path.abspath(drift_file)), exist_ok=True)
+        with open(drift_file, "a", encoding="utf-8") as fh:
+            fh.write(
+                "\n## convention-drift: %s\n"
+                "- slice: %s\n- contradicted_by: %s\n- now: %s\n- at: %s\n"
+                % (key, slug, evidence, state, when))
+    print("DRIFT: convention '%s' contradicted by %s — now %s" % (key, slug, state))
+    return 0
+
+
+def main(argv):
+    p = argparse.ArgumentParser(prog="conventions.py", add_help=True)
+    sub = p.add_subparsers(dest="cmd")
+
+    pb = sub.add_parser("band")
+    pb.add_argument("--corroborations", type=int, required=True)
+    pb.add_argument("--contradictions", type=int, default=0)
+
+    pr = sub.add_parser("read")
+    pr.add_argument("--root", default=".")
+
+    po = sub.add_parser("orient")
+    po.add_argument("--root", default=".")
+    po.add_argument("--min-band", type=float, default=0.0)
+
+    pp = sub.add_parser("promote")
+    pp.add_argument("--key", required=True)
+    pp.add_argument("--statement", required=True)
+    pp.add_argument("--kind", required=True)
+    pp.add_argument("--slug", required=True)
+    pp.add_argument("--evidence", required=True)
+    pp.add_argument("--date", default=None)
+    pp.add_argument("--root", default=".")
+
+    pc = sub.add_parser("contradict")
+    pc.add_argument("--key", required=True)
+    pc.add_argument("--slug", required=True)
+    pc.add_argument("--evidence", required=True)
+    pc.add_argument("--date", default=None)
+    pc.add_argument("--root", default=".")
+    pc.add_argument("--drift-file", default=None)
+
+    args = p.parse_args(argv[1:])
+    if args.cmd == "band":
+        b = band(args.corroborations, args.contradictions)
+        print("retired" if b is None else "%.2f" % b)
+        return 0
+    if args.cmd == "read":
+        return cmd_read(args.root)
+    if args.cmd == "orient":
+        return cmd_orient(args.root, args.min_band)
+    if args.cmd == "promote":
+        return cmd_promote(args.root, args.key, args.statement, args.kind,
+                           args.slug, args.evidence, args.date)
+    if args.cmd == "contradict":
+        return cmd_contradict(args.root, args.key, args.slug, args.evidence, args.date,
+                              args.drift_file)
+    p.print_usage(sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))