devrites 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [2.4.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.3.0...v2.4.0) (2026-06-27)
+
+### Added
+
+* **devrites:** enforce the doubt gate from invocation through seal ([0397cca](https://github.com/ViktorsBaikers/DevRites/commit/0397cca2158ed1e798c29122485d4e2b69ea4f80))
+
+## [2.3.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.2.0...v2.3.0) (2026-06-23)
+
+### Added
+
+* **agents:** auto-firing devex-reviewer + retrospector ([425c582](https://github.com/ViktorsBaikers/DevRites/commit/425c582802b5efb18a463a31174420dfb96838fe))
+* **rules:** add project invariants as a trusted gating layer ([e569d7e](https://github.com/ViktorsBaikers/DevRites/commit/e569d7e065d1baf4e974c274d921431cc3c6e26e))
+* **skills:** add spec-grammar validator + scenario hooks ([765430c](https://github.com/ViktorsBaikers/DevRites/commit/765430c3f21bd9f139d9de9ecc4d73e292970505))
+* **skills:** competitive forge builds + structured visual verdict ([c509519](https://github.com/ViktorsBaikers/DevRites/commit/c50951957525a5cbf673ee52d3fa573838092959))
+* **tests:** behavioral evals for gating-skill discipline ([9cfde94](https://github.com/ViktorsBaikers/DevRites/commit/9cfde942cd6fa12d2f08d0cb4f8e3c11354b9355))
+
+### Fixed
+
+* **scripts:** allow forge-report.md as a runtime workspace artifact ([e01bd50](https://github.com/ViktorsBaikers/DevRites/commit/e01bd50dcc2d5767d8abd3a1f527ec762dc83583))
+
+### Documentation
+
+* **skills:** sync skill/agent/rule counts + catalogue with current pack ([57ea677](https://github.com/ViktorsBaikers/DevRites/commit/57ea6771b2040382b80848cd5c866952b46355c9))
+
 ## [2.2.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.1.0...v2.2.0) (2026-06-23)
 
 ### Added

package/README.md

@@ -12,17 +12,24 @@ directory: `spec.md` → (`strategy.md`) → `plan.md` + `tasks.md` → (`eng-re
 files — no chat-context summary required. **Spec Drift Guard** catches the wrong turn
 before it costs you a day. **AFK mode** runs unattended without silently accepting
 destructive migrations, auth changes, or red tests. **`type-GO`** demands a literal
-typed confirmation before any irreversible commit / push / tag.
+typed confirmation before any irreversible commit / push / tag. **Project principles**
+(`.devrites/principles.md`) — the invariants you declare once ("money in integer cents",
+"no PII in logs", "never break the v1 API") — then gate every plan, build, and seal, with a
+recorded-exception escape hatch instead of silent work-arounds.
 
 ```
 .devrites/
   ACTIVE                    # which feature is active
   AFK                       # presence = AFK mode; YAML body sets max_slices / notify / allow_gates
+  principles.md             # project invariants — authored, prescriptive, GATING (the 4th knowledge layer)
+  conventions.md            # learned project idioms — descriptive, an untrusted prior
+  learnings.md              # dismissed-finding classes + dead ends — suppresses recurring false positives
   work/<slug>/
     brief.md  spec.md  references.md  references/        # spec
     strategy.md                                          # temper (optional)
     plan.md  tasks.md                                    # define
     eng-review.md  test-plan.md                          # vet
+    forge-report.md                                      # build (only a Forge: yes slice — competed candidates → winner)
     state.md  questions.md  decisions.md  assumptions.md  drift.md
     touched-files.md  evidence.md  browser-evidence.md  design-brief.md
     polish-report.md  review.md  seal.md  ship.md  handoff.md
@@ -94,7 +101,7 @@ Full diagram set (lifecycle, polish orchestrator, review fan-out, debug loop,
 rules carrier, workspace state, namespace map) →
 [`docs/flow.md`](docs/flow.md).
 
-**Status:** [`v2.2.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.2.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v2.4.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.4.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Contents
 
@@ -102,7 +109,7 @@ rules carrier, workspace state, namespace map) →
 - [Modes — HITL & AFK](#modes--hitl--afk)
 - [Install](#install) — [npx / bash](#installing) · [upgrade](#upgrading-an-existing-install)
 - [Recommended setup](#recommended-setup-optional-but-devrites-is-much-sharper-with-it) — codegraph · graphify · browser-harness
-- [Skills](#skills) — 31 total · full catalogue in [`docs/skills.md`](docs/skills.md)
+- [Skills](#skills) — 36 total · full catalogue in [`docs/skills.md`](docs/skills.md)
 - [Typical workflow](#typical-workflow) · [Worked examples](docs/usage.md)
 - [Engineering rules](#engineering-rules) · [Browser proof ladder](#browser-proof-ladder) · [Frontend & fullstack](#frontend--fullstack)
 - [Safety & scope](#safety--scope) · [Security model](#security-model)
@@ -275,7 +282,7 @@ investigation, cheaper context, and real browser proof. None are required.
 
 ## Skills
 
-The pack ships **31 skills total** — 22 user-invocable `rite-*` workflow + utility skills, 9 model-invoked `devrites-*` specialists. **Prefix convention:** `rite-*` is the user-facing slash-command surface; `devrites-*` is internal (model-invoked, hidden from the menu). Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step, and the other 15 rule files load on demand.
+The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills, 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library (scripts the workflow skills run, not a command). **Prefix convention:** `rite-*` is the user-facing slash-command surface; `devrites-*` is internal (model-invoked, hidden from the menu). Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step, and the other 22 rule files load on demand.
 
 **Two invocation forms.** Every user-invocable skill responds to **both** `/rite <verb>` (menu form — type `/rite` to discover) and `/rite-<verb>` (direct shortcut — muscle memory). The forms are equivalent: `/rite build slice-2` ≡ `/rite-build slice-2`. Use whichever reads more naturally.
 
@@ -297,12 +304,12 @@ Pinned aliases live at `.claude/skills/<alias>/SKILL.md`. The script refuses `ri
 | Group | Skills |
 |---|---|
 | Lifecycle (8) | `rite-spec` · `rite-define` · `rite-build` · `rite-prove` · `rite-polish` · `rite-review` · `rite-seal` · `rite-ship` |
-| On-ramp (optional) | `rite-adopt` — onboard an existing codebase: reverse-derive `spec.md` + seed the conventions ledger, then hand off to the lifecycle |
+| On-ramp (optional) | `rite-adopt` — onboard an existing codebase: reverse-derive `spec.md`, seed the conventions ledger + propose project principles, then hand off to the lifecycle |
 | Strategic (optional) | `rite-temper` — strategic spec review between spec and define; mandatory in `rite-autocomplete` |
 | Engineering (every feature) | `rite-vet` — engineering plan review between define and build; depth scales to stakes, never skipped; always in `rite-autocomplete` |
 | Resume / replan | `rite-resolve` · `rite-plan` |
 | Utility | `rite-status` · `rite-doctor` · `rite-zoom-out` · `rite-prototype` · `rite-handoff` · `rite-pressure-test` · `rite-autocomplete` |
-| Learning (optional) | `rite-learn` — cross-feature learning loop: mine shipped features for recurring mistakes + dismissed-finding classes, propose project-local lessons into `.devrites/learnings.md` |
+| Learning (optional) | `rite-learn` — cross-feature learning loop: mine shipped features for recurring mistakes + dismissed-finding classes, propose project-local lessons into `.devrites/learnings.md`, and promote recurring invariants to `.devrites/principles.md` |
 | Menu | `rite` |
 
 **Internal `devrites-*` specialists (9)** — model-invoked, hidden from menu:
@@ -312,13 +319,19 @@ Pinned aliases live at `.claude/skills/<alias>/SKILL.md`. The script refuses `ri
 `devrites-debug-recovery` · `devrites-api-interface` ·
 `devrites-audit` (axes: `security` · `perf` · `simplify`).
 
-**Review agents (10)** — fresh-context reviewers under `.claude/agents/`:
+**Review agents (12)** — fresh-context reviewers under `.claude/agents/`:
 
 `devrites-strategy-reviewer` (pre-plan, via `/rite-temper`) ·
 `devrites-plan-reviewer` (pre-build, via `/rite-vet`) · `devrites-spec-reviewer` ·
 `devrites-code-reviewer` · `devrites-test-analyst` · `devrites-frontend-reviewer` ·
 `devrites-security-auditor` · `devrites-performance-reviewer` ·
-`devrites-doubt-reviewer` · `devrites-simplifier-reviewer`.
+`devrites-devex-reviewer` (developer-facing surface, predict at `/rite-vet` + measure-the-boomerang at `/rite-seal`) ·
+`devrites-doubt-reviewer` · `devrites-simplifier-reviewer` ·
+`devrites-forge-judge` (build-time, via `/rite-build` — scores competing candidate builds on a `Forge: yes` slice, picks the winner).
+
+**Cross-feature analyst (1)** — fresh-context, read-only, scope is the archive not a diff:
+
+`devrites-retrospector` — dispatched at `/rite-ship` close (cadence-gated) to mine shipped features for recurring patterns + trends and **draft** graduation candidates for `/rite-learn`; proposes, never imposes.
 
 **Executor agent (1)** — fresh-context, **write-capable** writer under `.claude/agents/`:
 
@@ -424,15 +437,15 @@ browser-harness, backend-only, polish modes, zoom-out, mid-flight handoff):
 ## Engineering rules
 
 DevRites ships its own stack-agnostic engineering rules and installs them to
-`.claude/rules/` — 16 rule files plus a README index. They're **common** by design
-(no language assumptions); a project's own conventions always win where they exist.
-Skip them with `--no-rules`. Loading model: each `rite-*` skill Reads
-`.claude/rules/core.md` as its first step; the other 15 rule files load on
-demand via `Read` from the skill body that needs them.
+`.claude/rules/` — 23 rule files plus a README index. They're **common** by design
+(no language assumptions); a project's own conventions always win where they exist, and a
+project's own **principles** (`.devrites/principles.md`) outrank both. Skip them with
+`--no-rules`. Loading model: each `rite-*` skill Reads `.claude/rules/core.md` as its first
+step; the other 22 rule files load on demand via `Read` from the skill body that needs them.
 
 | Always-on | On-demand |
 |---|---|
-| `core.md` | `coding-style.md` · `error-handling.md` · `testing.md` · `code-review.md` · `security.md` · `performance.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `anti-patterns.md` |
+| `core.md` | `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `principles.md` · `security.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `anti-patterns.md` · `tooling.md` |
 
 Full index with phase mapping: [`pack/.claude/rules/README.md`](pack/.claude/rules/README.md);
 diagram: [`docs/flow.md` § Engineering-rules loading](docs/flow.md#6-engineering-rules-carrier).
@@ -486,9 +499,9 @@ devrites/
                        # grade-feature · run-outcome-evals · devrites-detect · check-no-global-writes
                        # sync-version · build-release-tarball
   mcp/                 # devrites-mcp.mjs — MCP stdio server over the devrites CLI
-  pack/.claude/        # skills/  31 skills — 22 public + 9 model-invoked    ─┐
-                       # agents/  10 reviewers + 1 writer (slice-wright)       ├─ the pack
-                       # rules/   16 rule files + README index                 ┘
+  pack/.claude/        # skills/  36 skills — 24 public + 12 internal          ─┐
+                       # agents/  13 read-only + 1 writer (slice-wright)         ├─ the pack
+                       # rules/   23 rule files + README index                   ┘
   evals/               # trigger evals (20/skill) + golden/ outcome-eval fixtures
   docs/                # architecture · skills · command-map · usage · flow · release · cli-mcp
     internal/          # research, development notes (gitignored)

package/docs/architecture.md

@@ -46,22 +46,27 @@ ship.
 4. **Supporting references** — `reference/*.md` inside each skill. Long checklists,
    templates, and anti-rationalization tables loaded on demand (progressive
    disclosure) so `SKILL.md` bodies stay small.
-5. **Agents** — `.claude/agents/devrites-*` fresh-context subagents. Nine **read-only
-   reviewers**: the post-build set used by `/rite-seal` and the doubt loop
-   (`devrites-spec-reviewer`, `-code-reviewer`, `-test-analyst`, `-frontend-reviewer`,
-   `-security-auditor`, `-performance-reviewer`, `-doubt-reviewer`, `-simplifier-reviewer`),
-   plus the **pre-plan** `devrites-strategy-reviewer` used by `/rite-temper`. Plus one
-   **write-capable** executor, `devrites-slice-wright`, dispatched by `/rite-build` to write
-   one slice in a clean context (the write-side mirror of the reviewers).
+5. **Agents** — `.claude/agents/devrites-*` fresh-context subagents: **13 read-only + 1
+   write-capable**. The read-only set is twelve reviewers — the post-build fan-out used by
+   `/rite-seal` and the doubt loop (`devrites-spec-reviewer`, `-code-reviewer`, `-test-analyst`,
+   `-frontend-reviewer`, `-security-auditor`, `-performance-reviewer`, `-devex-reviewer`,
+   `-doubt-reviewer`, `-simplifier-reviewer`), the **pre-plan** `devrites-strategy-reviewer`
+   (`/rite-temper`), the **pre-build** `devrites-plan-reviewer` (`/rite-vet`), and the
+   **build-time** `devrites-forge-judge` (scores competing candidate builds on a `Forge: yes`
+   slice) — plus the cross-feature `devrites-retrospector` (mines the shipped archive at
+   `/rite-ship` close). The one **write-capable** executor, `devrites-slice-wright`, is
+   dispatched by `/rite-build` to write one slice in a clean context (the write-side mirror of
+   the reviewers).
 6. **Engineering rules** — DevRites' own stack-agnostic rules installed to
    `.claude/rules/`. Each `rite-*` skill Reads `core.md` as its first step
-   (step 0); 15 on-demand files load by the phase that needs them:
-   - **Craft:** `coding-style.md` · `patterns.md` · `error-handling.md` ·
-     `testing.md` · `documentation.md`.
-   - **Quality / safety:** `code-review.md` · `security.md` ·
-     `performance.md` · `anti-patterns.md`.
+   (step 0); 22 on-demand files load by the phase that needs them:
+   - **Craft:** `coding-style.md` · `prose-style.md` · `patterns.md` · `error-handling.md` ·
+     `testing.md` · `spec-grammar.md` · `documentation.md`.
+   - **Quality / safety:** `code-review.md` · `principles.md` · `security.md` ·
+     `performance.md` · `observability.md` · `developer-experience.md` · `deprecation.md` ·
+     `anti-patterns.md`.
    - **Workflow / ops:** `development-workflow.md` · `git-workflow.md` ·
-     `hooks.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md`.
+     `hooks.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `tooling.md`.
    - **Index:** `README.md` (phase mapping, loading model).
 
 State lives in `.devrites/` as human-readable Markdown so it survives context
@@ -75,7 +80,7 @@ per-skill catalog with triggers + I/O.
 ### Why a shared orientation preamble (`devrites-lib`)
 Every workspace-operating skill's first move is the same: orient on the active feature —
 slug, phase, artifacts present, run mode, open-question tally — before acting. Re-deriving
-that from raw Markdown in each skill was duplicated (step-0 prose across ~15 skills),
+that from raw Markdown in each skill was duplicated (step-0 prose across ~20 skills),
 token-heavy (counting open gates meant re-reading the append-only `questions.md`, which
 only grows), and error-prone (a missed AFK sentinel or a miscounted gate changes behavior).
 So orientation is computed once by one read-only script, `devrites-lib/scripts/preamble.sh`,
@@ -211,20 +216,21 @@ contract.
 
 ## Design choices at a glance
 
-- **Surface**: 19 public `rite-*` skills (28 total) — the thin `/rite` menu
+- **Surface**: 24 public `rite-*` skills (36 total) — the thin `/rite` menu
   (carries the routing) + 8 lifecycle phases (`rite-spec`, `rite-define`,
   `rite-build`, `rite-prove`, `rite-polish`, `rite-review`, `rite-seal`,
   `rite-ship` — seal **decides**, ship **executes + closes**) + the
   `rite-temper` (strategic, optional) and `rite-vet` (engineering, every plan)
-  reviews +
-  `rite-status` +
-  the `rite-plan` replan verb + the `rite-resolve` resume verb + 5 utilities
-  (`rite-zoom-out`, `rite-prototype`, `rite-handoff`, `rite-pressure-test`,
-  `rite-autocomplete` — the unattended full-lifecycle orchestrator) — plus 9
-  internal model-invoked `devrites-*` specialists, not one mega-command. The
-  `devrites-` prefix is a namespace (collision avoidance), not a
-  public/internal marker — `user-invocable:` is. All `devrites-*` skills are
-  model-invoked.
+  reviews + the `rite-quick` express lane and `rite-frame` pre-flight/self-audit
+  lens + `rite-adopt` (onboard an existing codebase) + `rite-learn` (cross-feature
+  lessons) + `rite-status` + `rite-doctor` (install health) +
+  the `rite-plan` replan verb + the `rite-resolve` resume verb + 4 ideation /
+  handoff utilities (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+  `rite-pressure-test`) + `rite-autocomplete` (the unattended full-lifecycle
+  orchestrator) — plus 11 internal model-invoked `devrites-*` specialists and the
+  `devrites-lib` library, not one mega-command. The `devrites-` prefix is a
+  namespace (collision avoidance), not a public/internal marker —
+  `user-invocable:` is. All `devrites-*` skills are model-invoked.
 - **Selection**: the `/rite` menu skill carries the routing table; every
   workflow skill enforces a "right skill, right time" rule in its body.
 - **State**: durable `.devrites/` Markdown that survives compaction and new sessions.

package/docs/command-map.md

@@ -12,8 +12,9 @@ what it writes, and how the pieces interact.
 `devrites-` is a **namespace prefix** chosen for collision avoidance against
 bundled Claude Code skill names (`prototype`, `handoff`, `triage`, `diagnose`,
 …). It does **not** signal "internal" — visibility is governed by the
-`user-invocable:` flag in each `SKILL.md`. All five public utilities use the
-`rite-*` prefix (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+`user-invocable:` flag in each `SKILL.md`. All public utilities use the
+`rite-*` prefix (`rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`,
+`rite-doctor`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
 `rite-pressure-test`, `rite-autocomplete`); every `devrites-*` skill is
 model-invoked.
 
@@ -35,6 +36,8 @@ model-invoked.
 | [`/rite-ship`](../pack/.claude/skills/rite-ship/SKILL.md) | ship | `[slug]` | Final phase. Requires a GO in `seal.md` → renders type-`GO` + runs the irreversible git ladder (commit → push → tag/PR) + closes the task (archive workspace → `.devrites/archive/<slug>/`, clear `ACTIVE`, phase `done`). Triggers: "ship it", "ship this", "push it out", "close the task". | `seal.md` + all artifacts + diff | `ship.md`, `state.md`, archive |
 | [`/rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N]` | Full unattended lifecycle (spec → … → seal → ship), best option at each soft gate, rationale to `decisions.md`. Vague prompt → up-front interview; pauses on hard-risk / blocking / escalating / open-validating / NO-GO / budget-exhausted. Default stops at the final type-`GO`; `--ship` flag (alias `--yolo`) auto-confirms it. Triggers: "autocomplete", "do the whole thing". | idea + workspace | whole workspace (drives every phase) |
 | [`/rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | (express) | `<change>` | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. **Significance gate first**: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. Triggers: "quick fix", "small change", "tiny tweak", "just do X". | the change + codebase | code + commit (optional `brief.md` / `evidence.md`) |
+| [`/rite-frame`](../pack/.claude/skills/rite-frame/SKILL.md) | lens | `[ask \| diff]` | Pre-flight + self-audit lens for ad-hoc work the lifecycle gates never see — **FRAME** turns an imperative ask into a falsifiable success criterion + verify command before code; **AUDIT** checks a raw diff against the four LLM coding failure modes (silent assumption / overcomplication / out-of-scope edit / unverifiable goal). Top of `/rite-quick` or before a plain "just do X". | the ask / a raw diff | success criterion + verify command (inline) |
+| [`/rite-adopt`](../pack/.claude/skills/rite-adopt/SKILL.md) | onboard | `[path]` | Bring an EXISTING codebase under DevRites — reverse-derive a `spec.md` of current behavior + placement + architecture, seed the conventions ledger from observed idioms, then hand off to the lifecycle. Triggers: "adopt this project", "onboard this codebase", "we already have code". | the codebase | `spec.md`, `.devrites/conventions.md`, `decisions.md`, `state.md` |
 | [`/rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | status | `[slug]` | Active feature: phase, run mode (AFK/HITL), status, next action, evidence, open questions by gate, risks, handoff readiness. Reads via the shared `devrites-lib` preamble (portable). | workspace + `.devrites/AFK` | — |
 | [`/rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | resume | `<qid> "<answer>"` \| `--drop <qid>` \| `--batch <file>` | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and sets `Status: running`. Canonical writer for `status: open → answered`. | `questions.md` + `state.md` | `questions.md`, `state.md` |
 | [`/rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | utility | — | One-pass structural map of an unfamiliar area (modules, in-callers, out-calls, decisions) in project vocabulary. Prefers codegraph/graphify. | codebase + ADRs/CONTEXT.md | — |
@@ -42,6 +45,7 @@ model-invoked.
 | [`/rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | utility | `[next-session-focus]` | Compacts the chat into a handoff doc. Syncs chat-only context into workspace canonical files. References existing artifacts by path. | chat + workspace | `handoff.md` + sync into canonical files |
 | [`/rite-learn`](../pack/.claude/skills/rite-learn/SKILL.md) | utility | `[--mine \| "<lesson>"]` | Mine archived features for recurring mistakes / dismissed-finding classes; propose project-local lessons into `.devrites/learnings.md` (loaded by the review skills before a fan-out). | archive + workspace | `.devrites/learnings.md` |
 | [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3–5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
+| [`/rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | diagnostic | — | Diagnose DevRites install + workspace health — install integrity, stale `.devrites/ACTIVE`, corrupt workspace, orphaned gates, broken hook wiring. Read-only report. Triggers: "rite doctor", "is DevRites healthy", "why isn't the workflow picking up my feature". | install + workspace | — |
 
 ## Internal skills (`user-invocable: false`, model-invoked)
 
@@ -52,7 +56,9 @@ model-invoked.
 | [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | non-trivial decision in build/review | CLAIM → EXTRACT → DOUBT → RECONCILE → STOP | adversarial; ask user if uncertain |
 | [`devrites-ux-shape`](../pack/.claude/skills/devrites-ux-shape/SKILL.md) | UI detected in `/rite-spec` | Plan UX/UI before code → `design-brief.md` (direction, states, interaction, visual-direction probe) | the build target; refs: brief-template/visual-direction-probe |
 | [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | UI detected in build/polish | Build **to** `design-brief.md`: register, refine-per-slice, states, anti-slop | refs: shape/craft/design-references |
-| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | UI in prove/polish | Browser proof ladder + evidence schema | harness preferred |
+| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | a phase writes prose; `/rite-polish` Phase 1 catch | Human-voice writing — strip LLM tells, keep precise lists/terms | refs: banned-phrases, structures, examples |
+| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | UI in prove/polish | Browser proof ladder + evidence schema + the structured **Visual Verdict** table | harness preferred |
+| [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Stop hook (auto) or "reindex" | Keep codebase-memory-mcp / codegraph / graphify current after edits | manual force; no-ops when no index |
 | [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 6-phase: loop → reproduce → hypotheses → instrument → fix → cleanup | references split per phase |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | cross-boundary slice | Stable API/contract design | FE/BE split |
 | [`devrites-audit simplify`](../pack/.claude/skills/devrites-audit/SKILL.md) | `/rite-polish` Phase 1 | Chesterton's Fence, behavior-preserving simplification | dispatches `devrites-simplifier-reviewer` |
@@ -62,21 +68,24 @@ model-invoked.
 
 ## Agents (`.claude/agents/devrites-*`, fresh-context subagents)
 
-Ten **read-only reviewers** plus one **write-capable** executor (`devrites-slice-wright`).
+**13 read-only** (12 reviewers + the cross-feature `devrites-retrospector`) plus one **write-capable** executor (`devrites-slice-wright`).
 
 | Agent | Spawned by | Purpose |
 |---|---|---|
 | [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Write-capable** — turn one slice contract into clean, idiomatic, proven code (orient → TDD → verify, anti-slop); returns a structured artifact, writes no bookkeeping |
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | `/rite-temper` (pre-plan) | Spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention); read-only; **not** part of the seal fan-out |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | `/rite-vet` (pre-build) | Plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate; read-only; **not** part of the seal fan-out |
+| [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | `/rite-build` on a `Forge: yes` slice | Comparative judge of K=2–3 competing candidate builds (acceptance / test strength / principle fit / simplicity / reuse / anti-slop); picks the single winner to land, names grafts; read-only |
 | [`devrites-spec-reviewer`](../pack/.claude/agents/devrites-spec-reviewer.md) | `/rite-review` Spec axis; `/rite-seal` | Does the diff implement the spec? Missing/partial/wrong criteria; scope creep |
 | [`devrites-code-reviewer`](../pack/.claude/agents/devrites-code-reviewer.md) | `/rite-review` Standards axis; `/rite-seal` | Correctness / readability / architecture / maintainability |
 | [`devrites-test-analyst`](../pack/.claude/agents/devrites-test-analyst.md) | `/rite-seal` | Do the tests actually prove the acceptance criteria? |
-| [`devrites-frontend-reviewer`](../pack/.claude/agents/devrites-frontend-reviewer.md) | `/rite-seal` on UI features | UX, a11y, responsive, design-system, anti-AI-slop |
+| [`devrites-frontend-reviewer`](../pack/.claude/agents/devrites-frontend-reviewer.md) | `/rite-seal` on UI features | UX, a11y, responsive, design-system, anti-AI-slop; reads the **Visual Verdict** |
 | [`devrites-security-auditor`](../pack/.claude/agents/devrites-security-auditor.md) | `/rite-seal` when input/auth/data in scope | OWASP Top 10, trust boundary, secrets, deps |
 | [`devrites-performance-reviewer`](../pack/.claude/agents/devrites-performance-reviewer.md) | `/rite-seal` when perf relevant | N+1s, hot paths, payload size |
+| [`devrites-devex-reviewer`](../pack/.claude/agents/devrites-devex-reviewer.md) | `/rite-vet` (predict) + `/rite-seal` (measure) when a developer-facing surface is in scope | Developer-experience scorecard + predict-vs-measure boomerang (TTHW, getting-started, error-message quality, ergonomics, docs) |
 | [`devrites-doubt-reviewer`](../pack/.claude/agents/devrites-doubt-reviewer.md) | `devrites-doubt` loop | Adversarial check of a single claim/decision |
 | [`devrites-simplifier-reviewer`](../pack/.claude/agents/devrites-simplifier-reviewer.md) | `devrites-audit simplify` | Independent simplification judgment |
+| [`devrites-retrospector`](../pack/.claude/agents/devrites-retrospector.md) | `/rite-ship` close (cadence-gated) | Cross-feature retrospective — mines the shipped archive for recurring patterns + trends; **drafts** graduation candidates for `/rite-learn`; read-only |
 
 ## Engineering rules (`pack/.claude/rules/`)
 
@@ -85,7 +94,7 @@ first step (step 0); the rest are referenced on demand. Full index in
 [`pack/.claude/rules/README.md`](../pack/.claude/rules/README.md).
 
 - `core.md` (always-on) — operating rules + universal anti-rationalizations + 1-line craft disciplines + persistence-before-stopping summary.
-- `coding-style.md` · `error-handling.md` · `testing.md` · `code-review.md` · `security.md` · `performance.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md`
+- The other **22 on-demand** (read by the phase that needs them): `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `principles.md` · `security.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md` · `tooling.md`
 - `anti-patterns.md` — pack-wide rationalizations + red flags. Loaded by each per-phase `rite-*/reference/anti-patterns.md`; can be loaded directly for cross-phase reluctance.
 
 ## Trigger conditions (auto-selection)

package/docs/flow.md

@@ -20,6 +20,8 @@ flowchart LR
     Spec -->|spec.md ready| Define[/rite-define/]
     Define -->|plan.md + tasks.md<br/>each slice tagged AFK/HITL| Build[/rite-build/]
     Build -->|one slice done<br/>+ evidence| Build
+    Build -.->|"Forge: yes slice"| Forge[forge: K candidates<br/>→ devrites-forge-judge → 1 winner]
+    Forge -.->|winner lands<br/>forge-report.md| Build
     Build -->|HITL gate fires| Await{{Awaiting human<br/>state.md + questions.md}}
     Await -->|"/rite-resolve &lt;qid&gt; &lt;answer&gt;"| Build
     Build -->|all slices built| Prove[/rite-prove/]
@@ -45,7 +47,7 @@ flowchart LR
     class Shipped done
     class Repair repair
     class Await gate
-    class Shape internal
+    class Shape,Forge internal
 ```
 
 ## 2. `/rite-polish` orchestrator
@@ -117,6 +119,8 @@ flowchart TB
     Walk -.->|UI only| FERev[devrites-frontend-reviewer]
     Walk -.->|input/auth/data| SecRev[devrites-security-auditor]
     Walk -.->|perf relevant| PerfRev[devrites-performance-reviewer]
+    VV[/browser-evidence.md<br/>Visual Verdict/] -.->|UI + design-brief.md| FERev
+    VV -.->|acceptance-mapped FAIL = NO-GO| Gate
     SpecRev --> Gate
     CodeRev --> Gate
     TestRev --> Gate
@@ -141,6 +145,8 @@ flowchart TB
     class Gate,YN gate
     class Go,Ship ship
     class NoGo stop
+    classDef artifact fill:#0f172a,stroke:#9ca3af,color:#f9fafb
+    class VV artifact
 ```
 
 ## 5. `devrites-debug-recovery` six-phase loop
@@ -286,7 +292,7 @@ skills (`prototype`, `handoff`, `triage`, `diagnose`). Visibility is the
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true) — 19 skills"]
+    subgraph Public["Public (user-invocable: true) — 24 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
@@ -303,12 +309,17 @@ flowchart TB
         R13[/rite-autocomplete/]
         R10[/rite-status/]
         R11[/rite-resolve/]
+        RQ[/rite-quick/]
+        RF[/rite-frame/]
+        RA[/rite-adopt/]
+        RL[/rite-learn/]
+        RD[/rite-doctor/]
         IPT[/rite-pressure-test/]
         D1[/rite-zoom-out/]
         D2[/rite-prototype/]
         D3[/rite-handoff/]
     end
-    subgraph Internal["Internal (user-invocable: false) — 9 skills, model-invoked"]
+    subgraph Internal["Internal (user-invocable: false) — 12 skills (11 specialists + devrites-lib library)"]
         direction TB
         I1[devrites-api-interface]
         I2[devrites-audit<br/>security · perf · simplify]
@@ -319,12 +330,15 @@ flowchart TB
         I7[devrites-interview]
         I8[devrites-source-driven]
         I9[devrites-ux-shape]
+        I10[devrites-prose-craft]
+        I11[devrites-refresh-indexes]
+        I12[devrites-lib<br/>library scripts]
     end
 
     classDef pub fill:#064e3b,stroke:#34d399,color:#ecfdf5
     classDef int fill:#1f2937,stroke:#9ca3af,color:#f9fafb
-    class R1,R2,RT,R3,RV,R4,R5,R6,R7,R8,R9,R12,R13,R10,R11,IPT,D1,D2,D3 pub
-    class I1,I2,I3,I4,I5,I6,I7,I8,I9 int
+    class R1,R2,RT,R3,RV,R4,R5,R6,R7,R8,R9,R12,R13,R10,R11,RQ,RF,RA,RL,RD,IPT,D1,D2,D3 pub
+    class I1,I2,I3,I4,I5,I6,I7,I8,I9,I10,I11,I12 int
 ```
 
 ## 9. AFK & HITL state machine

package/docs/orchestration.md

@@ -29,7 +29,12 @@ its judgment is independent.
    the orchestrator reconciles — banding by confidence and surfacing genuine disagreement explicitly
    rather than averaging it away.
 3. **Single writer.** Exactly one `devrites-slice-wright` per slice, never a parallel fan-out of
-   writers — concurrent writers make conflicting implicit decisions that corrupt a coherent design.
+   writers *sharing a tree* — concurrent writers on one tree make conflicting implicit decisions
+   that corrupt a coherent design. The one sanctioned exception is a **forge** slice
+   (`Forge: yes`, flagged by `/rite-vet`): K=2–3 candidate wrights build it on distinct strategies
+   in **isolated** worktrees, `devrites-forge-judge` scores them, and exactly one winner's diff
+   lands — no tree ever has two authors, so the invariant holds
+   ([`rite-build/reference/forge.md`](../pack/.claude/skills/rite-build/reference/forge.md)).
 4. **Lifecycle as user-driven verbs.** Each verb performs one mutation and stops; chaining is
    explicit (the user types the next command), so there are no hidden side effects between phases.
    `/rite-autocomplete` is the one deliberate exception — an opt-in unattended driver.
@@ -41,7 +46,8 @@ its judgment is independent.
 - **A persona that paraphrases another.** Passing one agent's summary to the next is lossy telephone;
   reviewers read the raw diff and contract, not a digest of the author's reasoning.
 - **Parallel writers.** See single-writer above — two agents editing the same feature concurrently
-  is a merge of conflicting decisions, not a speed-up.
+  is a merge of conflicting decisions, not a speed-up. (Forge is *not* this: its candidates write in
+  **isolated** worktrees and exactly one lands, so no tree is ever co-authored.)
 - **A router that does the work.** `/rite` is a *thin dispatcher* — it renders the menu, resolves a
   verb to a skill, and gets out of the way. It holds no phase logic and produces no artifact itself.
   (This is the distinction that makes a router fine: the anti-pattern is a "meta-orchestrator"
@@ -57,11 +63,15 @@ Two Claude Code capabilities sit adjacent to DevRites' model; the stance on each
   plus fresh-context read-only fan-out already give independent context per agent without the
   coordination overhead, and the lifecycle is intentionally single-slice / single-writer. Reach for
   Agent Teams for work *outside* that discipline — competing-hypothesis debugging, or exploring
-  several genuinely different approaches in parallel — not to parallelise a DevRites build.
-- **Worktree isolation.** Orthogonal to DevRites. A single feature is single-writer on one branch by
-  design, so DevRites doesn't spawn worktrees itself — but you can run DevRites *inside* a git
-  worktree to drive two features in parallel without them colliding. The `.devrites/ACTIVE` sentinel
-  is per-working-tree, so each worktree carries its own active feature.
+  several genuinely different approaches in parallel — not to parallelise a DevRites build. The one
+  in-lifecycle form of "compete several approaches" is **forge** (a `Forge: yes` slice), and it is
+  deliberately bounded: vet-gated, K≤3, isolated, winner-takes-all.
+- **Worktree isolation.** A single feature is single-writer on one branch by design, so DevRites
+  doesn't spawn worktrees for ordinary builds — but you can run DevRites *inside* a git worktree to
+  drive two features in parallel without them colliding (the `.devrites/ACTIVE` sentinel is
+  per-working-tree, so each carries its own active feature). The one place DevRites spawns worktrees
+  itself is a **forge** slice: each candidate build gets an ephemeral worktree, auto-removed after
+  the winner lands.
 
 ## See also
 

package/docs/skills.md

@@ -1,8 +1,8 @@
-# All 29 skills
+# All 36 skills
 
-The pack ships **29 skills total** — 20 user-invocable `rite-*` workflow + utility skills, 9 model-invoked `devrites-*` specialists. Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0) and pulls the other rule files on demand (no carrier skill, no session-start autoload). A 30th directory — the internal `devrites-lib` library skill (`user-invocable: false`, not a command) — ships the cross-cutting scripts the workflow skills run: the read-only orientation preamble and the `readiness` / `evidence-fresh` / `acceptance` gate scripts, plus the `tick-afk` / `resolve` / `close-out` state mutators. A unified `devrites` CLI and an MCP server expose those ops to any tool (see [`cli-mcp.md`](cli-mcp.md)).
+The pack ships **36 skills total** — 24 user-invocable `rite-*` workflow + utility skills and 11 model-invoked `devrites-*` specialists, plus the internal `devrites-lib` library skill (`user-invocable: false`, not a command) that ships the cross-cutting scripts the workflow skills run: the read-only orientation preamble and the `readiness` / `evidence-fresh` / `acceptance` gate scripts, plus the `tick-afk` / `resolve` / `close-out` state mutators. Each skill is a structured workflow with its own operating rules, anti-rationalization tables, and red flags. Engineering rules live at `.claude/rules/`; each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0) and pulls the other 22 rule files on demand (no carrier skill, no session-start autoload). A unified `devrites` CLI and an MCP server expose the `devrites-lib` ops to any tool (see [`cli-mcp.md`](cli-mcp.md)).
 
-**Naming convention.** `rite-*` is the user-facing slash-command surface (lifecycle phases plus utilities — `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). `devrites-*` is internal (model-invoked, hidden from the menu) and collision-avoiding against bundled Claude Code skill names. Visibility is governed by each skill's `user-invocable:` flag; the prefix mirrors it.
+**Naming convention.** `rite-*` is the user-facing slash-command surface (lifecycle phases plus utilities — `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`). `devrites-*` is internal (model-invoked, hidden from the menu) and collision-avoiding against bundled Claude Code skill names. Visibility is governed by each skill's `user-invocable:` flag; the prefix mirrors it.
 
 ---
 
@@ -54,8 +54,13 @@ Every user-invocable skill responds to **both** `/rite <verb>` (menu form — ty
 | `/rite prototype` | `/rite-prototype` | utility | Throwaway code that answers ONE design question before committing — routes between a Logic harness (state/data model) and 2–4 radically different UI variations on one route. |
 | `/rite handoff` | `/rite-handoff` | utility | Compact the chat session into a handoff doc a fresh agent can pick up — syncs to the workspace, references existing artifacts by path. |
 | `/rite pressure-test` | `/rite-pressure-test` | utility | Diverge → converge on a rough idea before specifying. |
+| `/rite quick` | `/rite-quick` | express | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. Significance gate first: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. |
+| `/rite frame` | `/rite-frame` | lens | Pre-flight + self-audit lens for ad-hoc work the lifecycle's gates never see — converts an imperative ask into a falsifiable success criterion + verify command (FRAME), then audits a raw diff against the four LLM coding failure modes (AUDIT). |
+| `/rite adopt` | `/rite-adopt` | onboard | Bring an EXISTING codebase under DevRites — reverse-derive a `spec.md` of current behavior + placement + architecture, and seed the conventions ledger from the idioms the code already follows. |
+| `/rite learn` | `/rite-learn` | utility | Cross-feature learning loop — mine shipped features for recurring mistakes + dismissed-finding classes, propose project-local lessons into `.devrites/learnings.md` (and graduate a recurring invariant to a project principle, human-gated). |
+| `/rite doctor` | `/rite-doctor` | diagnostic | Diagnose DevRites install + workspace health — install integrity, a stale `.devrites/ACTIVE`, a corrupt workspace, orphaned gates, broken hook wiring. |
 
-The 9 model-invoked internal specialists (hidden from the menu): `devrites-interview`, `-source-driven`, `-doubt`, `-ux-shape`, `-frontend-craft`, `-browser-proof`, `-debug-recovery`, `-api-interface`, `-audit` (security / perf / simplify). The `/rite` menu carries the routing, the five user-invocable utilities all use the `rite-*` prefix (`rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`, `rite-autocomplete`), and the `/rite-polish` phases live as references inside the same skill rather than as `rite-polish-code` / `rite-polish-ui`. Triggers and interactions are documented in [`command-map.md`](command-map.md); diagrams in [`flow.md`](flow.md).
+The 11 model-invoked internal specialists (hidden from the menu): `devrites-interview`, `-source-driven`, `-doubt`, `-ux-shape`, `-frontend-craft`, `-prose-craft`, `-browser-proof`, `-debug-recovery`, `-api-interface`, `-audit` (security / perf / simplify), `-refresh-indexes`. Plus the `devrites-lib` library skill (scripts, not a command). The `/rite` menu carries the routing, the user-invocable utilities all use the `rite-*` prefix (`rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, `rite-pressure-test`, `rite-autocomplete`), and the `/rite-polish` phases live as references inside the same skill rather than as `rite-polish-code` / `rite-polish-ui`. Triggers and interactions are documented in [`command-map.md`](command-map.md); diagrams in [`flow.md`](flow.md).
 
 ---
 
@@ -68,6 +73,15 @@ The 9 model-invoked internal specialists (hidden from the menu): `devrites-inter
 | [`rite`](../pack/.claude/skills/rite/SKILL.md) | Compact menu + active-feature status + suggested next command. Does not run a workflow. | You type `/rite`, ask "what DevRites commands exist", or "where am I". |
 | [`rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | Read-only report: phase, run mode (AFK/HITL), status, active slice, next action, evidence, open questions by gate, drift, risks. | You ask "where am I", "what's the status", "what's next". |
 | [`rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and resumes the workflow. | A HITL checkpoint is open or AFK left blocking questions; you type `/rite-resolve <qid> "<answer>"`. |
+| [`rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | Diagnose DevRites install + workspace health — install integrity, stale `.devrites/ACTIVE`, corrupt workspace, orphaned gates, broken hook wiring. Read-only report. | "rite doctor", "is DevRites healthy", "why isn't the workflow picking up my feature". |
+
+### Express & ad-hoc — small or unguarded work
+
+| Skill | What It Does | Use When |
+|---|---|---|
+| [`rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, collapsing the full lifecycle into one pass. Significance gate first: auth / migration / public-API / destructive / multi-slice / ambiguous **escalates to `/rite-spec`**. | "quick fix", "small change", "tiny tweak", "just do X" on a low-risk change. |
+| [`rite-frame`](../pack/.claude/skills/rite-frame/SKILL.md) | Pre-flight + self-audit lens for ad-hoc work the lifecycle gates never see — FRAME converts an imperative ask into a falsifiable success criterion + verify command before code; AUDIT checks a raw diff against the four LLM coding failure modes (silent assumption / overcomplication / out-of-scope edit / unverifiable goal). | Top of `/rite-quick`, before a plain "just do X" edit, or to self-review a raw diff. |
+| [`rite-adopt`](../pack/.claude/skills/rite-adopt/SKILL.md) | Bring an EXISTING codebase under DevRites — reverse-derive a `spec.md` of current behavior + placement + architecture, and seed the conventions ledger from the idioms the code already follows, then hand off to the lifecycle. | "adopt this project", "onboard this codebase", "we already have code", "reverse-engineer a spec from the existing app". |
 
 ### Spec — Understand the ask before any code
 
@@ -101,17 +115,18 @@ The 9 model-invoked internal specialists (hidden from the menu): `devrites-inter
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | Orchestrates **exactly one** vertical slice: pre-flight gates, then dispatches a fresh-context [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) for the build core, then doubts / gates / records with evidence. | A plan exists and the next slice is ready. |
+| [`rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | Orchestrates **exactly one** vertical slice: pre-flight gates, then dispatches a fresh-context [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) for the build core, then doubts / gates / records with evidence. A slice `/rite-vet` flagged `Forge: yes` competes K=2–3 isolated candidate builds judged by [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md), landing one winner (`forge-report.md`). | A plan exists and the next slice is ready. |
 | [`devrites-source-driven`](../pack/.claude/skills/devrites-source-driven/SKILL.md) | Consult official docs / source before relying on framework behavior; record the source. | API, config, or framework behavior is assumed rather than known. |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | Design stable API / interface contracts — REST/GraphQL, module boundaries, type contracts, FE/BE split. | A slice crosses a boundary or defines a public interface. |
 | [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | Reproduce → ranked hypotheses → instrument → fix in scope → regression-test. Stops guess-and-retry. | Tests, builds, or runtime checks fail. |
+| [`devrites-refresh-indexes`](../pack/.claude/skills/devrites-refresh-indexes/SKILL.md) | Keep the optional code-intelligence indexes (codebase-memory-mcp, codegraph, graphify) current so the next structural lookup reads live code, not a stale graph. The Stop hook runs it automatically; this skill is the manual force. | Index looks stale, after a large change before a structural query, or "reindex" / "the graph is stale". |
 
 ### Prove — Real evidence, including the browser
 
 | Skill | What It Does | Use When |
 |---|---|---|
 | [`rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | Tests + build + runtime + browser evidence for the current scope. | All slices built; ready for full verification. |
-| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | Browser proof ladder: browser-harness → Chrome DevTools MCP → `/run`+`/verify` → project E2E → manual. | Scope touches UI. |
+| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | Browser proof ladder: browser-harness → Chrome DevTools MCP → `/run`+`/verify` → project E2E → manual. Auto-emits the structured **Visual Verdict** (per-criterion PASS/FAIL vs `design-brief.md`) for UI slices — consumed by `devrites-frontend-reviewer` and gated at `/rite-seal`. | Scope touches UI. |
 
 ### Polish — Normalize, then ship-quality detail pass
 
@@ -119,6 +134,7 @@ The 9 model-invoked internal specialists (hidden from the menu): `devrites-inter
 |---|---|---|
 | [`rite-polish`](../pack/.claude/skills/rite-polish/SKILL.md) | Orchestrator. Always runs code polish (`reference/code.md`); detects UI scope and runs UI normalize + polish (`reference/ui.md`) when needed. Accepts mode tokens (`bolder`, `quieter`, `distill`, `harden`, `normalize-only`). | All slices proven; ready to finish. |
 | [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | Senior frontend craft — register, shape-before-code, all states, design system, anti-AI-slop, Core Web Vitals + WCAG 2.2. | A slice touches UI. |
+| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | Human-voice writing for artifacts + replies — strips the LLM tells (filler openers, false contrasts, fake profundity, em-dash tics, hedging) while keeping precise lists, exact terms, and spec structure. The catch pass in `/rite-polish` Phase 1. | A phase writes prose (spec / plan / decisions / review / seal / commit / PR bodies) or a user-facing reply. |
 
 ### Review — Adversarial, scoped to the feature
 
@@ -154,27 +170,35 @@ The 9 model-invoked internal specialists (hidden from the menu): `devrites-inter
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| (engineering rules) | Live at `.claude/rules/` post-install — each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0); the other 19 rule files (`coding-style.md`, `prose-style.md`, `error-handling.md`, `testing.md`, `code-review.md`, `security.md`, `performance.md`, `observability.md`, `patterns.md`, `git-workflow.md`, `hooks.md`, `documentation.md`, `development-workflow.md`, `deprecation.md`, `agents.md`, `context-hygiene.md`, `anti-patterns.md`, `afk-hitl.md`, `tooling.md`) load on demand per skill body. No carrier skill, no session-start autoload. | n/a — step-0 core / on-demand by path. |
+| (engineering rules) | Live at `.claude/rules/` post-install — each `rite-*` skill Reads `.claude/rules/core.md` as its first step (step 0); the other 22 rule files (`coding-style.md`, `prose-style.md`, `error-handling.md`, `testing.md`, `spec-grammar.md`, `code-review.md`, `principles.md`, `security.md`, `performance.md`, `observability.md`, `developer-experience.md`, `patterns.md`, `git-workflow.md`, `hooks.md`, `documentation.md`, `development-workflow.md`, `deprecation.md`, `agents.md`, `context-hygiene.md`, `anti-patterns.md`, `afk-hitl.md`, `tooling.md`) load on demand per skill body. No carrier skill, no session-start autoload. | n/a — step-0 core / on-demand by path. |
 
 ---
 
 ## Review agents — Fresh-context reviewers
 
-Spawned by `/rite-review`, `/rite-seal` (post-build), `/rite-temper` (pre-plan), and `/rite-vet` (pre-build) for independent judgment. Read-only; given only the artifact + rubric, never the author's reasoning.
+Spawned by `/rite-review`, `/rite-seal` (post-build), `/rite-temper` (pre-plan), `/rite-vet` (pre-build), and `/rite-build` (the forge judge, on a `Forge: yes` slice) for independent judgment. Read-only; given only the artifact + rubric, never the author's reasoning. **13 read-only** in all (12 reviewers + the cross-feature `devrites-retrospector`); plus the one **write-capable** `devrites-slice-wright` below.
 
 | Agent | Purpose |
 |---|---|
 | [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | **Pre-plan** spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention) — via `/rite-temper`, not the seal fan-out. |
 | [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | **Pre-build** plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate — via `/rite-vet`, not the seal fan-out. |
+| [`devrites-forge-judge`](../pack/.claude/agents/devrites-forge-judge.md) | **Build-time** comparative judge of K=2–3 competing candidate builds of one slice (acceptance / test strength / principle fit / simplicity / reuse / anti-slop) — via `/rite-build` on a `Forge: yes` slice; picks the single winner to land, names grafts. |
 | [`devrites-spec-reviewer`](../pack/.claude/agents/devrites-spec-reviewer.md) | Does the diff implement the spec? Missing / partial / wrong criteria; scope creep. |
 | [`devrites-code-reviewer`](../pack/.claude/agents/devrites-code-reviewer.md) | Correctness / readability / architecture / maintainability. |
 | [`devrites-test-analyst`](../pack/.claude/agents/devrites-test-analyst.md) | Do the tests actually prove the acceptance criteria? |
 | [`devrites-frontend-reviewer`](../pack/.claude/agents/devrites-frontend-reviewer.md) | UX, a11y, responsive, design-system, anti-AI-slop. |
 | [`devrites-security-auditor`](../pack/.claude/agents/devrites-security-auditor.md) | OWASP Top 10, trust boundary, secrets, deps. |
 | [`devrites-performance-reviewer`](../pack/.claude/agents/devrites-performance-reviewer.md) | N+1s, hot paths, payload size. |
+| [`devrites-devex-reviewer`](../pack/.claude/agents/devrites-devex-reviewer.md) | Developer-experience scorecard + the predict-vs-measure boomerang (TTHW, getting-started, error-message quality, ergonomics, docs) — predicts at `/rite-vet`, measures + reconciles at `/rite-seal`, when a developer-facing surface (API / CLI / SDK / webhook / config / errors / getting-started) is in scope. |
 | [`devrites-doubt-reviewer`](../pack/.claude/agents/devrites-doubt-reviewer.md) | Adversarial check of a single claim/decision. |
 | [`devrites-simplifier-reviewer`](../pack/.claude/agents/devrites-simplifier-reviewer.md) | Independent simplification judgment (called by `devrites-audit simplify`). |
 
+**Cross-feature analyst** (read-only, scope is the archive not a diff):
+
+| Agent | Purpose |
+|---|---|
+| [`devrites-retrospector`](../pack/.claude/agents/devrites-retrospector.md) | Mine the shipped `.devrites/archive/<slug>/` workspaces for recurring patterns + trends (repeated review findings, recurring drift, dead-ends, GO/NO-GO + rework signal) and **draft** graduation candidates for `/rite-learn`. Proposes, never imposes. Dispatched at `/rite-ship` close, cadence-gated. |
+
 Seal fan-out diagram: [`flow.md` § /rite-seal fan-out](flow.md#4-rite-seal-fan-out).
 
 ---