devrites 2.1.0 → 2.3.0

package/pack/.claude/rules/spec-grammar.md

@@ -0,0 +1,106 @@
+# Spec grammar — testable requirements, parseable by tooling
+
+Acceptance criteria are the contract the seal checks ([`testing.md`](testing.md),
+[`code-review.md`](code-review.md)). Prose criteria work, but a requirement written as free
+text is graded by a human reading carefully — and an ambiguous one ("handle errors
+gracefully") slips past every gate because nothing can falsify it. This rule adds an
+**optional, recommended structure** that makes a behavioral requirement testable by
+construction and parseable by a deterministic linter, so the spec phase catches a malformed
+requirement before `/rite-define` plans against it.
+
+It is the grammar counterpart to [`testing.md`](testing.md): testing says *prove every
+behavior*; this says *write each behavior so it can be proven*.
+
+## Progressive rigor — when to use the structured form
+
+Match the rigor to the stakes; don't pay grammar ceremony for a one-liner.
+
+- **Simple / routine change** — the flat checklist form is correct and stays. One bullet per
+  criterion, each tagged with an `[ACn]` id:
+  ```markdown
+  ## Acceptance criteria
+  - [ ] [AC1] export returns a CSV with a header row
+  - [ ] [AC2] an empty dataset returns 204, not an empty 200
+  ```
+- **Behavioral / high-risk / cross-boundary requirement** — auth, data model, state machine,
+  public API, money, a migration, anything with non-obvious edge cases — use the structured
+  **Requirement / Scenario** grammar below. The act of writing the WHEN/THEN forces the edge
+  cases into the open at spec time, where they're cheapest to resolve.
+
+A spec mixes both: most criteria stay flat bullets; the two or three that carry real risk get
+the structured treatment. **Absence of structured requirements is never a failure** — the
+validator no-ops on a flat-bullet spec, the same discipline as the principles gate
+([`principles.md`](principles.md)).
+
+## The structured form
+
+```markdown
+### Requirement: Session tokens expire after inactivity
+The system SHALL reject any session token older than 15 minutes of inactivity.
+
+#### Scenario: token past the inactivity window
+- [ ] [AC4] **WHEN** a request presents a token whose last use was > 15m ago
+            **THEN** the request is rejected with 401 and the token is revoked
+
+#### Scenario: token within the window
+- [ ] [AC5] **WHEN** a request presents a token last used < 15m ago
+            **THEN** the request is served and the last-use timestamp advances
+```
+
+The rules the validator enforces (`spec-validate.sh`):
+
+- **`### Requirement: <name>`** — a level-3 heading. Its block MUST carry a **SHALL** or
+  **MUST** statement (in the header or the body) describing the core behavior. Keep the name
+  descriptive and under ~50 characters.
+- **Header identity is the key.** Requirement names are **unique** within a spec — tooling (and
+  any future spec sync) matches a requirement by its header text, so two requirements can't
+  share a name. Renaming a requirement is a remove + add, not an in-place edit, so the change
+  is visible.
+- **`#### Scenario: <name>`** — every requirement owns **at least one**. A requirement with no
+  scenario is an assertion no test can target.
+- **WHEN / THEN** — every scenario states a trigger (**WHEN**) and an observable outcome
+  (**THEN**); chain extra conditions with **AND**. Keywords are uppercase so they parse
+  unambiguously. A scenario missing either half isn't falsifiable.
+
+## Behavior first — WHAT, not HOW
+
+A spec requirement describes observable behavior, not the implementation that delivers it
+(the spec stays technology-agnostic — see `rite-spec/reference/spec-template.md`). "**THEN**
+respond 401" is behavior; "**THEN** call `AuthGuard.reject()`" leaks the design and locks the
+plan before `/rite-define` has chosen it. Name the input, the observable output, and the state
+change — not the function, class, or library. Implementation belongs in `plan.md`, not the
+requirement.
+
+## How it composes (no new gate, no duplication)
+
+- **`[ACn]` ids nest inside scenarios.** Tag each scenario's checkable line with an `[ACn]` id
+  exactly as the flat form does. The same `check-acceptance.sh` grades it against `seal.md` at
+  the end of the lifecycle — this grammar checks the requirement's **shape**, that script
+  checks its **proof**. The two compose; neither replaces the other.
+- **`/rite-prove` and `/rite-review` get concrete hooks.** Each scenario is one behavior to
+  prove and the test analyst's unit of "is this actually covered" — the WHEN/THEN maps
+  straight to an arrange/assert ([`testing.md`](testing.md)).
+- **The spec-quality checklists still apply.** The grammar makes a requirement *parseable*; the
+  `checklists/<domain>.md` "unit tests for English" still score whether it's *complete and
+  measurable* ("is 'prominent' quantified?"). Structure doesn't excuse vagueness inside a THEN.
+
+## The validator — `spec-validate.sh`
+
+Deterministic, zero-token. Run it on the workspace (or a spec path) at the spec readiness gate:
+
+```bash
+bash .claude/skills/devrites-lib/scripts/spec-validate.sh .devrites/work/<slug>
+```
+
+Exit codes: `0` valid (or no structured requirements — nothing to lint), `1` grammar
+violation(s) with `file:line` locations, `2` usage, `5` missing `spec.md`. A non-zero exit is a
+blocking spec-readiness failure: fix the requirement, never soften the check. It runs as part
+of `/rite-spec`'s readiness gate and is safe to re-run any time the spec changes.
+
+## Forward note
+
+The Requirement / Scenario block is deliberately the unit a persistent capability ledger would
+store — so if DevRites later grows a living "what the system currently does" layer, today's
+structured specs sync into it without a reformat. That layer is **not** shipped here; for now
+the grammar earns its place purely as testable, lint-checkable acceptance criteria at the spec
+phase.

package/pack/.claude/skills/devrites-browser-proof/SKILL.md

@@ -9,6 +9,10 @@ user-invocable: false
 Screenshots and runtime observations beat "it should render fine." Use the highest rung
 of the ladder that's available; record which one.
 
+The same ladder captures a **developer-facing docs / getting-started page** for the DX measure step
+(`/rite-prove` 5c, `developer-experience.md`): screenshot the quickstart, confirm the documented
+commands match what actually runs, and note the result in `browser-evidence.md` / `devex.md`.
+
 ## Ladder (top-down)
 1. **browser-harness** — detect `command -v browser-harness`. Connects to the user's
    Chrome over CDP. Pattern: `new_tab(url)` → `wait_for_load()` → `capture_screenshot()`
@@ -45,9 +49,44 @@ a lab value as a field value or vice versa.
 Tooling used · route(s) · viewports (375/768/1280) · screenshot paths **opened and
 described** · console errors/warnings · network failures · interaction path tested ·
 accessibility basics · responsive checks · **CWV capture** (tool + route + each
-source-labeled value, or `pending (manual)` + the command) · **design-reference match** (if
-the spec saved references in `references/`, compare the built UI to them and note
-match/diffs) · limitations.
+source-labeled value, or `pending (manual)` + the command) · **Visual Verdict** (the
+structured design-brief / design-reference scorecard below) · limitations.
+
+## Visual Verdict — structured pass/fail (auto-emit for UI with a design brief)
+The screenshots you already opened and described become a verdict, not a vibe. **Whenever the
+feature is UI and a `design-brief.md` exists** (or the spec saved design refs in `references/`),
+emit a `## Visual Verdict` table to `browser-evidence.md`, scored from the opened screenshots.
+This is the prose "design-reference match" formalized so `/rite-seal` and the
+`devrites-frontend-reviewer` can gate on it instead of re-reading prose. No `design-brief.md` and
+no saved references → no Visual Verdict (greenfield no-op — never block UI for the absence of a
+brief; record the limitation and move on).
+
+One row per **declared `design-brief.md` state** the slice delivers (default / loading / empty /
+error / success / disabled / long-content), plus key **design-reference** diffs and the
+**anti-slop** checks (`rite-polish/reference/anti-ai-slop.md`). Score each from a real screenshot,
+not the markup:
+
+```markdown
+## Visual Verdict — <route / component>   (viewport: 375 / 1280)
+| Criterion (source) | Expected | Observed (screenshot) | Verdict | Severity |
+|---|---|---|---|---|
+| empty state (brief) | welcoming copy + primary action | renders, copy present | PASS | — |
+| error state (brief) | inline recoverable message | no error UI — silent | FAIL | Important |
+| primary CTA (ref)   | brand indigo, 44px target | indigo, 32px target | PARTIAL | Suggestion |
+| anti-slop           | no gradient-on-card cliché | clean | PASS | — |
+
+Overall: PARTIAL — 1 FAIL (error state), 1 PARTIAL (CTA size). Screenshots: <paths>.
+```
+
+- **Verdict per row** — `PASS` (matches), `PARTIAL` (present but off), `FAIL` (missing / wrong /
+  broken). **Severity** scales by who-pays and acceptance mapping: a FAIL on a criterion that maps
+  to a **spec acceptance criterion** is **Critical** (it's an unmet criterion, not a polish nit); a
+  declared-state FAIL is **Important**; a cosmetic drift is **Suggestion**.
+- **Overall line** — `PASS` | `PARTIAL (n)` | `FAIL (n)`. This is what the consumers read: a
+  FAIL on an acceptance-mapped row is a NO-GO at `/rite-seal`, and the FAIL/PARTIAL rows are the
+  `/rite-polish` normalize worklist.
+- **Honesty.** A row scored without an opened screenshot is `pending (manual)` with the command —
+  never a green you didn't observe (the same standing as `pending (manual)` proof below).
 
 ## Hard rules
 - A screenshot **path is not proof** — open it and describe what's visible.

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

@@ -48,6 +48,12 @@ first, then `${CLAUDE_SKILL_DIR}`, then the repo `pack/` source).
 - `scripts/check-acceptance.sh` — executable acceptance gate. Compiles `spec.md`'s
   `[ACn]`-tagged criteria and exits `1` unless every one is checked (proven) in `seal.md`;
   used by `/rite-seal` and by the outcome grader.
