devrites 2.2.0 → 2.4.0

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Spec-grammar validator — deterministic, zero-token lint of the structured
+# Requirement/Scenario acceptance grammar (rules/spec-grammar.md) in a spec.md.
+# Turns "are the behavioral requirements well-formed?" into an exit code instead
+# of prose the model walks by hand — the spec-side mirror of check-acceptance.sh
+# (which grades the SAME [ACn] ids against seal.md at the end of the lifecycle).
+#
+# Grammar checked (only when the spec opts into the structured form):
+#   ### Requirement: <name>     — must carry a SHALL/MUST statement (header or body)
+#                               — must own >=1 #### Scenario; header names unique
+#   #### Scenario: <name>       — must carry both a WHEN and a THEN line
+# A spec with ZERO `### Requirement:` headers uses the simple flat-bullet form
+# (- [ ] [AC1] ...) — valid, and this validator no-ops (exit 0). Absence is never
+# a failure, the same discipline as the principles gate. The grammar is opt-in and
+# recommended for behavioral / high-risk requirements (progressive rigor).
+#
+# Usage: spec-validate.sh <workspace-dir | spec.md path>
+# Exit:  0 valid (or no structured requirements — nothing to lint) ·
+#        1 grammar violation(s) · 2 usage · 5 missing spec.md
+#
+# [ACn] compatibility: tag each scenario's checkable line with an [ACn] id so the
+# same criterion is graded at seal by check-acceptance.sh. This validator checks
+# SHAPE, not proof; the two compose, they don't overlap.
+
+set -euo pipefail
+
+arg="${1:-}"
+if [ -z "$arg" ]; then
+  printf 'usage: spec-validate.sh <workspace-dir | spec.md path>\n' >&2
+  exit 2
+fi
+
+if [ -d "$arg" ]; then
+  spec="$arg/spec.md"
+elif [ -f "$arg" ]; then
+  spec="$arg"
+else
+  printf 'spec-validate: no such workspace or file: %s\n' "$arg" >&2
+  exit 2
+fi
+[ -f "$spec" ] || { printf 'spec-validate: no spec.md at %s\n' "$spec" >&2; exit 5; }
+
+# Parse the structured grammar in one awk pass. Emits ERROR:/WARN: finding lines
+# and a trailing "__SUMMARY__ <requirements> <scenarios>" line. BSD/GNU awk safe:
+# tolower() is POSIX; no IGNORECASE, no gensub. Keyword matches are case-sensitive
+# on purpose — the grammar mandates uppercase SHALL / MUST / WHEN / THEN.
+findings="$(awk -v FILE="$spec" '
+  function close_scenario() {
+    if (inScenario) {
+      if (!scenWhen) { print "ERROR:" FILE ": Requirement \"" curReq "\" > Scenario \"" scenName "\" (line " scenLine ") has no WHEN line"; }
+      if (!scenThen) { print "ERROR:" FILE ": Requirement \"" curReq "\" > Scenario \"" scenName "\" (line " scenLine ") has no THEN line"; }
+      inScenario = 0
+    }
+  }
+  function close_requirement() {
+    close_scenario()
+    if (curReq != "") {
+      if (!sawShall) { print "ERROR:" FILE ": Requirement \"" curReq "\" (line " reqLine ") has no SHALL/MUST statement"; }
+      if (scenInReq == 0) {
+        if (looseWhenThen) { print "ERROR:" FILE ": Requirement \"" curReq "\" (line " reqLine ") has WHEN/THEN lines but no \"#### Scenario:\" header — wrap them in a scenario"; }
+        else { print "ERROR:" FILE ": Requirement \"" curReq "\" (line " reqLine ") has no \"#### Scenario:\" block"; }
+      }
+    }
+  }
+  /^[[:space:]]*###[[:space:]]+[Rr]equirement:/ {
+    close_requirement()
+    reqCount++
+    name = $0
+    sub(/^[[:space:]]*###[[:space:]]+[Rr]equirement:[[:space:]]*/, "", name)
+    sub(/[[:space:]]+$/, "", name)
+    curReq = name; reqLine = NR
+    sawShall = ($0 ~ /(^|[^A-Za-z])(SHALL|MUST)([^A-Za-z]|$)/) ? 1 : 0
+    scenInReq = 0; looseWhenThen = 0
+    key = tolower(name)
+    if (key in seen) { print "ERROR:" FILE ": duplicate Requirement header \"" name "\" (lines " seen[key] " and " NR ") — headers must be unique"; }
+    else { seen[key] = NR }
+    next
+  }
+  /^[[:space:]]*####[[:space:]]+[Ss]cenario:/ {
+    close_scenario()
+    if (curReq == "") { print "ERROR:" FILE ": Scenario at line " NR " is not under any \"### Requirement:\""; }
+    sName = $0
+    sub(/^[[:space:]]*####[[:space:]]+[Ss]cenario:[[:space:]]*/, "", sName)
+    sub(/[[:space:]]+$/, "", sName)
+    inScenario = 1; scenCount++; scenInReq++
+    scenName = sName; scenLine = NR; scenWhen = 0; scenThen = 0
+    next
+  }
+  {
+    if (curReq != "") {
+      if ($0 ~ /(^|[^A-Za-z])(SHALL|MUST)([^A-Za-z]|$)/) { sawShall = 1 }
+      hasWhen = ($0 ~ /(^|[^A-Za-z])WHEN([^A-Za-z]|$)/)
+      hasThen = ($0 ~ /(^|[^A-Za-z])THEN([^A-Za-z]|$)/)
+      if (inScenario) {
+        if (hasWhen) { scenWhen = 1 }
+        if (hasThen) { scenThen = 1 }
+      } else if (hasWhen || hasThen) {
+        looseWhenThen = 1
+      }
+    }
+  }
+  END { close_requirement(); print "__SUMMARY__ " reqCount+0 " " scenCount+0 }
+' "$spec")"
+
+summary="$(printf '%s\n' "$findings" | grep '^__SUMMARY__' || true)"
+reqs="$(printf '%s' "$summary" | awk '{print $2+0}')"
+scens="$(printf '%s' "$summary" | awk '{print $3+0}')"
+problems="$(printf '%s\n' "$findings" | grep -E '^(ERROR|WARN):' || true)"
+errs="$(printf '%s\n' "$findings" | grep -c '^ERROR:' || true)"
+
+rel="${spec#"$PWD"/}"
+
+if [ "$reqs" -eq 0 ]; then
+  printf 'spec-validate: %s uses the simple acceptance form (no "### Requirement:" blocks) — nothing to lint\n' "$rel"
+  exit 0
+fi
+
+if [ -n "$problems" ]; then
+  printf '%s\n' "$problems" >&2
+fi
+
+if [ "$errs" -gt 0 ]; then
+  printf 'spec-validate: %s — %d requirement(s) / %d scenario(s); %d grammar error(s) (see rules/spec-grammar.md)\n' \
+    "$rel" "$reqs" "$scens" "$errs" >&2
+  exit 1
+fi
+
+printf 'spec-validate: OK — %s: %d requirement(s) / %d scenario(s) well-formed (SHALL + WHEN/THEN, unique headers)\n' \
+  "$rel" "$reqs" "$scens"
+exit 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
@@ -136,7 +164,21 @@ writes; read them yourself for the doubt/record gates or in the inline fallback:
 4. **Doubt the decisions it stood up.** For each entry in the wright's `Decisions stood`
    (branching, boundary crossing, data model, auth, public API, migration, user-flow change,
    "this is safe/scales") apply `devrites-doubt` **before accepting the slice** — the writer
