devrites 2.6.1 → 3.0.0

package/pack/generated/codex/skills/rite-build/reference/afk-discipline.md

@@ -0,0 +1,145 @@
+# AFK discipline — running `$rite-build` unattended without burning the trunk
+
+AFK mode is `.devrites/AFK` present. It lets `$rite-build` chain slices without per-slice
+user input. The discipline below is what keeps an AFK loop from drifting into damage.
+
+The core principles are borrowed from established autonomous-coding loops (Ralph Wiggum,
+Claude Code auto mode):
+
+1. **Feedback loops are the trust substrate.** No green tests / types / lint → no
+   "built" status. The loop can't declare victory if the lights are red.
+2. **Always cap iterations.** Stochastic systems + infinite loops = unsafe. `max_slices`
+   is the hard counter.
+3. **Promote pre-action gates, demote post-action gates.** Code that lands without a
+   gate is a finding; gates after the fact are review queues.
+4. **AFK widens what's automatic, never what's irreversible.** Destructive work, auth
+   boundaries, public API breaks always pause regardless of the sentinel.
+
+## The sentinel file
+
+`.devrites/AFK` (presence = AFK). Optional YAML body:
+
+```yaml
+max_slices: 10                       # read-only INITIAL budget; seeds state.md on first AFK build
+notify: "ntfy.sh/my-topic"           # shell command run on awaiting_human transition
+allow_gates: [advisory, validating]  # gate severities AFK may auto-handle
+```
+
+`.devrites/AFK` is **read-only config** — never rewritten in place. `max_slices` is the
+initial budget; the mutable remaining count lives in `state.md` as `AFK slices remaining:
+<n>`, seeded from `max_slices` on the first AFK build and decremented by `devrites-engine tick-afk`
+(see "Iteration cap").
+
+Defaults when keys are omitted:
+- `max_slices`: unlimited (a missing cap is risky — see "Always cap iterations").
+- `notify`: none.
+- `allow_gates`: `[advisory]`.
+
+To disable AFK temporarily, delete the file. The next `$rite-build` boots straight back
+into HITL.
+
+## Iteration cap
+
+`$rite-build`'s **record step** (workflow step 6) decrements `state.md`'s `AFK slices
+remaining` by 1 each time a slice is marked `built`, by running
+`devrites-engine tick-afk <state.md path>`. The script reads the
+field, decrements, writes it back, prints the new value, and **exits `3` when it hits 0**.
+The cap is enforced by `devrites-engine tick-afk`, not by prose — when it exits 3:
+
+- `$rite-build` treats exit 3 as a forced HITL stop:
+  ```
+  AFK cap reached. Raise `state.md` `AFK slices remaining` or remove the sentinel to continue.
+  ```
+- The workspace stays consistent — no half-built slice, no pending question.
+
+Step 0 re-derives the remaining budget from `state.md` (seeding it from `.devrites/AFK`
+`max_slices` on the first AFK build); `max_slices` itself is read-only and never rewritten.
+
+The cap is intentional: a missing or large cap **must be a conscious choice**. Ralph's
+rule: 5-10 iterations for small tasks, 30-50 for larger ones. Don't ship "unlimited" as
+the default for a job you haven't observed running once HITL.
+
+## Fail-on-red
+
+The **fail-on-red step** (workflow step 5) refuses to mark a slice `built` if targeted tests /
+types / lint are red. The reasoning:
+
+- A red signal means either the slice's contract is wrong or the failing code is. Neither
+  is something AFK can resolve.
+- Marking it `built` and letting the AFK loop chain to the next slice burns the trunk —
+  the next slice builds on broken state.
+
+The fail-on-red path:
+
+1. Append a question to `questions.md` with `gate: blocking`, the SLA of the slice, and a
+   crisp `question:` field naming what failed.
+2. Set `state.md` `Status: awaiting_human` and the `Awaiting human` block.
+3. Fire the `notify:` hook if defined.
+4. STOP.
+
+The user resolves via `$rite-resolve` after diagnosing or re-planning.
+
+## Irreversible-risk list (always pause)
+
+Regardless of `allow_gates`, AFK invokes the checkpoint protocol when the slice touches
+any of:
+
+- Destructive data migration (drop column, drop table, irreversible backfill).
+- Auth / authz boundary change (new role, changed permission check, new public auth endpoint).
+- Public API break (response shape change, removed endpoint, changed status code semantics).
+- External-service contract change (webhook payload, partner-facing schema).
+- Filesystem destructive operation outside the workspace (`rm -rf` of project paths,
+  rewriting `.gitignore`-listed paths, deleting fixtures).
+- Anything the slice's `Gate: blocking` plus `tasks.md` `Why HITL:` flags as irreversible.
+
+The list is the same one Claude Code auto-mode's transcript classifier protects — adapted
+to DevRites's workspace shape.
+
+## The `notify:` hook contract
+
+The hook is a single shell command run on the `awaiting_human` transition. Environment
+the hook receives:
+
+| Var | Value |
+|---|---|
+| `DEVRITES_QID` | the new qid (e.g. `q-2026-05-28-001`) |
+| `DEVRITES_GATE` | `advisory` / `validating` / `blocking` / `escalating` |
+| `DEVRITES_SLICE` | `<N — name>` |
+| `DEVRITES_SLUG` | active feature slug |
+| `DEVRITES_QUESTION` | the checkpoint text |
+| `DEVRITES_PROPOSED` | the proposed answer |
+
+The hook is best-effort: non-zero exit does **not** roll back the pause. Failures are
+logged to `evidence.md` so the user sees them on return.
+
+Example targets:
+- `curl -d "$DEVRITES_QID: $DEVRITES_QUESTION" ntfy.sh/my-topic`
+- `osascript -e "display notification \"$DEVRITES_QUESTION\" with title \"DevRites: $DEVRITES_GATE\""`
+- `pb push "$DEVRITES_SLUG: $DEVRITES_QUESTION"` (via pushbullet CLI)
+
+DevRites owns no notification logic — the hook is a seam, not a feature.
+
+## When to leave AFK
+
+Drop the sentinel before:
+
+- A novel feature where you have not yet seen `$rite-build` work on this codebase HITL —
+  Ralph's progression: HITL first → refine prompt → AFK once trusted.
+- A risky slice you marked `Mode: HITL` and want to walk through interactively even if
+  the gate is technically `validating`.
+- Any time you'd rather review per-slice than batch-resolve afterwards.
+
+AFK is a **bias toward continuing**, not a vow. Re-enter it whenever the next stretch of
+work is bulk + low-stakes.
+
+## What AFK does NOT do
+
+- It does not bypass `$rite-prove`, `$rite-review`, or `$rite-seal`. Those gates are
+  feature-scoped and always run when their phase runs.
+- It does not skip `$rite-plan repair` on Spec Drift Guard fires.
+- It does not skip `devrites-source-driven` checks. Uncertain framework behavior still
+  triggers the doc lookup.
+- It does not skip `evidence.md` writes. AFK runs that don't record evidence are
+  unproven and get rejected at `$rite-prove` regardless.
+
+The sentinel widens *human pauses*, nothing else.

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

