devrites 2.1.0 → 2.3.0

package/pack/.claude/skills/rite-build/reference/forge.md

@@ -0,0 +1,171 @@
+# Forge — competing candidate builds for one slice
+
+How `/rite-build` builds a slice that `/rite-vet` flagged `Forge: yes`: instead of one wright,
+**K = 2–3 candidate wrights** each build the slice a genuinely different way in **isolation**, a
+read-only judge scores them, and exactly **one** winner's diff lands in the working tree. Loaded
+on demand by `/rite-build` step 3; the sibling of single-path
+[`wright-dispatch.md`](wright-dispatch.md).
+
+Forge is the **rare** path. Most slices are single-path (cheaper, and the default). A slice
+forges only when the work is a genuine architecture fork — two or three approaches that actually
+differ, no clear winner on paper, at high enough stakes that building the wrong one costs more
+than building all of them. That judgment is made at `/rite-vet` and recorded as the slice's
+`Forge:` field; build acts on the flag, it does not invent it.
+
+## Why this doesn't break the single-writer invariant
+
+DevRites forbids a parallel fan-out of writers **sharing one tree** — concurrent writers on one
+working tree make conflicting implicit decisions and produce incoherent code
+([`wright-dispatch.md`](wright-dispatch.md)). Forge keeps that invariant intact by **isolation**:
+every candidate writes in its own worktree (or its own throwaway branch), never touching another
+candidate's tree, and the orchestrator lands exactly one. No tree ever has two authors; exactly
+one author's work ships. "N isolated complete attempts, winner-takes-all" is not "N writers on
+one slice."
+
+## Trust the flag, but clear a stale one
+
+Before competing anything, confirm the flag still earns its cost — `/rite-vet` set it, but the
+plan may have moved:
+
+- **No objective scorecard** — the slice has no acceptance criteria and no `test-plan.md`
+  coverage the judge can score against → clear `Forge` to `no`, build single-path. A competition
+  with no rubric is a coin toss with K× the cost.
+- **Can't name two genuinely different strategies** — if the candidates would be variations of
+  one approach, there is nothing to compete → single-path.
+- **Slice shrank below the bar** (now Complexity ≤3, or a dependency landed that picks the
+  approach) → single-path.
+
+A cleared flag is recorded in `decisions.md` (one line: why forge was dropped). Never forge a
+slice you can't score, and never forge to avoid making a decision the plan already made.
+
+## Mechanics
+
+The orchestrator runs F1–F7. Steps 4–7 of the [one-slice-cycle](one-slice-cycle.md) (doubt,
+fail-on-red, reconcile, record, stop) then run **unchanged** on the winner.
+
+### F1 — Confirm the K strategies
+Take the 2–3 candidate strategies `/rite-vet` named (in the slice brief). Each must be a
+**distinct, complete approach** to the same slice contract — a different seam, data shape,
+reuse-vs-build call, or algorithm — not a tweak of one. Name them `A`, `B`, (`C`) with a
+one-line description each. K is capped at 3: a fourth candidate rarely changes the winner and
+multiplies cost.
+
+### F2 — Snapshot, then isolate each candidate
+Snapshot the working tree first (the winner's landing is reconciled against it later), then give
+each candidate its own isolated tree. **Prefer parallel isolated worktrees** when the harness can
+dispatch a sub-agent with worktree isolation; the **always-available** path is one throwaway git
+branch per candidate, built sequentially (slower, universally works — the
+[`tooling.md`](../../../rules/tooling.md) "fallback is first-class" discipline):
+
+```bash
+SLUG="$(cat .devrites/ACTIVE 2>/dev/null)"
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo "(not a git repo — forge needs git for isolation; degrade to single-path)"
+BASE="$(git rev-parse --abbrev-ref HEAD)"
+# one isolated worktree per candidate (parallel-capable); falls back to branches if worktrees are unavailable
+for C in A B; do
+  git worktree add ".devrites/work/$SLUG/forge/cand-$C" -b "forge/$SLUG/cand-$C" 2>/dev/null \
+    || git branch "forge/$SLUG/cand-$C" "$BASE"
+done
+```
+
+### F3 — Dispatch K candidate wrights
+Send **each** candidate the identical single-path slice contract from
+[`wright-dispatch.md`](wright-dispatch.md), with **one** line added naming its assigned strategy
+and its isolated tree:
+
+```
+Forge candidate <A|B|C> of <K>. Build this slice using ONLY this approach:
+  Strategy: <the distinct approach, one or two sentences — the seam / data shape / reuse call>
+Work in your isolated tree: <worktree path | branch name>. Do not consult or merge another
+candidate's work. Same discipline as always — orient → RED → implement smallest complete →
+verify → return your structured artifact. Code + tests only.
+```
+
+Each is still **one wright, one tree** — the invariant holds per candidate. Parallel where the
+harness isolates them; otherwise build candidate A to green, capture its diff, reset to `BASE`,
+then candidate B. A candidate that hits an irreversible-risk item escalates exactly as a
+single-path wright does — **forge never bypasses a gate** (see AFK below).
+
+### F4 — Judge (read-only, fresh context)
+Dispatch [`devrites-forge-judge`](../../../agents/devrites-forge-judge.md) with the K finished
+candidate diffs and the scorecard inputs (slice acceptance, `test-plan.md`, `.devrites/principles.md`,
+the anti-slop charter). It scores each candidate, ranks them, names the **winner** and the
+specific runner-up ideas worth grafting, and returns the structured verdict. The judge **never
+writes code** — it reads the diffs and returns findings, like every reviewer agent. If sub-agent
+dispatch is unavailable, do the judge's rubric pass yourself in a fresh read, discarding your
+authoring reasoning (a flagged fallback, not an independent judgment).
+
+### F5 — Land the winner, graft sparingly
+Apply **only** the winner's diff to the working tree (merge its worktree / cherry-pick its
+branch). If the judge named a cheap, specific improvement in a runner-up, graft it by
+**continuing the winning wright once** with that instruction — never hand-merge two candidates'
+code (that re-creates the incoherent-tree failure the invariant exists to prevent). The landed
+tree has exactly one author: the winner (plus its own grafted follow-up).
+
+### F6 — Write `forge-report.md`
+The durable record of the competition (template below). One per forged slice; archived with the
+feature.
+
+### F7 — Clean up, then return to the cycle
+Remove the losing worktrees / delete the candidate branches:
+
+```bash
+SLUG="$(cat .devrites/ACTIVE 2>/dev/null)"
+for C in A B; do
+  git worktree remove ".devrites/work/$SLUG/forge/cand-$C" --force 2>/dev/null || true
+  git branch -D "forge/$SLUG/cand-$C" 2>/dev/null || true
+done
+```
+
+Then hand the **winner's** structured artifact to [one-slice-cycle](one-slice-cycle.md) step 4 as
+if a single wright produced it. Doubt, fail-on-red, reconcile (against the F2 snapshot, claimed =
+the winner's files), record, and stop all run unchanged.
+
+## `forge-report.md` template
+
+```markdown
+# Forge report: <slice id — name>
+Forged on <iso>. Reason: <the architecture fork /rite-vet flagged>.
+
+## Candidates
+| # | Strategy | Gates | Score | Notes |
+|---|---|---|---|---|
+| A | <approach> | green/red | <judge score> | <one line> |
+| B | <approach> | green/red | <judge score> | <one line> |
+
+## Verdict
+Winner: <A|B|C> — <why it won, in the judge's terms: acceptance coverage, simplicity, principle
+fit, anti-slop, reuse>.
+Grafted from runner-up: <specific idea + which candidate | none>.
+Discarded: <the losing approaches + the one-line reason each lost — load-bearing for a later
+slice that might be tempted to retry one>.
+```
+
+The **Discarded** section matters: it is a dead-end record at the slice level, the same role
+`decisions.md` "Dead ends" plays for the feature — a later slice shouldn't re-litigate an
+approach forge already rejected.
+
+## AFK & budget
+
+- **Cost.** Forge multiplies the build by K. Under `.devrites/AFK`, each candidate counts against
+  the slice budget (`tick-afk.sh` once per candidate dispatched), so a forge slice can exhaust the
+  cap faster — that is intended back-pressure, not a bug.
+- **Gates are unchanged.** Forge changes *how many candidates build*, never *what pauses*. An
+  irreversible-risk item, a blocking/escalating gate, or a red-on-completion in **any** candidate
+  pauses per [`afk-hitl.md`](../../../rules/afk-hitl.md) exactly as single-path. AFK widens what is
+  automatic, never what is irreversible — forge included.
+- **Stuck loop still applies.** Re-dispatching the same candidate without progress trips
+  `stuck.sh` the same as a single wright.
+
+## When isolation is impossible
+
+No git, or neither worktrees nor throwaway branches are usable → **degrade to single-path** and
+say so. Forge is an accelerator for choosing between real alternatives; it is never a requirement
+for building the slice. A slice always has a single-path build available — the competition is the
+optional part.
+
+## Anti-patterns
+
+See [`anti-patterns.md`](anti-patterns.md) § Forge — the short version: don't forge a decided or
+trivial slice, don't forge to dodge a decision, don't hand-merge candidates, don't exceed K=3,
+and don't let a forged slice skip the post-return doubt because "the judge already looked."

package/pack/.claude/skills/rite-build/reference/one-slice-cycle.md

@@ -9,6 +9,8 @@ The orchestrator (`/rite-build`) gates and records; the **wright** writes. See
 ```
 SELECT    → orchestrator: restate slice goal + acceptance + scope boundary; HITL gate (pause pre-code)
 (SHAPE)   → orchestrator: if UI and no design-brief.md, shape it (devrites-ux-shape) before dispatch
+(FORGE)   → orchestrator: if slice is Forge: yes, compete K=2–3 isolated candidate wrights →
+            devrites-forge-judge → land one winner → forge-report.md, then continue at DOUBT (forge.md)
 DISPATCH  → hand the slice contract to devrites-slice-wright (fresh context). Inside the wright:
    ORIENT    → load only the files this slice touches; learn the project's idiom; reuse-first
    (RED)     → if behavior change: write the failing test first

package/pack/.claude/skills/rite-build/reference/wright-dispatch.md

@@ -16,8 +16,11 @@ The orchestrator's window is full of spec investigation, planning, prior slices,
 output — the exact "lost-in-the-middle" load that degrades instruction-following and pulls the
 model toward generic code. The wright starts clean and sees only the contract, so it holds the
 slice boundary strictly and writes to the *project's* idiom instead of drifting. Single-threaded
-by design: **one** wright per slice, never a parallel fan-out of writers — concurrent writers
-make conflicting implicit decisions and produce incoherent code.
+by design: **one** wright per slice, never a parallel fan-out of writers *sharing a tree* —
+concurrent writers on one working tree make conflicting implicit decisions and produce incoherent
+code. The one sanctioned exception is a **forge** slice, which competes K candidates in *isolated*
+worktrees and lands exactly one — no tree ever has two authors, so the invariant holds (see
+[Forge](#forge--competing-candidates-the-deliberate-exception)).
 
 ## The contract `/rite-build` sends
 One `Task` call to `devrites-slice-wright` carrying everything the writer needs and nothing it
@@ -91,6 +94,23 @@ set.
    [`evidence-standard.md`](evidence-standard.md). Evidence is the wright's real command output,
    not its say-so. Then tick AFK if `.devrites/AFK` is present (`tick-afk.sh`; exit 3 → STOP).
 
+## Forge — competing candidates (the deliberate exception)
+
+The single-writer rule forbids parallel writers **sharing one tree**. A `Forge: yes` slice
+(flagged by `/rite-vet` as a genuine architecture fork at Complexity ≥4) is the one sanctioned
+fan-out, and it keeps the rule intact by **isolation**: each candidate wright works in its own
+`git worktree`, sees the identical slice contract plus one **distinct strategy**, and never
+touches another candidate's tree. A read-only [`devrites-forge-judge`](../../../agents/devrites-forge-judge.md)
+then scores the finished candidates against acceptance + `test-plan.md` + `.devrites/principles.md`
++ the anti-slop charter, and the orchestrator lands **exactly one** winner's diff in the working
+tree. No tree ever has two authors; exactly one author's work ships. Everything downstream (doubt,
+fail-on-red, reconcile against the winner's claimed set, record) runs on the winner as if a single
+wright had built it.
+
+Full mechanics — strategy derivation, worktree setup, the judge contract, landing + grafting the
+winner, `forge-report.md`, AFK budgeting, and the worktree-unavailable fallback — live in
+[`forge.md`](forge.md).
+
 ## Fallback
 If the `Task` tool / sub-agent dispatch is unavailable, `/rite-build` runs the wright's
 discipline **inline** in its own context and flags it as a fallback (no clean-context benefit).

package/pack/.claude/skills/rite-define/SKILL.md

@@ -17,6 +17,7 @@ nothing gets missed in one batch. **No code here.**
 as their first step; the other rule files load on demand. Pull these via `Read` when shaping
 the plan:
 - `development-workflow.md` — small batches, trunk-always-green, definition of done.
+- `principles.md` — the project invariants (`.devrites/principles.md`) the chosen approach must conform to.
 - `documentation.md` — record plan-time decisions and rationale.
 
 ## Operating rules
@@ -90,6 +91,12 @@ the plan:
    ```
 5. **Complexity & deviations gate** — justify anything off DevRites defaults (new dep,
    extra abstraction, second design system) in the plan; if you can't justify it, simplify.
+   **Principles conformance:** read `.devrites/principles.md` (if present) and confirm the
+   approach honors every declared invariant. A plan that conflicts with one is not "a deviation
+   to justify away" — either reshape the approach to conform, or, when the conflict is genuine and
+   intended, route it through the Spec Drift Guard plus a recorded decision and a scoped principle
+   exception a human approves. Never ready a plan that silently violates an invariant. (Re-scored
+   as a blocking gate at `/rite-vet`; no file → none declared → nothing to check.)
 6. **Write** `plan.md` + `tasks.md`; update `state.md` (phase: plan → next `/rite-build`).
 7. **Readiness gate** (bottom of plan-template): every acceptance criterion covered by a
    slice, dependency order acyclic + risk-first, no unjustified deviation, rollback for
@@ -105,6 +112,9 @@ Goal:
 Satisfies: AC-n[, AC-m]     # reverse traceability — which spec acceptance criteria this slice satisfies
 Acceptance criteria:        # which spec FR/criteria this satisfies
 Complexity: N/5 — <reason>  # 1=trivial … 5=hairy; >3 triggers a reslice unless the reason justifies it
+Forge: no | yes — <reason>  # default no. Propose yes ONLY when Complexity ≥4 AND the slice has ≥2 genuinely-viable
+                            # approaches with no clear winner (an architecture fork, not just "hard"). /rite-vet confirms
+                            # or clears it; /rite-build then competes K isolated candidates and keeps one. See rite-build/reference/forge.md.
 Mode: AFK | HITL            # AFK = implementable + mergeable without human gating;
                             # HITL = needs a human decision mid-slice (design call,
                             # architectural choice, destructive migration sign-off).
@@ -139,7 +149,10 @@ Evidence required:
 > coverage. Keep `Blocked by` cycle-free. `depends_on` is the machine-readable mirror tools read
 > to pick the next *buildable* slice; `Complexity` (>3 → reslice) sizes it; `Satisfies` +
 > `Consumes/Produces` + `Known-Gotchas` + `Validation commands` make each slice a self-contained,
-> one-pass-implementable brief (the PRP target `/rite-vet` checks).
+> one-pass-implementable brief (the PRP target `/rite-vet` checks). `Forge` flags the rare slice
+> worth *competing* — a genuine architecture fork at high complexity, not a slice that is merely
+> hard. Define only proposes it; `/rite-vet` confirms or clears it and `/rite-build` acts on it.
+> The bulk of slices stay `no` (single-path is cheaper and the default).
 
 > **Mid-flight discipline.** When tempted to skip vertical slicing, coverage mapping, or dependency-order discipline — see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
 

package/pack/.claude/skills/rite-frame/SKILL.md

@@ -77,6 +77,9 @@ map + worked examples: [`reference/failure-modes.md`](reference/failure-modes.md
 - [ ] **4 · Unverifiable goal** — is there a command that proves this, run, with output? Or am
       I asserting "it works"? Tautological test that can't fail? → run the FRAME verify command;
       record command + output (`testing.md`, evidence-over-confidence).
+- [ ] **Principle check** — if `.devrites/principles.md` exists, does the change break a declared
+      invariant? A violation with no recorded, human-approved exception is a **Critical** — the
+      express lane is not a way around a project gate; escalate it, don't ship it (`principles.md`).
 
 The test for each changed line: **it traces directly to the criterion, and the criterion can
 be proven false.** A line that fails either is a finding.
@@ -85,8 +88,10 @@ be proven false.** A line that fails either is a finding.
 
 If FRAME can't produce a falsifiable criterion, or AUDIT surfaces a mode-1 / mode-3 issue that
 is actually a hidden design decision (new dependency, data model, second design system, an
-auth/migration/public-API touch) → **STOP and route to `/rite-spec`**. Same drift guard the
-express lane enforces — don't quietly grow an unframed ask into unreviewed work.
+auth/migration/public-API touch), or a **declared-principle violation** with no recorded
+exception → **STOP and route to `/rite-spec`** (a needed exception is a human-approved decision,
+not an inline call). Same drift guard the express lane enforces — don't quietly grow an unframed
+ask into unreviewed work.
 
 ## Rules
 - Self-applied and inline. No subagent, no `.devrites/` workspace required. For an adversarial

package/pack/.claude/skills/rite-learn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-learn
-description: Review the auto-captured learning ledger and promote recurring lessons to project rules — the human-gated half of the cross-feature learning loop. Capture is automatic (`/rite-seal` appends dismissed-finding classes + dead-ends to `.devrites/learnings.md` on every GO; the review skills load it before a fan-out), so the system learns without a command; this skill mines that ledger across features and decides which recurring lessons graduate into a rule (propose, don't impose). Use when the user says "what have we learned", "rite learn", "harvest lessons", "promote our learnings", or after several features ship. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
+description: Review the auto-captured learning ledger and promote recurring lessons to project rules or principles — the human-gated half of the cross-feature learning loop. Capture is automatic (`/rite-seal` appends dismissed-finding classes + dead-ends to `.devrites/learnings.md` on every GO; the review skills load it before a fan-out), so the system learns without a command; this skill mines that ledger across features and decides which recurring lessons graduate into a rule (propose, don't impose). Use when the user says "what have we learned", "rite learn", "harvest lessons", "promote our learnings", or after several features ship. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
 argument-hint: "[--mine | \"<lesson to record>\"]"
 user-invocable: true
 disable-model-invocation: true
@@ -45,6 +45,11 @@ it never edits source or rule files on its own.
    you could swap onto any project says nothing).
 3. **Classify each candidate** into its durable home:
    - **project rule** — a craft/standard that belongs in a `.claude/rules/*` file or `CLAUDE.md`.
+   - **project principle** — a recurring correction that is really a *non-negotiable invariant*
+     (not just an idiom or a craft standard): graduate it to `.devrites/principles.md`
+     ([`principles.md`](../../rules/principles.md)). This is the **trusted, gating** layer — higher
+     stakes than a rule — so `/rite-learn` **drafts** the principle + a dated Governance entry for
+     the human to confirm; it never writes a principle silently.
    - **conventions-ledger entry** — a proven project idiom for `.devrites/conventions.md`.
    - **dismissed-finding class** — a pattern reviewers keep flagging that is *intentional here*;
      recording it stops the recurring false positive (`learnings.md`, loaded pre-fan-out).
@@ -53,9 +58,12 @@ it never edits source or rule files on its own.
    times, the proposed home) via `AskUserQuestion` — the human picks which to promote. Never
    promote a lesson to a rule silently; an unproven "lesson" hardened into a rule is its own slop.
 5. **Record the accepted.** For each the user accepts, append it with `learnings.sh add <slug>
-   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule** or
-   **ledger** promotion, draft the exact edit and let the user confirm it through the normal flow
-   — `/rite-learn` writes the ledger, not the rule files. Then `touch .devrites/.learnings-reviewed`
+   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule**,
+   **principle**, or **ledger** promotion, draft the exact edit and let the user confirm it through
+   the normal flow — `/rite-learn` writes the ledger, not the rule or principle files. A
+   **principle** promotion is the highest-stakes of these: draft the `.devrites/principles.md` entry
+   **plus its dated Governance line**, and let the human confirm before it lands — a principle is a
+   gate, so it is amended deliberately, never auto-written. Then `touch .devrites/.learnings-reviewed`
    so the SessionStart learnings nudge snoozes until new signal accumulates.
 
 ## How the ledger is used
@@ -66,6 +74,11 @@ convention** raises the bar. The ledger is an **untrusted prior** — a fresh ob
 live code always overrides a ledger entry (see `.claude/rules/security.md`). Confidence in a
 recorded lesson never raises its authority.
 
+A **project principle** (`.devrites/principles.md`) is the opposite layer — prescriptive,
+trusted, and **gating**. Promoting a lesson there is a deliberate amendment, not a prior the next
+fan-out can override: a violation becomes a blocking finding, not a suppressed false positive.
+That asymmetry is why principle promotion is human-confirmed and dated, never auto-written.
+
 ## Gotchas
 - Evidence first: a lesson without ≥2 real occurrences is speculation. Cite the features.
 - Don't pad the ledger. Five real lessons that change behaviour beat thirty rubber-stamped rows.

package/pack/.claude/skills/rite-polish/SKILL.md

@@ -49,7 +49,9 @@ don't load both up front.
 4. **If UI scope detected** read [`reference/ui.md`](reference/ui.md), and read
    `design-brief.md` if present (the UX/UI contract `devrites-ux-shape` shaped at spec and
    `devrites-frontend-craft` refined while building) so the polish honors the agreed
-   direction + states. Then run
+   direction + states. **Read the `## Visual Verdict` table in `browser-evidence.md` if present:
+   its `FAIL` and `PARTIAL` rows are the normalize/quality-bar worklist** — fix the root cause of
+   each (a missing state, an off-token CTA, an anti-slop hit), don't decorate around it. Then run
    **Phase 3 (normalize)** → **Phase 4 (UI polish)**. Honor argument modes:
    - `bolder | quieter | distill | harden` — passed to Phase 4 as the
      emphasis dial.

package/pack/.claude/skills/rite-prove/SKILL.md

@@ -36,7 +36,14 @@ the affected criteria/routes to refresh proof before `/rite-seal`.
 **Step 0:** Read `.claude/rules/core.md` first. The other rule files load on demand;
 pull these via `Read` when relevant:
 - `testing.md` — pyramid, determinism, no-flake discipline.
+- `spec-grammar.md` — when the spec uses structured `### Requirement:` / `#### Scenario:`
+  blocks, each scenario (WHEN/THEN) is one observable behavior to walk and prove.
 - `performance.md` — measure first when perf is in scope.
+- `observability.md` — when the change has a runtime surface (endpoint, job, integration,
+  user flow): telemetry must be present **and observed to emit**, not assumed.
+- `developer-experience.md` — when the change ships a developer-facing surface (API / CLI / SDK /
+  webhook / config / error messages / getting-started): **measure** the DX scorecard (run the flow,
+  time time-to-hello-world, capture the verbatim error text), don't assert it.
 
 ## Operating rules
 - Evidence over confidence. Feature scope only — fix within the feature or record a
@@ -69,7 +76,19 @@ pull these via `Read` when relevant:
    (`devrites-browser-proof`): routes, viewports, screenshots (opened + described),
    console, network, interaction paths, and design-reference match if references exist.
 5. **Map results to acceptance** — walk `spec.md` acceptance criteria; note which are now
-   proven and which aren't. If `test-plan.md` exists, also walk its acceptance→test map and
+   proven and which aren't. **If the spec uses the structured grammar** (`### Requirement:` /
+   `#### Scenario:` blocks — `spec-grammar.md`), walk it **per scenario**: each `#### Scenario:`
+   WHEN/THEN is one observable behavior that needs a passing asserting test (the WHEN is the
+   arrange, the THEN the assert). A scenario with no covering result is an unproven gap =
+   blocker, the same standing as an uncovered acceptance criterion. Re-run the grammar gate
+   first so a requirement hand-edited to malformed since `/rite-spec` can't masquerade as proven:
+   ```bash
+   SV=.claude/skills/devrites-lib/scripts/spec-validate.sh
+   [ -f "$SV" ] || SV="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/spec-validate.sh"
+   [ -f "$SV" ] || SV=pack/.claude/skills/devrites-lib/scripts/spec-validate.sh
+   [ -f "$SV" ] && { bash "$SV" ".devrites/work/<slug>"; echo "spec-validate rc=$?"; } || true
+   ```
+   If `test-plan.md` exists, also walk its acceptance→test map and
    per-gap requirements — a planned test (especially a regression-Critical) with no covering
    result is an unproven gap, not a pass. **Also walk the test-plan interaction inventory**
    (every interactive element + user flow): each must have a passing asserting test. An
