devrites 2.2.0 → 2.3.0

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

@@ -22,7 +22,8 @@ lifecycle (`/rite-temper` → `/rite-define` → `/rite-build` …) takes over.
 
 ## Rules consulted (read on demand from `.claude/rules/`)
 **Step 0:** Read `.claude/rules/core.md` first. Pull `documentation.md` when recording
-the adoption decisions (why-not-what) in `decisions.md`.
+the adoption decisions (why-not-what) in `decisions.md`; pull `principles.md` when the code
+upholds invariants worth proposing as project principles (step 4a).
 
 ## Operating rules (DevRites core)
 - No silent assumptions · prefer the project's existing conventions (you are *documenting*
@@ -61,6 +62,16 @@ the adoption decisions (why-not-what) in `decisions.md`.
    evidence-gated promotion: the seeds start at the base band and are provenance-tagged as
    onboarding observations, not sealed-slice proofs, so real slices later corroborate or
    (fresh-wins) contradict them.
+4a. **Propose candidate principles** (human-ratified; optional). Where the investigation found an
+   invariant the code *consistently and deliberately* upholds — money always in integer cents, PII
+   always redacted from logs, every v1 endpoint preserved — surface it as a **candidate
+   principle**, not a seeded convention. Principles are prescriptive and gating, so they are
+   **ratified by the human, never auto-seeded** the way conventions are: present the candidates via
+   `AskUserQuestion` with the evidence (where the code upholds it), and write the ones the human
+   ratifies to `.devrites/principles.md` with a dated Governance entry
+   ([`principles.md`](../../rules/principles.md)). Propose, don't impose — an unratified candidate
+   stays a convention, not a gate. Skip cleanly when nothing rises to an invariant (common — a
+   fresh adopt may declare zero principles, and that's valid).
 5. **Hand off.** The project is now in the lifecycle with a spec and a head-start ledger.
    Point the user at `/rite-temper` (big/risky) or `/rite-define` (straightforward) — do not
    plan or build here.
@@ -78,6 +89,7 @@ Adopted: <slug>
 Baseline: <one-line summary of current behavior>   Placement: <where it lives>
 Next objective: <what we'll build on top>
 Conventions seeded: <n> (commands · idioms · placement · gotchas)
+Principles proposed: <n ratified → .devrites/principles.md | none rose to an invariant>
 Next: big / risky? → /rite-temper   ·   straightforward? → /rite-define
 ↻ Hygiene: /clear before the next phase (spec.md + decisions.md + the seeded ledger captured). See rules/context-hygiene.md.
 ```

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

@@ -22,7 +22,9 @@ blocking / escalating gates, and any NO-GO still pause.
 - **Safety gates are not bypassable.** AFK never auto-passes destructive migration /
   auth-authz change / public-API break / external-contract change / red tests; blocking
   and escalating gates and any open `gate: validating` always pause. `--ship` auto-confirms
-  the **final** type-GO only — nothing else.
+  the **final** type-GO only — nothing else. A change that violates a declared project
+  principle (`.devrites/principles.md`) with no recorded exception pauses too — autocomplete
+  never grants a principle exception on its own (`principles.md`: that's a human decision).
 - **Loop budget = the plan's own slice count, not a fixed number.** After `/rite-vet`
   (not `/rite-define` — vet may split or add slices, so the count isn't final until then),
   set the AFK budget to however many slices the plan has, so the loop builds exactly the

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

@@ -24,6 +24,7 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
 - `error-handling.md` — fail fast, no silent catches, fail closed.
 - `testing.md` — pyramid, behaviour over implementation, see-it-fail-first.
 - `patterns.md` — composition over inheritance, avoid premature abstraction.
+- `principles.md` — the project invariants (`.devrites/principles.md`) the slice must honor; the wright reads them as **binding**, not priors.
 - `security.md` — when the slice touches user input, auth, data, or external integrations.
 
 ## Operating rules
@@ -40,11 +41,23 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
   The **prose you write yourself** — `evidence.md`, `decisions.md`, the slice report — follows
   the human-voice charter (`.claude/rules/prose-style.md`; depth in `devrites-prose-craft`): no
   filler openers, no marketing adjectives, exact commands and identifiers kept verbatim.
+- **Honor declared project principles.** The wright reads `.devrites/principles.md` and treats
+  each invariant as **binding** (not a prior to weigh like a convention) — a slice it cannot build
+  without breaking one is an **Escalation**, not a silent violation. On return **you verify no
+  principle was broken**; a fresh violation is handled like any irreversible-risk item — a
+  human-approved, scoped exception in the register or a stop, never folded into the slice. No
+  `.devrites/principles.md` → none declared → nothing to honor.
 - **You never edit source — the wright is the only writer of code + tests.** You write only
   `.devrites/` bookkeeping. On any red gate, doubt finding, or coverage gap your only remedies
   are **continue the same wright once** (it fixes in its own context) or **stop + escalate** —
   never patch the code yourself. The `reconcile.sh` gate (step 6) enforces this by exit code:
   any source file changed outside the wright's claimed set is a hard STOP.
+- **A `Forge: yes` slice competes candidates — one author still lands.** When `/rite-vet`
+  flagged the slice a genuine architecture fork, step 3 runs K=2–3 candidate wrights in
+  **isolated worktrees** and lands exactly one winner's diff; the single-writer invariant holds
+  because no tree ever has two authors and only the winner reaches the working tree. You still
+  never edit source, and reconcile runs against the winner's claimed set. The default slice is
+  single-path — forge is the rare exception ([`reference/forge.md`](reference/forge.md)).
 
 ## Workflow ([one-slice-cycle](reference/one-slice-cycle.md))
 0. **Rules + AFK + readiness check.** Read `.claude/rules/core.md` first. Then **run the
@@ -111,10 +124,25 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
    [ -f "$ST" ] || ST=pack/.claude/skills/devrites-lib/scripts/stuck.sh
    [ -f "$ST" ] && bash "$ST" log "$(cat .devrites/ACTIVE 2>/dev/null)" dispatch "<slice id>" || true
    ```
+   **Forge branch — only if the selected slice is `Forge: yes`.** Instead of the single dispatch
+   below, run the competitive build per [`reference/forge.md`](reference/forge.md): K=2–3 candidate
+   wrights, each in an **isolated git worktree** on the distinct strategy `/rite-vet` named, then a
+   fresh-context [`devrites-forge-judge`](../../agents/devrites-forge-judge.md) scores them against
+   acceptance + `test-plan.md` + `.devrites/principles.md` + the anti-slop charter, and you land
+   exactly **one** winner's diff in the working tree, graft any cheap runner-up improvement by
+   continuing the winning wright once, and write `forge-report.md`. Forge returns the **same shape**
+   a single wright does (one structured artifact, for the winner), so steps 4–7 (doubt, fail-on-red,
+   reconcile against the winner's claimed set, record, stop) run **unchanged**. If you cannot give
+   the judge an objective scorecard (the slice lacks acceptance / `test-plan.md` coverage) or cannot
+   name two genuinely different strategies, the flag is stale — clear it and build single-path. The
+   single-writer invariant is intact: each candidate owns its own tree, exactly one author's diff
+   lands. Then **stop** here for this slice; the steps below are the default single-path dispatch.
+
    Then assemble the slice contract and send it per
    [`reference/wright-dispatch.md`](reference/wright-dispatch.md): the slice goal, acceptance
    criteria, and **scope boundary**; the paths it may touch (`touched-files.md`); the context
-   paths to read (`spec.md`, `plan.md`, `decisions.md`, `assumptions.md`, plus `test-plan.md`
+   paths to read (`spec.md`, `plan.md`, `decisions.md`, `assumptions.md`, `.devrites/principles.md`
+   when present — the binding invariants the slice must honor — plus `test-plan.md`
    when present — its per-gap test requirements + regression-criticals for this slice are the
    coverage the wright must write — and `design-brief.md`
    when the slice touches UI per [frontend-trigger](reference/frontend-trigger.md)); and the
@@ -146,6 +174,10 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
    blocking protocol violation — pause and re-dispatch with the item flagged out-of-bounds, do
    **not** doubt-and-accept it. (The wright's return is the not-yet-load-bearing moment — the
    slice isn't `built` or merged yet — so this post-return doubt is still pre-commit.)
+   **Principle check (same standing):** a wright return that breaks a declared principle
+   (reported in its `Principles` field, or that you detect against `.devrites/principles.md`) is
+   handled here like an irreversible-risk item — block, route to a human-approved scoped
+   exception in the register or stop; never doubt-and-accept a principle violation into the slice.
 5. **Fail-on-red.** If the wright's `Gates` were red (targeted tests / types / lint) or it
    couldn't verify: do **not** mark the slice `built`, and **do not fix the code yourself**.
    First remedy — **continue the same wright once** (`SendMessage` to it, carrying the failing
@@ -258,4 +290,7 @@ Next  ▸ /rite-prove  (prove the completed feature)
 Keep fact lines terse — one `key value` per fact, `·` between, no prose. The meter, the
 `✅ ALL BUILT` marker, and the ribbon carry the progress; don't restate them in words.
 
+For a **forged slice**, the `Built` line names the competition and points at the record, e.g.
+`Built  slice 3 — csv-streaming   (forged: 3 candidates → winner B; forge-report.md)`.
+
 **DO NOT continue to the next slice automatically** — even at `✅ ALL BUILT`, `/rite-prove` is the user's call.

package/pack/.claude/skills/rite-build/reference/anti-patterns.md

@@ -15,6 +15,16 @@ generic AI naming, drive-by refactors): see
 | "Slices 1 and 2 are related; let me do both." | One slice, then stop. Full stop. The user asks for the next. |
 | "It's faster to skip `devrites-doubt` for this small change." | Doubt is cheapest *before* the decision is standing. After is debugging. |
 
+## Forge ([forge.md](forge.md))
+
+| Excuse | Rebuttal |
+|---|---|
+| "This slice is hard — I'll forge it." | Hard ≠ forkable. Forge competes ≥2 *genuinely-different* approaches with no clear winner. One hard approach is single-path; building it K times wastes K× for one answer. |
+| "I'm not sure which approach is right, so let me compete them and decide." | Forge is for a real fork the plan couldn't settle, not for dodging a decision you can make now. Decide from the code/docs first; forge only when the alternatives are genuinely undecidable on paper. |
+| "Candidate A's data layer plus B's UI would be the best of both." | Don't hand-merge candidates — two authors in one tree is the incoherence the single-writer rule exists to prevent. Land one winner whole; graft a *specific* runner-up idea only by continuing the winning wright once. |
+| "The judge already scored these, so I can skip the post-return doubt." | The judge picks *between* candidates; it doesn't replace doubting the winner's standing decisions. Steps 4–7 run on the winner unchanged. |
+| "A fourth candidate might be even better." | K is capped at 3. A fourth rarely moves the winner and multiplies cost; if none of three is right, the plan is wrong — `/rite-plan repair`, don't add candidates. |
+
 ## Red Flags
 
 - About to start slice N+1 without the user asking.
@@ -23,3 +33,5 @@ generic AI naming, drive-by refactors): see
 - Writing a `try/catch` block wider than what you actually handle.
 - A comment that restates what the next line does.
 - Touching files that aren't in `touched-files.md` for "tidiness".
+- Forging a slice with no acceptance / `test-plan.md` coverage for the judge to score against.
+- Landing more than one candidate's code, or keeping a losing worktree/branch around after F7.

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,9 +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
@@ -71,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
@@ -107,6 +124,16 @@ pull these via `Read` when relevant:
    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.
@@ -120,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