@@ -0,0 +1,37 @@
+# rite-build — anti-patterns
+
+Load this when standing a non-trivial implementation decision, or when the
+agent feels reluctance toward stopping after one slice, applying TDD, or
+calling `devrites-doubt`.
+
+Pack-wide rationalizations + red flags (incl. tests-later, defensive checks,
+generic AI naming, drive-by refactors): see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "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.
+- Skipping `devrites-doubt` on a branching, boundary, data-model, auth, public-API, or migration decision.
+- Adding a dependency or a second design system without recording rationale in `decisions.md`.
+- 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/generated/codex/skills/rite-build/reference/checkpoint-protocol.md

@@ -0,0 +1,149 @@
+# Checkpoint protocol — what `$rite-build` does when a slice is HITL
+
+When `$rite-build` reaches a slice with `Mode: HITL`, it does **not** start writing code. It
+surfaces the checkpoint as a ranked **option set** and resolves it **before** any code lands:
+
+- **Human present (interactive)** — ask inline via `AskUserQuestion` (the option set below).
+  The human picks; record the pick to `questions.md` (`answered`) + `decisions.md`, clear the
+  gate, and **continue building in place** — no STOP, no `$rite-resolve` round-trip.
+- **Human absent / AFK-pausing / notify-only** — persist the checkpoint (`questions.md` open +
+  `state.md` `Awaiting human`), fire the `notify:` hook, and **stop**. Resume later via
+  `$rite-resolve` (or `--batch`).
+
+Either way the pause is **pre-action**, not post-action: code never lands before the gate.
+
+## Render contract
+
+The checkpoint must be rendered in user-facing output **and** persisted to the workspace.
+Both are required — the output is for the human in the room (or the notification target),
+the persisted form is for the next session or the AFK observer.
+
+### User-facing render — the option set
+
+Present the checkpoint as an `AskUserQuestion` with a ranked **option set**
+(`afk-hitl.md` → "Option set"): 2–4 options, **recommended first** + labelled `(Recommended)`,
+each option's description carrying the dimension-tagged rationale + the trade-off it accepts,
+plus the escape hatch. The header names the slice + gate:
+
+```
+Slice <N — name> — HITL (<gate>, SLA <SLA>). <Checkpoint text from tasks.md>
+
+▸ 1. <recommended>  (Recommended)
+     logic: … · infra: … · business: … · architecture: …   (+ security/UX/risk if in scope)
+  2. <alternative> — <rationale + the trade-off it accepts>
+  3. <alternative> — <rationale>
+  4. Something else — I'll describe it
+```
+
+The recommended option (#1) is **required** — a checkpoint without a recommendation is a worse
+interrupt than one with shape; the human reacts to a ranked draft faster than to a blank prompt
+(the "give the human something to approve" rule). The recommendation reflects *this* project
+(its conventions, stack, scale), not a generic default. On an interactive pick, resolve in
+place; when persisting a pause instead, the same set is written to `questions.md` `options:`
+and the resume line is `$rite-resolve <qid> "<answer>"` (or `--drop <qid> "<reason>"`).
+
+### Workspace mutations
+
+In one atomic write (one `state.md` rewrite + one `questions.md` append):
+
+1. **`questions.md` append:**
+
+   ```markdown
+   ## q-<YYYY-MM-DD>-<NNN>
+   status: open
+   slice: <N — name>
+   gate: <gate from tasks.md>
+   question: <Checkpoint text from tasks.md>
+   options: |                        # the ranked set, recommended first (matches the render)
+     1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+     2. <alternative> — <rationale>
+   proposed: <the recommended option restated; matches option 1>
+   raised_at: <iso>
+   ```
+
+2. **`state.md` updates:**
+
+   ```markdown
+   - Status: awaiting_human
+   - Active slice: <N — name>
+   - Slice mode: HITL
+   - Next step: $rite-resolve <qid> "<answer>"
+
+   ## Awaiting human
+   - qid: <q-...-NNN>
+   - gate: <gate>
+   - question: <Checkpoint text>
+   - proposed: <one-paragraph best-guess>
+   - raised_at: <iso>
+   - blocking_slices: [<list, from `Blocked by` lookups>]
+   ```
+
+3. **`notify:` hook (if `.devrites/AFK` defines one):** export all six env vars from the
+   canonical contract in [`afk-discipline.md`](afk-discipline.md) (the `notify:` hook
+   contract table is the source of truth):
+
+   ```bash
+   DEVRITES_QID="$qid" \
+   DEVRITES_GATE="$gate" \
+   DEVRITES_SLICE="$slice_id" \
+   DEVRITES_SLUG="$slug" \
+   DEVRITES_QUESTION="$question" \
+   DEVRITES_PROPOSED="$proposed" \
+   sh -c "$notify_cmd"
+   ```
+
+   The hook fires after the workspace write so the notification target sees a workspace
+   that already records the pause. Failures in the hook **do not** roll back the pause —
+   the gate is authoritative; the notification is best-effort.
+
+## qid generation
+
+Format: `q-YYYY-MM-DD-NNN`, where `NNN` is the next sequential integer for that date in
+`questions.md`. For the write side, call
+`devrites-engine resolve next-qid <questions.md path>` — it
+counts existing `## q-YYYY-MM-DD-` headers for today, prints the next zero-padded id, and
+refuses to print an id whose header already exists. Use that id verbatim so each qid is
+unique within the date.
+
+## When AFK is active
+
+If `.devrites/AFK` exists and the slice's `Gate` is in `allow_gates`, `$rite-build` does
+**not** invoke the checkpoint protocol. Instead:
+
+- For `advisory`: log a `gate: advisory` entry to `questions.md`, record the trade-off in
+  `decisions.md`, and **dispatch the wright** to build the slice (workflow step 3).
+- For `validating` (only when `allow_gates` includes it): **dispatch the wright** (step 3); on
+  return, write a `gate: validating` entry to `questions.md`, mark the slice
+  `built (pending review)` in `state.md`, and continue. A slice's only states are `pending` and `built` —
+  acceptance is proven at the **feature** level by `$rite-prove` (recorded in
+  `evidence.md`), not per slice. The `built (pending review)` slice is not done until the
+  open `validating` gate resolves via `$rite-resolve`; an open `validating` gate is a
+  NO-GO at seal.
+
+For gates in `allow_gates`, AFK **auto-picks the recommended option** (option 1 of the set)
+instead of pausing, recording it as above. For `blocking` and `escalating` (and every
+irreversible-risk item), AFK **always** invokes the checkpoint protocol — the sentinel does
+not unlock these gates — **unless `allow_irreversible: true`** is set, which makes AFK
+auto-pick the recommendation on *every* gate, irreversible included (maximal autonomy, opt-in;
+see `afk-hitl.md`). See `afk-discipline.md` for the irreversible-risk list.
+
+## Multi-question pauses
+
+The current protocol is **one question per pause**. If a slice has multiple HITL
+checkpoints, split it into sub-slices via `$rite-plan reslice` so each pause is
+single-question. Multi-question pauses are reserved future shape; `Awaiting human` is
+written as a single block.
+
+## What NOT to do
+
+- **Don't write code first and pause after.** The pre-action rule is the whole point.
+- **Don't render the checkpoint without persisting.** Output without `state.md` + `questions.md`
+  updates means the workspace lies on `/clear`.
+- **Don't self-answer a question that *paused* for a human.** When a gate stopped the session
+  (an AFK queue, or a HITL pause the human walked away from), `$rite-resolve` requires an
+  explicit answer — the agent doesn't confirm its own `proposed:` on resume. This is distinct
+  from the two legitimate auto-resolutions: an interactive `AskUserQuestion` pick the human
+  just made, and an AFK auto-pick of the recommended option on a gate `allow_gates` permits.
+- **Don't bundle the `notify:` hook output into chat.** Fire-and-forget; the chat already
+  has the user-facing render.
+- **Don't fire `notify:` on `advisory`-downgraded entries.** It's reserved for true pauses.

package/pack/generated/codex/skills/rite-build/reference/checkpoint.md

@@ -0,0 +1,44 @@
+# Checkpoint — crash-survivable WIP commits (opt-in)
+
+`.devrites/` markdown survives compaction, but a slice's *source* stays uncommitted until
+`$rite-ship`. A crash or killed session mid-build — the AFK / `$rite-autocomplete` case —
+loses that source **and** the reasoning behind it. Checkpoint mode commits each proven
+slice as a local `WIP`, so the work and its context outlive the session.
+
+## When it's on
+Opt-in via the `.devrites/CHECKPOINT` sentinel — the mirror of `.devrites/AFK`. Absent →
+no checkpoints; `$rite-build` behaves exactly as before. A long unattended run
+(`$rite-autocomplete`) is the case it earns its keep, so that path sets the sentinel for
+the run. **Local-only by rule:** a checkpoint is never pushed — scratch work must not
+trigger CI.
+
+## The checkpoint commit — orchestrator, at RECORD, after gates are green
+A checkpoint records a **proven** slice; it fires only after PROVE is green, never on a red
+gate. Stage only the slice's `touched-files.md`, then commit locally with a
+`[devrites-context]` body a cold reader can restore from:
+
+```bash
+[ -f .devrites/CHECKPOINT ] || exit 0   # sentinel absent → no-op, silent
+git commit -m "WIP(<slug>): <slice>" -m "$(cat <<'BODY'
+[devrites-context]
+decisions: <one-line delta this slice added to decisions.md>
+remaining: <pending slices — count or names>
+dead-ends: <approaches ruled out this slice, if any>
+BODY
+)"
+```
+
+## Restore
+The commit body is a durable record, not just a marker. After a crash, a fresh session —
+or `$rite-status` — reads the last `WIP(<slug>)` body to reconstruct the decisions,
+remaining slices, and dead-ends that in-session `.devrites/` state would have held. No
+special tooling: it's a git log entry any agent can read.
+
+## Collapse at ship
+WIP commits are scratch and never reach shared history. `$rite-ship` folds them into the
+one atomic feature commit before the Conventional-Commit ladder — see the collapse step in
+[git-ship.md](../../rite-ship/reference/git-ship.md). Result: one clean commit, bisect
+stays green.
+
+## Autocomplete clean-baseline use
+`$rite-autocomplete` may arm checkpoint mode after it verifies a clean or explicitly accepted baseline. Checkpoints are local-only crash recovery, not authorization to continue across red gates or to ship. `$rite-build` remains one-slice-at-a-time; autocomplete is the only opt-in loop that may invoke multiple builds.

package/pack/generated/codex/skills/rite-build/reference/evidence-standard.md

@@ -0,0 +1,35 @@
+# Evidence standard
+
+Evidence beats confidence. A slice isn't built until there's a record that proves it.
+
+## What counts as evidence
+- A **command + its output**: `npm test src/export.test.ts` → `3 passing`.
+- A **build/typecheck/lint** result for touched code.
+- **Runtime observation**: a request/response, a log line, a CLI output.
+- **Browser evidence** for UI (see `devrites-browser-proof`): route, viewport,
+  screenshot path (opened and described), console state, interaction path.
+
+## What does NOT count
+- "It should work" / "this looks right" / "I'm confident".
+- A green test you never saw fail (for new behavior).
+- "No type errors" as proof that a *feature* works (it proves types, not behavior).
+- A screenshot path you didn't open.
+
+## Record format (`evidence.md`)
+```markdown
+# Evidence
+
+## Evidence log
+| Evidence ID | Command / action | Result | Timestamp | Related IDs | Limitation |
+| --- | --- | --- | --- | --- | --- |
+| EVID-001 | <command/action> | <pass/fail + key output line> | <iso if available> | AC-001, SLICE-001 | <what remains unproven, or none> |
+```
+
+## Honesty rules
+- If a test fails, record the failure and the output — don't hide it.
+- If a step was skipped (no browser available, command not found), say so and record
+  the manual verification steps instead.
+- Unproven acceptance criteria stay unchecked. The seal will catch them.
+- Every evidence row uses `EVID-###` and names the related `AC-###` and `SLICE-###`.
+- UI/browser proof goes in `browser-evidence.md`; `evidence.md` links to its `EVID-###`
+  instead of copying screenshot notes.

package/pack/generated/codex/skills/rite-build/reference/forge.md

@@ -0,0 +1,181 @@
+# 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`](../../devrites-lib/reference/standards/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`](.codex/agents/devrites-forge-judge.toml) 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 only clean losing worktrees / delete their candidate branches. If a losing worktree is dirty,
+preserve it and record the path in `forge-report.md`; never `--force` away unlanded work.
+
+```bash
+SLUG="$(cat .devrites/ACTIVE 2>/dev/null)"
+for C in A B; do
+  WT=".devrites/work/$SLUG/forge/cand-$C"
+  if [ -d "$WT/.git" ] || git -C "$WT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if git -C "$WT" diff --quiet && git -C "$WT" diff --cached --quiet; then
+      git worktree remove "$WT" 2>/dev/null || true
+      git branch -D "forge/$SLUG/cand-$C" 2>/dev/null || true
+    else
+      echo "preserved dirty forge worktree: $WT"
+    fi
+  else
+    git branch -D "forge/$SLUG/cand-$C" 2>/dev/null || true
+  fi
+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 (`devrites-engine tick-afk` 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`](../../devrites-lib/reference/standards/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
+  `devrites-engine stuck` 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/generated/codex/skills/rite-build/reference/frontend-trigger.md

@@ -0,0 +1,39 @@
+# Frontend trigger
+
+A slice is **frontend/UI** if it touches or plans to touch any of:
+
+- React / TSX / JSX; Vue, Svelte, Astro, Angular;
+- Rails Slim / Haml / ERB views; any server-rendered template;
+- CSS, SCSS, Tailwind, design tokens, theme files;
+- components, forms, layout, navigation, dashboard, landing/marketing page;
+- UI copy, empty states, error states, onboarding, settings;
+- screenshots, mockups, visual direction;
+- browser behavior, responsive behavior, accessibility, frontend performance.
+
+## When triggered
+- `$rite-spec` applies **`devrites-ux-shape`** (spec step 3a) to write the feature-level
+  **`design-brief.md`** before any code — design direction, key states, interaction model,
+  optional Figma/image visual-direction probe.
+- `$rite-build` applies **`devrites-frontend-craft`**, building **to** that `design-brief.md`
+  (register detection, refine the brief per slice, existing design system, all states,
+  anti-AI-slop) before/while implementing.
+- `$rite-prove` applies **`devrites-browser-proof`** (proof ladder + evidence schema).
+- `$rite-polish` runs the full **normalize + polish** workflow.
+- `$rite-review` and `$rite-seal` include frontend UX / a11y / responsive / design-
+  system checks.
+
+## Fullstack (UI slice that also needs backend)
+If the slice spans both layers, it's both a frontend **and** a backend slice. Define the
+**API/data contract first** (`devrites-api-interface`), build it as one **vertical slice**
+(DB → service → API → UI), apply the engineering rules to the backend and
+`devrites-frontend-craft` to the UI, map each contract error to a real UI state, and
+**prove both layers** (contract tests + browser proof). See
+`devrites-frontend-craft/reference/fullstack.md`.
+
+## When NOT triggered
+Pure backend/data/CLI/infra slices skip craft and browser proof — but still get tests
+and evidence. If unsure whether a slice is "UI enough", treat copy/empty/error states
+and any rendered output as UI.
+
+Mark `Frontend craft required: yes/no` and `Browser proof required: yes/no` on the
+slice in `tasks.md` so the trigger is explicit, not rediscovered each cycle.