@@ -97,6 +116,24 @@ pull these via `Read` when relevant:
    example tests miss the edge cases these explore. If the same unit regenerated from a paraphrased
    spec (or a second sample) **diverges in behaviour on shared inputs**, treat that as a low-confidence
    signal: under AFK it blocks an auto-GO and routes to HITL.
+5b. **Observability check (runtime surface only).** If the feature added an endpoint, job,
+   queue consumer, external integration, user-facing flow, or a new error path, apply the
+   on-call test (`observability.md`): are the signals needed to debug a prod failure present —
+   structured logs on the failure path, a metric/counter on errors, a trace id across any
+   boundary? Then **observe them fire**: trigger the path and confirm the log line / metric /
+   span actually emits, and record that observation in `evidence.md`. Instrumentation never seen
+   emitting is unproven, not done. Skip entirely for pure-internal / docs / config / type-only
+   changes — don't instrument a typo fix.
+5c. **Developer-experience measure (developer-facing surface only).** If the feature ships a public
+   API, CLI, SDK/library, webhook, config/env contract, error/exit path, or the getting-started flow
+   (`developer-experience.md`), **exercise it** rather than reading it: run the getting-started steps
+   on a clean state and **time time-to-hello-world**; invoke the CLI `--help` / call the endpoint /
+   import the package; trigger the failure path and capture the **verbatim** error text. For a docs or
+   quickstart page, capture it through the browser-proof ladder (`devrites-browser-proof`) and describe
+   the screenshot. Write the **measured** scorecard to `devex.md` (beside the `/rite-vet` prediction the
+   boomerang reconciles at `/rite-seal`) and the headline numbers + error strings to `evidence.md`. A
+   scorecard from "the code looks fine" is Source mode, not proof. Skip entirely when no developer-facing
+   surface is in scope — don't DX-measure an internal refactor.
 6. **On failure** → [failure-triage](reference/failure-triage.md) +
    `devrites-debug-recovery`. Reproduce → isolate → fix within scope → re-run; if a fix
    would exceed scope, record a blocker.
