devrites 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -2,10 +2,39 @@
 
 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.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
+
+* **rules:** add observability + deprecation rules, OWASP LLM Top 10 ([0c29760](https://github.com/ViktorsBaikers/DevRites/commit/0c29760e504c22c18d7ca2c5e1986746ba95a07d))
+
+### Fixed
+
+* **release:** drop duplicate 2.1.0 changelog block ([0a7b510](https://github.com/ViktorsBaikers/DevRites/commit/0a7b5101ecd05e4c0b4d3812cefc68c0f92f1626))
+
 ## [2.1.0](https://github.com/ViktorsBaikers/DevRites/compare/v2.0.0...v2.1.0) (2026-06-23)
 
 ### Added
 
+* **agents:** code reviewer gets structural-depth lenses ([b37c9d2](https://github.com/ViktorsBaikers/DevRites/commit/b37c9d259b99613b971269fac2943977dedbea6d))
 * **agents:** perf reviewer gets Source/Measured CWV modes ([be82b20](https://github.com/ViktorsBaikers/DevRites/commit/be82b20b37252a9f55d77e0f71659ec58a213ca6))
 
 ## [2.0.0](https://github.com/ViktorsBaikers/DevRites/compare/v1.18.0...v2.0.0) (2026-06-23)

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.1.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.1.0) — see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v2.3.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v2.3.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)
@@ -113,6 +120,7 @@ rules carrier, workspace state, namespace map) →
 [skills catalogue](docs/skills.md) ·
 [command map](docs/command-map.md) ·
 [flow diagrams](docs/flow.md) ·
+[orchestration](docs/orchestration.md) ·
 [usage examples](docs/usage.md) ·
 [release pipeline](docs/release.md) ·
 [engineering rules](pack/.claude/rules/README.md)
@@ -274,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.
 
@@ -296,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:
@@ -311,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/`:
 
@@ -423,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).
@@ -485,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
@@ -177,7 +183,7 @@ demands. No carrier skill, no session-start autoload.
 ```mermaid
 flowchart TD
     R[rite-* skill<br/>step 0] -->|always-on| Core[.claude/rules/core.md]
-    R -->|on demand index| Idx[(.claude/rules/README.md<br/>15 specialist rule files)]
+    R -->|on demand index| Idx[(.claude/rules/README.md<br/>19 specialist rule files)]
     Idx --> CS[coding-style.md]
     Idx --> EH[error-handling.md]
     Idx --> T[testing.md]
@@ -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

@@ -0,0 +1,81 @@
+# Orchestration patterns
+
+How DevRites coordinates multiple agents — the patterns it uses, the ones it deliberately avoids,
+and where Claude Code's Agent Teams and worktree isolation fit. The rule that governs this lives in
+[`pack/.claude/rules/agents.md`](../pack/.claude/rules/agents.md); this doc is the map.
+
+## The model
+
+DevRites separates three roles and never blurs them:
+
+- **Orchestrator** — the active `rite-*` skill (chiefly `/rite-build` and `/rite-seal`). It owns
+  the gates and the `.devrites/` workspace, dispatches the other agents, and is the *single
+  canonical writer* of workspace state.
+- **Reviewers** — fresh-context, **read-only** subagents under `.claude/agents/`. Each gets the
+  workspace path + the diff and returns labelled findings; read-only is enforced at the tool layer
+  (`devrites-reviewer-readonly.sh`), not merely promised.
+- **Executor** — `devrites-slice-wright`, the one **write-capable** agent. It implements a single
+  fully-specified slice in a fresh context and returns code + tests; it never writes the `.devrites/`
+  bookkeeping (the orchestrator does).
+
+Fresh, undirected context is the point: an agent gets the contract, not the author's reasoning, so
+its judgment is independent.
+
+## Endorsed patterns
+
+1. **Direct (no orchestration).** Most phases are one skill doing one job. Don't spawn an agent for
+   work the phase can do inline.
+2. **Parallel read-only fan-out.** At `/rite-seal` the relevant reviewers run *in parallel*, then
+   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 *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.
+5. **Adversarial single-claim check.** `devrites-doubt` spawns a fresh reviewer to try to refute one
+   load-bearing decision, rather than asking the author to re-grade their own work.
+
+## Anti-patterns DevRites avoids
+
+- **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. (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"
+  persona that paraphrases and re-decides on every call, not a dispatch table.)
+- **Deep persona trees.** Agents don't call agents that call agents. The orchestrator dispatches one
+  level deep — reviewers and the wright — and reconciles the results itself.
+
+## Agent Teams and worktree isolation
+
+Two Claude Code capabilities sit adjacent to DevRites' model; the stance on each is deliberate.
+
+- **Agent Teams.** DevRites does **not** use Agent Teams to run the lifecycle. The on-disk workspace
+  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. 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
+
+- [`pack/.claude/rules/agents.md`](../pack/.claude/rules/agents.md) — the reviewer / executor roster
+  and the when-to-fan-out rules.
+- [`architecture.md`](architecture.md) — the full layer model.
+- [`flow.md`](flow.md) — phase-by-phase flow and the public/internal namespace.