+- `scripts/spec-validate.sh` — spec-grammar gate (the spec-side mirror of
+  `check-acceptance.sh`). Lints `spec.md`'s structured `### Requirement:` / `#### Scenario:`
+  blocks (SHALL/MUST present, ≥1 scenario each, every scenario has WHEN + THEN, headers
+  unique). Exits `1` on a grammar violation, `0` when valid **or** when the spec uses the flat
+  `[ACn]`-bullet form (no structured blocks — nothing to lint, never a failure). Used by
+  `/rite-spec`'s readiness gate; see [`rules/spec-grammar.md`](../../rules/spec-grammar.md).
 
 **State mutators — write `state.md` / `questions.md` under one contract:**
 
@@ -70,7 +76,8 @@ PR=.claude/skills/devrites-lib/scripts/progress.sh
 **Unified entrypoint (tool-agnostic):**
 
 - `scripts/devrites.sh` — one CLI dispatching to all of the above (`orient` / `ready` /
-  `evidence-fresh` / `acceptance` / `tick-afk` / `resolve` / `close` / `active` / `list` /
-  `use`), so any agent or human can drive `.devrites/` without the skill prose. The MCP
+  `evidence-fresh` / `acceptance` / `spec-validate` / `tick-afk` / `resolve` / `close` /
+  `active` / `list` / `use`), so any agent or human can drive `.devrites/` without the skill
+  prose. The MCP
   wrapper `mcp/devrites-mcp.mjs` exposes the read/gate ops as MCP tools. See
   [`docs/cli-mcp.md`](../../../../docs/cli-mcp.md).

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