@@ -110,9 +147,11 @@ pull these via `Read` when relevant:
 ```
 Proved: <feature>
 Acceptance criteria proven: <n / total>
+Scenarios proven: <n / total | n/a (flat acceptance)>
 Tests:  <cmd → pass/fail (counts)>
 Build:  <cmd → pass/fail>   Lint: <cmd → pass/fail>
 Browser: <ladder rung used + summary | n/a>
+DevEx:  <measured TTHW + getting-started/error-message verdict → devex.md | n/a (no dev-facing surface)>
 Unresolved failures / blockers: <none | list>
 Next: /rite-polish   (finish the feature → /rite-review → /rite-seal)
 ↻ Hygiene: /clear before /rite-polish (evidence.md + browser-evidence.md captured; debug trails noisy). See rules/context-hygiene.md.

package/pack/.claude/skills/rite-quick/SKILL.md

@@ -23,6 +23,9 @@ express lane:**
 - **Ambiguous scope** — you'd have to guess what "done" means, or the ask hides a design
   decision (data model, new dependency, second design system).
 - Security-sensitive input handling, or a measurable performance-critical path.
+- Would **break a declared project principle** (`.devrites/principles.md`) with no recorded,
+  human-approved exception — the express lane never relaxes a project gate; a needed exception is
+  a deliberate human decision, so route it to `/rite-spec`.
 
 If none hold, the change is small + reversible + unambiguous → proceed. **When in doubt,
 escalate** — the cost of the full lifecycle on a small change is minutes; the cost of the
@@ -34,6 +37,7 @@ Read `.claude/rules/core.md` first. Then the small set this lane actually needs:
 - `testing.md` — TDD, **completeness** (every touched behavior/element asserted) +
   **assertion strength** (no tautological tests; see it fail first), scaled to the change.
 - `error-handling.md` / `security.md` — only if the change touches input/errors.
+- `principles.md` — when `.devrites/principles.md` exists; a change that breaks an invariant is a gate, not a quick fix.
 
 ## Workflow
 0. **Orient.** Read `core.md`. If a `.devrites/` workspace is active, run the preamble to
@@ -53,10 +57,11 @@ Read `.claude/rules/core.md` first. Then the small set this lane actually needs:
 4. **Prove (scoped).** Run the **targeted** tests + typecheck / lint for what changed (not
    the whole suite) → green. Record the command + output. A tautological test that can't
    fail is not proof.
-5. **Review-lite + ship.** Self-review the diff (correctness, scope, idiom — one pass, no
-   subagent fan-out). Show the diff, then on the user's confirm commit it (Conventional
-   Commits, atomic) — or hand to `/rite-ship` if a workspace is active. **Never push without
-   the user asking.**
+5. **Review-lite + ship.** Self-review the diff (correctness, scope, idiom, and — if
+   `.devrites/principles.md` exists — no declared invariant broken; this is `/rite-frame`'s AUDIT
+   pass — one pass, no subagent fan-out). Show the diff, then on the user's confirm commit it
+   (Conventional Commits, atomic) — or hand to `/rite-ship` if a workspace is active. **Never push
+   without the user asking.**
 
 ## Escalation (mid-flight) — the Spec Drift Guard still applies
 If the "small" change turns out to be not small — a second slice appears, a real design

package/pack/.claude/skills/rite-review/SKILL.md

@@ -21,6 +21,7 @@ if none, tell the user to run `/rite-spec <feature>`.
 **Step 0:** Read `.claude/rules/core.md` first. The other rule files load on demand;
 pull these via `Read` when the diff demands them:
 - `code-review.md` — small PRs, severity labels, tests-first review focus.
+- `principles.md` — declared project invariants (`.devrites/principles.md`); a diff that violates one with no recorded exception is a Critical, blocking finding.
 - `testing.md` — confirm the tests prove the spec, not just pass.
 - `agents.md` — when to fan out to which review subagent.
 - `security.md` — when input / auth / data / integrations / secrets are in scope.
@@ -48,7 +49,8 @@ pull these via `Read` when the diff demands them:
    [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
    ```
 1. Read `spec.md`, `tasks.md`, `state.md`, `decisions.md`, `evidence.md`,