-   doesn't grade its own decisions. The doubt loop honours `.devrites/AFK` (see its AFK
+   doesn't grade its own decisions. Each `devrites-doubt` invocation **dispatches the
+   `devrites-doubt-reviewer` subagent** (doing the adversarial pass inline is the writer grading
+   itself — the thing this step exists to forbid). **Completion criterion (checkable):** step 4
+   is done only when **every** `Decisions stood` entry carries a recorded `devrites-doubt`
+   verdict — `accept`, or `reject` + the required changes — in `decisions.md` (accepted
+   trade-offs) / `questions.md` (open gates). A `Decisions stood` entry with **no verdict on
+   record** means doubt did not run for it: **do not enter step 5 and do not mark the slice
+   `built`.** Log each dispatch so the seal can prove doubt ran (the footprint already counts a
+   `doubt` kind):
+   ```bash
+   FP=.claude/skills/devrites-lib/scripts/footprint.sh
+   [ -f "$FP" ] || FP="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/footprint.sh"
+   [ -f "$FP" ] || FP=pack/.claude/skills/devrites-lib/scripts/footprint.sh
+   [ -f "$FP" ] && bash "$FP" log <slug> doubt "<decision id>" || true
+   ``` The doubt loop honours `.devrites/AFK` (see its AFK
    exception): findings below the slice's gate ceiling become advisory entries in `questions.md`;
    destructive / auth / public-API concerns always pause regardless. A non-empty `Escalation` in
    the artifact is handled here too: irreversible-risk / blockers → blocking question + set
@@ -146,6 +188,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 +304,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