@@ -26,6 +26,9 @@ devrites — drive the .devrites/ workflow from any tool (run at the project roo
   ready [slug]           build-readiness gate    (0 ready · 2 no-plan · 3 awaiting · 4 blocked · 5 none)
   evidence-fresh [slug]  evidence-freshness gate (0 fresh · 3 stale)
   acceptance [slug|dir]  acceptance-criteria gate (0 all proven · 1 gap)
+  spec-validate [slug|dir|file]
+                         spec-grammar gate — lint structured Requirement/Scenario blocks
+                         (0 valid or flat form · 1 grammar violation · 5 no spec.md)
   tick-afk [slug]        decrement the AFK slice budget (3 = exhausted)
   resolve <args...>      answer / --drop / --batch a questions.md entry
   close [slug]           archive the workspace + clear ACTIVE
@@ -51,6 +54,11 @@ case "$cmd" in
     if [ -n "$a" ] && [ -d "$a" ]; then d="$a"
     else s="$(resolve_slug "${a:-}")"; [ -n "$s" ] || { echo "devrites: no active feature" >&2; exit 5; }; d=".devrites/work/$s"; fi
     exec bash "$HERE/check-acceptance.sh" "$d" ;;
+  spec-validate)
+    a="${1:-}"
+    if [ -n "$a" ] && { [ -d "$a" ] || [ -f "$a" ]; }; then t="$a"
+    else s="$(resolve_slug "${a:-}")"; [ -n "$s" ] || { echo "devrites: no active feature" >&2; exit 5; }; t=".devrites/work/$s"; fi
+    exec bash "$HERE/spec-validate.sh" "$t" ;;
   tick-afk)
     s="$(resolve_slug "${1:-}")"; [ -n "$s" ] || { echo "devrites: no active feature" >&2; exit 5; }
     exec bash "$HERE/tick-afk.sh" ".devrites/work/$s/state.md" ;;

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
@@ -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.