-   `touched-files.md`, and the `git diff`. For "what would this change break"
+   `touched-files.md`, `.devrites/principles.md` (if present — the binding invariants to score
+   the diff against), and the `git diff`. For "what would this change break"
    questions, prefer a code-intelligence index if available — codebase-memory-mcp first,
    cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
    `.claude/rules/tooling.md` — over file reads;
@@ -77,7 +79,8 @@ pull these via `Read` when the diff demands them:
        where 20 would do) and the silent-failure bugs (a missing value coerced to 0/''/[],
        a dropped Result/err return, off-by-one / boundary, logic that contradicts the
        comment/docstring/name). Per hunk, check whether working code was deleted that the
-       task did not ask to remove."
+       task did not ask to remove. Score the diff against `.devrites/principles.md` — a change
+       that breaks a declared invariant with no recorded, human-approved exception is a Critical."
    - **Do NOT merge or re-rank** their findings. Present them under separate
      `## Spec` and `## Code review` sub-sections in `review.md`. Surface contradictions
      between the axes explicitly (e.g. "Spec axis says complete, Code-review axis says

package/pack/.claude/skills/rite-review/reference/five-axis-review.md

@@ -20,10 +20,21 @@ is complete, and to scope anything the agent could not (e.g. UI-only lenses belo
 ## 2. Readability
 - Can the next engineer understand it without the author? Naming, function length,
   nesting depth, comments that explain *why* not *what*.
+- Structural smells: a conditional **bolted onto an unrelated flow** (wants its own
+  helper/state/policy — a design smell, not a nit); **repeated conditionals on the same
+  shape** (a missing model or dispatcher).
 
 ## 3. Architecture
 - Right seam/boundary? Coupling and cohesion. Does it fit existing patterns or
   introduce a competing one? Is the abstraction earned (not premature)?
+- Does a refactor **reduce** complexity or just **relocate** it? Count the concepts a
+  reader must hold; a "cleaner" version that leaves that count unchanged isn't cleaner.
+- Is feature-specific logic **leaking into a shared module** instead of its owning layer?
+  Is a **type boundary** left implicit by a gratuitous `any`/cast or a silent fallback?
+- **Name the remedy, not just the smell** — replace a conditional chain with a typed
+  dispatcher, separate orchestration from business logic, move feature logic to its owning
+  package, delete a pass-through wrapper, split a large file. Prefer the move that removes
+  moving pieces over one that re-centralizes the same complexity.
 
 ## 4. Security
 - Trust boundaries, input validation, authz checks, secrets handling. Hand off to
@@ -43,4 +54,7 @@ is complete, and to scope anything the agent could not (e.g. UI-only lenses belo
 
 ## Sizing & speed
 Prefer reviewing roughly one slice / ~100 lines of meaningful change at a time. Larger
-diffs hide defects — recommend splitting rather than rubber-stamping.
+diffs hide defects — recommend splitting rather than rubber-stamping. Watch **file size,
+not just diff size**: a small diff that pushes an already-large file further past a healthy
+boundary wants decomposition (extract helpers / split modules) *first* — decompose, then
+add.

package/pack/.claude/skills/rite-seal/SKILL.md

@@ -17,7 +17,11 @@ live in `/rite-ship`, which refuses to run without a GO recorded here.
 pull these via `Read` before sealing:
 - `agents.md` — review-subagent fan-out at seal.
 - `code-review.md` — severity labels (Critical / Important / Suggestion / Nit / FYI).
+- `principles.md` — declared project invariants (`.devrites/principles.md`) are a pass/fail gate; a diff that violates one with no recorded, human-approved exception is a NO-GO.
 - `documentation.md` — record decisions in `decisions.md` before sealing.
+- `observability.md` — a runtime surface that ships blind is an Important finding.
+- `deprecation.md` — when the diff removes / migrates code, API, or data (read with the
+  risk-and-rollback step below).
 
 ## Operating rules
 - Evidence over confidence — a criterion is met only if evidence proves it.
@@ -34,6 +38,8 @@ Read `review.md` and the latest reviewer outputs.
 | `Critical == 0` and `Important > 0` and acceptance proven and drift resolved | Render interactive prompt: *"`Important > 0` open. Proceed to seal? [y/N]"*. Default **N**. If the user types `y`, GO; otherwise NO-GO with the open Important findings listed as blockers-by-policy. |
 | `Critical > 0` | **NO-GO**, no exceptions. List every Critical with `file:line` and fix direction. |
 | Any acceptance criterion unproven | **NO-GO**, list the unproven criteria. |
+| Visual Verdict `FAIL` on an acceptance-mapped UI criterion (`browser-evidence.md`) | **NO-GO** — an unmet acceptance criterion. A declared-state `FAIL` is Important (the `Important > 0` row). UI build with a `design-brief.md` but no Visual Verdict → Important evidence gap. No brief → not applicable. |
+| Diff violates a declared project principle (`.devrites/principles.md`) with no recorded, human-approved exception | **NO-GO**, list each violated principle with `file:line`. Same standing as an unproven criterion (absent / empty file → none declared → not a blocker). |
 | Unresolved drift in `drift.md` | **NO-GO**, route through `/rite-plan` first. |
 | Any `questions.md` entry with `gate: validating` and `status: open` | **NO-GO** regardless of behavior impact — an open validating gate is merge-blocking by definition. A slice marked `built (pending review)` is not done. |
 
@@ -50,7 +56,7 @@ Read `review.md` and the latest reviewer outputs.
    Then read all artifacts: `brief.md`, `spec.md`, `plan.md`, `tasks.md`, `state.md`,
    `decisions.md`, `assumptions.md`, `questions.md`, `drift.md`, `evidence.md`,
    `browser-evidence.md`, `polish-report.md`, `review.md`, `design-brief.md` (if UI),
-   `strategy.md` (if present), and the **final diff**. If a code-intelligence index is available
+   `devex.md` (if a developer-facing surface), `strategy.md` (if present), and the **final diff**. If a code-intelligence index is available
    (codebase-memory-mcp first, cross-checked with codegraph + graphify, else standard methods LSP / Read/Grep/Glob — see `.claude/rules/tooling.md`), use it for
    blast-radius checks on the final diff in step 5; context7 if available can confirm a current
    external-API signature a reviewer flags.
@@ -60,7 +66,11 @@ Read `review.md` and the latest reviewer outputs.
    proof; the `devrites-spec-reviewer` + `devrites-test-analyst` fan-out in step 7 is the
    independent cross-check (a verifier that never saw the optimistic narrative).
 3. Verify tests, build/typecheck/lint, and browser proof are present and green for the
-   scope. Re-run if cheap and in doubt.
+   scope. Re-run if cheap and in doubt. **For a UI feature with a `design-brief.md`**, read the
+   `## Visual Verdict` table in `browser-evidence.md`: a `FAIL` on an **acceptance-mapped**
+   criterion is an unmet acceptance criterion (NO-GO, per the severity gate), a declared-state
+   `FAIL` is **Important**, and a UI build whose brief exists but whose verdict is **absent** is an
+   Important evidence gap (the scorecard should have been emitted at browser-proof).
 4. Check unresolved **questions** and **drift** — any open item that changes product
    behavior blocks. **Any `questions.md` entry with `gate: validating` and `status: open`
    is a NO-GO regardless of behavior impact** (an open validating gate is merge-blocking by
@@ -70,6 +80,23 @@ Read `review.md` and the latest reviewer outputs.
    `/rite-temper`), confirm its **top pre-mortem risks are mitigated** in the diff/evidence and
    that no **Non-goal / deferred item crept into the diff** (scope creep) — either is a finding
    (an unmitigated top risk or smuggled-in out-of-scope work).
+   - **Principles** (`principles.md`): score the final diff against each declared invariant in
+     `.devrites/principles.md`. A violation with no matching, human-approved exception in the
+     register is a **Critical** finding and a NO-GO; an exception that is stale (past its review
+     trigger) or wider than its stated scope is itself a finding. No file / no principles → skip.
+   - **Observability** (`observability.md`): if the diff added a runtime surface (endpoint,
+     job, integration, user flow, error path), a feature shipping with no way to debug it in
+     prod is an **Important** finding, not a pass — `evidence.md` should show telemetry observed
+     to emit (`/rite-prove` step 5b).
+   - **Developer experience** (`developer-experience.md`): if the diff ships a developer-facing
+     surface, reconcile `devex.md` (the `/rite-vet` predicted scorecard vs the `/rite-prove`
+     measured one — the boomerang). A broken public dev contract (a documented command that errors,
+     a getting-started flow that can't complete) or an unexplained measured DX regression is
+     **Important** — **Critical** on a frozen public surface (`principles.md`). No surface → skip.
+   - **Removal / migration** (`deprecation.md`): if the diff deletes or migrates code, an API,
+     or data, confirm it followed expand→contract, proved the old path unused before removing it,
+     and carries a rollback for every destructive step. A surprise deletion or a one-shot
+     breaking migration is a finding (and trips the irreversible-risk gate, `afk-hitl.md`).
 6. Check **frontend polish** if UI is involved (states, a11y, responsive, design-system,
    browser evidence).
 7. **Independent review** — seal is the final gate, not a re-run of `/rite-review`.
@@ -87,8 +114,10 @@ Read `review.md` and the latest reviewer outputs.
    `devrites-spec-reviewer` (does the diff implement
    the spec?), `devrites-test-analyst` (do the tests prove acceptance?),
    `devrites-code-reviewer`, `devrites-frontend-reviewer` (UI features),
-   `devrites-security-auditor` (input/auth/data/integrations), and
-   `devrites-performance-reviewer` (perf-relevant). Give each the workspace
+   `devrites-security-auditor` (input/auth/data/integrations),
+   `devrites-performance-reviewer` (perf-relevant), and `devrites-devex-reviewer`
+   (developer-facing surface — measure mode: grade the measured DX scorecard and reconcile
+   the boomerang against the `/rite-vet` prediction). Give each the workspace
    path + diff *without the author's reasoning*. If subagents are unavailable,
    run the equivalent reviews sequentially yourself.
    The reviewer **AGENTS** here (fresh context, no author reasoning) are the seal