devrites 2.2.0 → 2.3.0

package/pack/.claude/skills/rite-review/SKILL.md

@@ -21,6 +21,7 @@ if none, tell the user to run `/rite-spec <feature>`.
 **Step 0:** Read `.claude/rules/core.md` first. The other rule files load on demand;
 pull these via `Read` when the diff demands them:
 - `code-review.md` — small PRs, severity labels, tests-first review focus.
+- `principles.md` — declared project invariants (`.devrites/principles.md`); a diff that violates one with no recorded exception is a Critical, blocking finding.
 - `testing.md` — confirm the tests prove the spec, not just pass.
 - `agents.md` — when to fan out to which review subagent.
 - `security.md` — when input / auth / data / integrations / secrets are in scope.
@@ -48,7 +49,8 @@ pull these via `Read` when the diff demands them:
    [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
    ```
 1. Read `spec.md`, `tasks.md`, `state.md`, `decisions.md`, `evidence.md`,
-   `touched-files.md`, and the `git diff`. For "what would this change break"
+   `touched-files.md`, `.devrites/principles.md` (if present — the binding invariants to score
+   the diff against), and the `git diff`. For "what would this change break"
    questions, prefer a code-intelligence index if available — codebase-memory-mcp first,
    cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
    `.claude/rules/tooling.md` — over file reads;
@@ -77,7 +79,8 @@ pull these via `Read` when the diff demands them:
        where 20 would do) and the silent-failure bugs (a missing value coerced to 0/''/[],
        a dropped Result/err return, off-by-one / boundary, logic that contradicts the
        comment/docstring/name). Per hunk, check whether working code was deleted that the
-       task did not ask to remove."
+       task did not ask to remove. Score the diff against `.devrites/principles.md` — a change
+       that breaks a declared invariant with no recorded, human-approved exception is a Critical."
    - **Do NOT merge or re-rank** their findings. Present them under separate
      `## Spec` and `## Code review` sub-sections in `review.md`. Surface contradictions
      between the axes explicitly (e.g. "Spec axis says complete, Code-review axis says

package/pack/.claude/skills/rite-seal/SKILL.md

@@ -17,6 +17,7 @@ live in `/rite-ship`, which refuses to run without a GO recorded here.
 pull these via `Read` before sealing:
 - `agents.md` — review-subagent fan-out at seal.
 - `code-review.md` — severity labels (Critical / Important / Suggestion / Nit / FYI).
+- `principles.md` — declared project invariants (`.devrites/principles.md`) are a pass/fail gate; a diff that violates one with no recorded, human-approved exception is a NO-GO.
 - `documentation.md` — record decisions in `decisions.md` before sealing.
 - `observability.md` — a runtime surface that ships blind is an Important finding.
 - `deprecation.md` — when the diff removes / migrates code, API, or data (read with the
@@ -37,6 +38,8 @@ Read `review.md` and the latest reviewer outputs.
 | `Critical == 0` and `Important > 0` and acceptance proven and drift resolved | Render interactive prompt: *"`Important > 0` open. Proceed to seal? [y/N]"*. Default **N**. If the user types `y`, GO; otherwise NO-GO with the open Important findings listed as blockers-by-policy. |
 | `Critical > 0` | **NO-GO**, no exceptions. List every Critical with `file:line` and fix direction. |
 | Any acceptance criterion unproven | **NO-GO**, list the unproven criteria. |
+| Visual Verdict `FAIL` on an acceptance-mapped UI criterion (`browser-evidence.md`) | **NO-GO** — an unmet acceptance criterion. A declared-state `FAIL` is Important (the `Important > 0` row). UI build with a `design-brief.md` but no Visual Verdict → Important evidence gap. No brief → not applicable. |
+| Diff violates a declared project principle (`.devrites/principles.md`) with no recorded, human-approved exception | **NO-GO**, list each violated principle with `file:line`. Same standing as an unproven criterion (absent / empty file → none declared → not a blocker). |
 | Unresolved drift in `drift.md` | **NO-GO**, route through `/rite-plan` first. |
 | Any `questions.md` entry with `gate: validating` and `status: open` | **NO-GO** regardless of behavior impact — an open validating gate is merge-blocking by definition. A slice marked `built (pending review)` is not done. |
 
@@ -53,7 +56,7 @@ Read `review.md` and the latest reviewer outputs.
    Then read all artifacts: `brief.md`, `spec.md`, `plan.md`, `tasks.md`, `state.md`,
    `decisions.md`, `assumptions.md`, `questions.md`, `drift.md`, `evidence.md`,
    `browser-evidence.md`, `polish-report.md`, `review.md`, `design-brief.md` (if UI),
-   `strategy.md` (if present), and the **final diff**. If a code-intelligence index is available
+   `devex.md` (if a developer-facing surface), `strategy.md` (if present), and the **final diff**. If a code-intelligence index is available
    (codebase-memory-mcp first, cross-checked with codegraph + graphify, else standard methods LSP / Read/Grep/Glob — see `.claude/rules/tooling.md`), use it for
    blast-radius checks on the final diff in step 5; context7 if available can confirm a current
    external-API signature a reviewer flags.
@@ -63,7 +66,11 @@ Read `review.md` and the latest reviewer outputs.
    proof; the `devrites-spec-reviewer` + `devrites-test-analyst` fan-out in step 7 is the
    independent cross-check (a verifier that never saw the optimistic narrative).
 3. Verify tests, build/typecheck/lint, and browser proof are present and green for the
-   scope. Re-run if cheap and in doubt.
+   scope. Re-run if cheap and in doubt. **For a UI feature with a `design-brief.md`**, read the
+   `## Visual Verdict` table in `browser-evidence.md`: a `FAIL` on an **acceptance-mapped**
+   criterion is an unmet acceptance criterion (NO-GO, per the severity gate), a declared-state
+   `FAIL` is **Important**, and a UI build whose brief exists but whose verdict is **absent** is an
+   Important evidence gap (the scorecard should have been emitted at browser-proof).
 4. Check unresolved **questions** and **drift** — any open item that changes product
    behavior blocks. **Any `questions.md` entry with `gate: validating` and `status: open`
    is a NO-GO regardless of behavior impact** (an open validating gate is merge-blocking by
@@ -73,10 +80,19 @@ Read `review.md` and the latest reviewer outputs.
    `/rite-temper`), confirm its **top pre-mortem risks are mitigated** in the diff/evidence and
    that no **Non-goal / deferred item crept into the diff** (scope creep) — either is a finding
    (an unmitigated top risk or smuggled-in out-of-scope work).
+   - **Principles** (`principles.md`): score the final diff against each declared invariant in
+     `.devrites/principles.md`. A violation with no matching, human-approved exception in the
+     register is a **Critical** finding and a NO-GO; an exception that is stale (past its review
+     trigger) or wider than its stated scope is itself a finding. No file / no principles → skip.
    - **Observability** (`observability.md`): if the diff added a runtime surface (endpoint,
      job, integration, user flow, error path), a feature shipping with no way to debug it in
      prod is an **Important** finding, not a pass — `evidence.md` should show telemetry observed
      to emit (`/rite-prove` step 5b).
+   - **Developer experience** (`developer-experience.md`): if the diff ships a developer-facing
+     surface, reconcile `devex.md` (the `/rite-vet` predicted scorecard vs the `/rite-prove`
+     measured one — the boomerang). A broken public dev contract (a documented command that errors,
+     a getting-started flow that can't complete) or an unexplained measured DX regression is
+     **Important** — **Critical** on a frozen public surface (`principles.md`). No surface → skip.
    - **Removal / migration** (`deprecation.md`): if the diff deletes or migrates code, an API,
      or data, confirm it followed expand→contract, proved the old path unused before removing it,
      and carries a rollback for every destructive step. A surprise deletion or a one-shot
@@ -98,8 +114,10 @@ Read `review.md` and the latest reviewer outputs.
    `devrites-spec-reviewer` (does the diff implement
    the spec?), `devrites-test-analyst` (do the tests prove acceptance?),
    `devrites-code-reviewer`, `devrites-frontend-reviewer` (UI features),
-   `devrites-security-auditor` (input/auth/data/integrations), and
-   `devrites-performance-reviewer` (perf-relevant). Give each the workspace
+   `devrites-security-auditor` (input/auth/data/integrations),
+   `devrites-performance-reviewer` (perf-relevant), and `devrites-devex-reviewer`
+   (developer-facing surface — measure mode: grade the measured DX scorecard and reconcile
+   the boomerang against the `/rite-vet` prediction). Give each the workspace
    path + diff *without the author's reasoning*. If subagents are unavailable,
    run the equivalent reviews sequentially yourself.
    The reviewer **AGENTS** here (fresh context, no author reasoning) are the seal

package/pack/.claude/skills/rite-ship/SKILL.md

@@ -97,6 +97,26 @@ Refuses to ship unless `seal.md` records a **GO** verdict.
    `bash .claude/skills/devrites-lib/scripts/close-out.sh <slug>` to archive
    `.devrites/work/<slug>/` → `.devrites/archive/<slug>/` and clear `.devrites/ACTIVE`.
    Every `.md` is preserved in the archive.
+6a. **Cross-feature retro (automatic, cadence-gated, advisory).** The just-shipped feature is now in
+   the archive, so this is where the **cross-feature** learning loop closes on its own — the synthesis
+   that otherwise waits for a human to run `/rite-learn`. Run the cheap cadence gate first; it stays
+   silent unless a finding/drift class recurs across **>=2 shipped features** with new signal since the
+   last review (so it never fires on an early or one-off ship):
+   ```bash
+   L=.claude/skills/devrites-lib/scripts/learnings.sh
+   [ -f "$L" ] || L="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/learnings.sh"
+   [ -f "$L" ] || L=pack/.claude/skills/devrites-lib/scripts/learnings.sh
+   [ -f "$L" ] && bash "$L" nudge || true
+   ```
+   **If the nudge emits** (a recurring pattern crossed the threshold), dispatch the read-only
+   `devrites-retrospector` (`.claude/agents/`) over `.devrites/archive/` for the cross-feature
+   synthesis. Persist its digest to `.devrites/retro.md` (append a dated entry — the project-level
+   retro ledger, never rewritten) and surface the **graduation candidates** with a one-line pointer
+   to `/rite-learn`, which is where the human confirms a promotion to a rule / principle / convention.
+   **Propose, never impose:** retro **drafts**; it never auto-writes a rule or principle (a principle
+   is a gate, amended deliberately and dated — `principles.md` governance), and it never blocks the
+   ship, which has already happened. If the nudge is silent, skip — no retro this close. Then `touch
+   .devrites/.learnings-reviewed` only when the human acts on it via `/rite-learn`, not here.
 
 > **Mid-flight discipline.** When tempted to ship without a GO seal, skip the type-GO,
 > stage files outside `touched-files.md`, or delete the workspace instead of archiving
@@ -112,6 +132,7 @@ Commit:  <sha> on <branch>    Tag/PR: <ref | none>
 Acceptance: <n/total> proven
 Archived: .devrites/archive/<slug>/    ·    ACTIVE cleared
 ship.md:  .devrites/archive/<slug>/ship.md
+Retro:    <n graduation candidates drafted → .devrites/retro.md · promote with /rite-learn | quiet (no cross-feature signal yet)>
 ```
 If the user declined type-GO: state that nothing shipped, the seal still reads GO, and
 the resume command (`/rite-ship`).

package/pack/.claude/skills/rite-spec/SKILL.md

@@ -21,7 +21,13 @@ are `/rite-define` and `/rite-build`.
 ## Rules consulted (read on demand from `.claude/rules/`)
 **Step 0:** Read `.claude/rules/core.md` first. DevRites skills Read `.claude/rules/core.md`
 as their first step; the other rule files load on demand. Pull `documentation.md` via `Read`
-when capturing significant spec decisions (why-not-what, ADR-style notes in `decisions.md`).
+when capturing significant spec decisions (why-not-what, ADR-style notes in `decisions.md`);
+pull `principles.md` when the project has declared invariants (`.devrites/principles.md`) — a
+new spec must respect them, and a requirement that can only be met by breaking one is a blocking gap.
+Pull `spec-grammar.md` when writing acceptance for a behavioral / high-risk requirement (auth,
+data model, state machine, public API, money, migration) — the structured `### Requirement:` /
+`#### Scenario:` (SHALL · WHEN/THEN) form, lint-checked by `spec-validate.sh`. Simple criteria
+stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
 
 ## Operating rules (DevRites core)
 - No silent assumptions · no guessing through confusion · prefer existing conventions ·
@@ -55,7 +61,8 @@ when capturing significant spec decisions (why-not-what, ADR-style notes in `dec
    Also discover the project's **test / build/typecheck/lint** commands and the
    frontend/backend systems; read `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` / `AGENTS.md` if
    present (`AGENTS.md` is the cross-tool agent-conventions standard — treat it as project
-   conventions the build must follow, same standing as `CLAUDE.md`).
+   conventions the build must follow, same standing as `CLAUDE.md`), and read
+   `.devrites/principles.md` if present — the declared invariants the feature must respect.
 3. **Gather design references (optional)** — [references-intake](reference/references-intake.md).
    The human **may** attach screenshots, mockups, a Figma link, a video, or links — or
    **none at all** (perfectly normal; skip this step then). If any are given: **view/fetch**
@@ -79,12 +86,19 @@ when capturing significant spec decisions (why-not-what, ADR-style notes in `dec
    can predict them (don't interrogate). Aim for **zero blocking gaps**. *If a gap is genuinely undecidable on paper (state
    machine that may deadlock, data shape ambiguity, "which UX wins") → suggest a
    scoped detour to `/rite-prototype` to answer that ONE question before
-   continuing.*
+   continuing.* **Invariant conflict is a blocking gap:** if a requirement or acceptance
+   criterion can only be satisfied by breaking a declared principle (`.devrites/principles.md`),
+   surface it — the principle wins by default; breaking it needs a recorded, scoped exception a
+   human approves, never a spec that silently contradicts an invariant.
 5. **Create the workspace** + set `.devrites/ACTIVE`
    ([state-workspace](reference/state-workspace.md)). Write `spec.md`
    ([spec-template](reference/spec-template.md)) — WHAT/WHY, technology-agnostic, with
    **Placement & integration**, **Design references**, **Gaps/issues/decisions**, and
-   measurable acceptance ([acceptance-criteria](reference/acceptance-criteria.md)). Also
+   measurable acceptance ([acceptance-criteria](reference/acceptance-criteria.md)). For a
+   behavioral / high-risk requirement, write the acceptance as a structured
+   `### Requirement:` (SHALL) + `#### Scenario:` (WHEN/THEN) block per
+   [`spec-grammar.md`](../../rules/spec-grammar.md), nesting the `[ACn]` id inside each scenario
+   so `/rite-seal` still grades it; routine criteria stay flat `[ACn]` bullets. Also
    write `brief.md`, `references.md`, `questions.md`, `decisions.md`, `assumptions.md`,
    and an initial `state.md` (phase: spec). When the feature touches UI, `design-brief.md`
    is written here too (by `devrites-ux-shape`, step 3a).
@@ -98,7 +112,16 @@ when capturing significant spec decisions (why-not-what, ADR-style notes in `dec
    `[NEEDS CLARIFICATION]`, placement decided, all material gaps resolved, any design
    references provided are saved, **UX/UI shaped into `design-brief.md` if the feature is
    UI**, requirements testable, success criteria measurable, **every `checklists/<domain>.md` at
-   `Verdict: pass`**. When it passes, write `Spec gate: passed <iso>` to `state.md`. **Stop** when
+   `Verdict: pass`**, and **any structured requirement blocks are grammar-valid** — run
+   `spec-validate.sh` (resolved like the step-0 preamble), a non-zero exit is a blocking
+   failure to fix, not soften:
+   ```bash
+   SV=.claude/skills/devrites-lib/scripts/spec-validate.sh
+   [ -f "$SV" ] || SV="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/spec-validate.sh"
+   [ -f "$SV" ] || SV=pack/.claude/skills/devrites-lib/scripts/spec-validate.sh
+   [ -f "$SV" ] && bash "$SV" ".devrites/work/<slug>" || echo "(spec-grammar validator unavailable — eyeball the Requirement/Scenario blocks)"
+   ```
+   When it passes, write `Spec gate: passed <iso>` to `state.md`. **Stop** when
    it passes.
 
 > **Mid-flight discipline.** When tempted to skip investigation depth, gap-closing, or placement decisions — see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
@@ -114,6 +137,7 @@ References: <n saved | none provided>
 Design brief: <design-brief.md shaped (compact|full) | n/a — not UI>
 Gaps closed: <n>   Open (non-blocking): <n>
 Checklists: <n domains scored — all pass | BLOCKED: n CRITICAL open>
+Grammar: <n requirements / m scenarios — valid | n/a (flat acceptance)>
 Next: big / risky feature (auth · data model · public API · migration · multi-slice · ambiguous scope)?
       → /rite-temper   (strategic review: scope mode + pre-mortem, hardens the spec) — then /rite-define.
       Small / reversible / unambiguous? → /rite-define directly.

package/pack/.claude/skills/rite-spec/reference/spec-template.md

@@ -65,7 +65,16 @@ Observable outcomes that mean "this worked". Numbers where possible. No tech nam
 
 ## Acceptance criteria
 Binary, evidence-backed checklist; each maps to a scenario/FR. See acceptance-criteria.md.
-- [ ] <criterion> (FR-00x)
+- [ ] [AC1] <criterion> (FR-00x)
+
+For a behavioral / high-risk requirement (auth, data model, state machine, public API, money,
+migration), write it as a structured Requirement/Scenario block instead — testable by
+construction and lint-checked by spec-validate.sh (see spec-grammar.md). Keep the [ACn] id
+inside the scenario so the seal still grades it; routine criteria stay flat bullets above.
+### Requirement: <name>
+The system SHALL <core observable behavior>.
+#### Scenario: <name>
+- [ ] [AC2] **WHEN** <trigger> **THEN** <observable outcome>  (**AND** <extra condition>)
 
 ## Non-goals
 Explicitly out of scope for this version.
@@ -119,6 +128,7 @@ List every open marker; blocking ones must be zero at the gate.
 - [ ] Design references gathered + saved (if the human supplied any)
 - [ ] **UX/UI shaped into `design-brief.md`** (if the feature touches UI) — direction, key states, interaction model decided
 - [ ] Requirements are testable and unambiguous
+- [ ] **Structured requirements are grammar-valid** (if any) — `### Requirement:` / `#### Scenario:` blocks pass `spec-validate.sh` (SHALL + WHEN/THEN, unique headers); flat `[ACn]` bullets need no check (see spec-grammar.md)
 - [ ] Success criteria are measurable and technology-agnostic
 - [ ] **Spec-quality checklists pass** — every `checklists/<domain>.md` reaches `Verdict: pass` (zero CRITICAL "unit-tests-for-English" fails; see [spec-checklists.md](spec-checklists.md))
 ```

package/pack/.claude/skills/rite-status/SKILL.md

@@ -49,7 +49,9 @@ Otherwise summarize from the loaded state, concisely:
 6. **Open questions** — count by gate (from `questions.md`:
    `n open: x blocking · y validating · z advisory`) + the blocking qids by id and one-line question.
 7. **Unresolved drift** (`drift.md`).
-8. **Risks** (from `state.md` / `spec.md`).
+8. **Risks** (from `state.md` / `spec.md`); if `.devrites/principles.md` exists, note the count
+   of declared invariants and flag any exception in its register that is past its review/removal
+   trigger (a stale exception is a standing risk). Omit if there's no principles file.
 9. **Ready for handoff?** — see section below.
 
 Flag anything blocking: unresolved drift, failing evidence, `Status: awaiting_human`,

package/pack/.claude/skills/rite-vet/SKILL.md

@@ -22,11 +22,16 @@ This is the engineering counterpart to `/rite-temper` (which is strategic, on th
 Temper decides *the right thing*; vet decides *the right way to build it*.
 
 ## Rules consulted (read on demand from `.claude/rules/`)
-**Step 0:** Read `.claude/rules/core.md` first. Pull on demand: `patterns.md` +
+**Step 0:** Read `.claude/rules/core.md` first. Pull on demand: `principles.md` (the project
+invariants gate — how `.devrites/principles.md` is scored pass/fail), `patterns.md` +
 `coding-style.md` (the over-engineering / reuse-first / YAGNI rubric — reuse the pack's
-standard), `testing.md` (the test-coverage axis), `performance.md` (the perf axis),
+standard), `testing.md` (the test-coverage axis) + `spec-grammar.md` (when the spec uses
+structured Requirement/Scenario blocks, each scenario is a coverage unit `test-plan.md` must
+map), `performance.md` (the perf axis),
 `error-handling.md` (failure-mode coverage), `development-workflow.md` (parallel lanes,
-definition of done), `afk-hitl.md` (irreversible-risk list + gate ceiling).
+definition of done), `afk-hitl.md` (irreversible-risk list + gate ceiling),
+`developer-experience.md` (when the plan ships a developer-facing surface — API / CLI / SDK /
+webhook / config / error messages / getting-started — predict the DX scorecard here).
 
 ## Operating rules
 - **Review the plan, not the spec's ambition.** The spec's scope/ambition is `/rite-temper`'s
@@ -78,15 +83,22 @@ definition of done), `afk-hitl.md` (irreversible-risk list + gate ceiling).
    against a built-in (dispatch `devrites-source-driven`); completeness check (with AI, full
    coverage is ~100× cheaper than the human-hours saved by a shortcut — prefer complete); and a
    distribution check for any new artifact.
-2a. **Cross-artifact analyze gate + charter/conventions gate.** Before the axes, run one read-only
-   consistency+coverage pass over `spec.md` + `plan.md` + `tasks.md` (+ `coverage.md` if present);
-   any **CRITICAL** — an acceptance criterion with no slice, a slice satisfying no criterion, a
-   contradiction across artifacts — **blocks `/rite-build`** until resolved. Then score the anti-slop
-   charter (`coding-style.md` + `prose-style.md`) and the conventions ledger
-   (`.devrites/conventions.md`) as an explicit **pass/fail** on the planned approach — a plan that
-   bakes in a god-module, a speculative abstraction with no second caller, or a dependency where an
-   in-repo option exists is a **top-severity** violation, walked first. **Re-check both after the
-   axes harden the plan** (post-design). Write the result to `analysis.md`.
+2a. **Cross-artifact analyze gate + principles / charter / conventions gate.** Before the axes, run
+   one read-only consistency+coverage pass over `spec.md` + `plan.md` + `tasks.md` (+ `coverage.md`
+   if present); any **CRITICAL** — an acceptance criterion with no slice, a slice satisfying no
+   criterion, a contradiction across artifacts — **blocks `/rite-build`** until resolved. Then score
+   the three project gates as explicit **pass/fail** on the planned approach:
+   - **Principles** (`.devrites/principles.md`, rubric in [`principles.md`](../../rules/principles.md))
+     — the authored invariants the project will not break. A plan that bakes in a violation of a
+     declared principle with **no recorded, human-approved exception** is a **top-severity** finding,
+     walked **first**, and **blocks `/rite-build`**. Absent or empty file → none declared → passes;
+     **never block for the absence of principles**. A genuine need to break one routes to a scoped,
+     dated exception in the principles register — never a silent work-around (adding the exception is
+     an irreversible-risk decision: it always pauses for a human, even in AFK).
+   - **The anti-slop charter** (`coding-style.md` + `prose-style.md`) and **the conventions ledger**
+     (`.devrites/conventions.md`) — a plan that bakes in a god-module, a speculative abstraction with
+     no second caller, or a dependency where an in-repo option exists is a **top-severity** violation.
+   **Re-check all three after the axes harden the plan** (post-design). Write the result to `analysis.md`.
    ```bash
    A=.claude/skills/devrites-lib/scripts/analyze.sh
    [ -f "$A" ] || A="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/analyze.sh"
@@ -103,12 +115,31 @@ definition of done), `afk-hitl.md` (irreversible-risk list + gate ceiling).
    coverage-increasing findings auto-apply; **anything that grows scope or changes acceptance is a
    blocking pause**; irreversible-risk always pauses.)
 4. **Required outputs** — the test-coverage diagram + per-gap test requirements (the **regression
-   rule** is mandatory, no question), failure-mode table, "NOT in scope", "What already exists",
+   rule** is mandatory, no question). When the spec uses the structured grammar
+   (`spec-grammar.md`), the diagram maps **each `#### Scenario:` (WHEN/THEN) to ≥1 planned
+   test** — an unmapped scenario is a coverage gap the build must close. Then the failure-mode
+   table, "NOT in scope", "What already exists",
    and the worktree parallelization strategy. Shapes in [`reference/review-axes.md`](reference/review-axes.md).
+   **Developer-facing surface?** If the plan ships one (`developer-experience.md` — API / CLI / SDK /
+   webhook / config / error messages / getting-started), predict the DX scorecard: the time-to-hello-world
+   estimate plus the getting-started, error-message, and ergonomics friction the plan bakes in. Write it
+   to `devex.md` as the **prediction the boomerang measures against** at `/rite-prove` / `/rite-seal`.
+   Absent surface → skip, no `devex.md` (greenfield no-op, like the principles gate).
    Also a **PRP one-pass-implementable check** per slice brief (the build's pre-flight): confirm each
    slice's Consumes/Produces, Known-Gotchas, validation commands, and reuse targets are present and
    concrete — a brief that can't be built in one pass is a finding; harden the slice until it clears,
    before `/rite-build`.
+4a. **Forge gate (rare — confirm or clear).** For each slice carrying `Forge: yes` (proposed by
+   `/rite-define`), and any slice the architecture axis showed has **≥2 genuinely-viable approaches
+   with no clear winner at Complexity ≥4**, confirm the flag: name the 2–3 candidate strategies that
+   actually differ (different data shape, different seam, reuse-vs-build — not variations of one), and
+   confirm the slice's acceptance + `test-plan.md` give the judge an objective scorecard. **Clear**
+   `Forge: yes` back to `no` when the review settled on one approach, the slice is below the complexity
+   bar, or you can't name two real strategies — competing a decided or trivial slice burns K× the build
+   for nothing. Forge is a **build-cost** decision, not an irreversible one: it never bypasses a gate,
+   and under AFK its K candidates count against the slice budget. Record the confirmed strategies in
+   the slice brief so `/rite-build` competes them
+   ([`rite-build/reference/forge.md`](../rite-build/reference/forge.md)). No flagged slice → nothing to do.
 5. **Write `eng-review.md` + `test-plan.md`, fold back** — [`reference/artifacts.md`](reference/artifacts.md).
    `eng-review.md` is the durable record; `test-plan.md` is the build-readable coverage target
    (`/rite-build` and `/rite-prove` read it). Harden `plan.md` / `tasks.md` directly for
@@ -144,9 +175,10 @@ Depth: light | full (<trigger that escalated it>)
 Scope: reuse <n found> / minimum-diff <ok|trimmed N> / complexity <ok|smell: N files, M new services → asked>
 Axes (floor → verdict):  Architecture <band> · Code-quality <band> · Tests <band> · Performance <band>
 Findings: <Critical n / Important n / Suggestion n>   (suppressed low-confidence: n)
-Coverage: <x/y paths> planned · GAPS closed <n> · regressions flagged <n>  → test-plan.md
+Coverage: <x/y paths> planned (<s/t scenarios mapped | n/a>) · GAPS closed <n> · regressions flagged <n>  → test-plan.md
 Failure modes: <n> mapped (<n critical: no test + no handling + silent>)
 Parallelization: <n lanes — n parallel / n sequential> | sequential (no opportunity)
+Forge: <n slices flagged — strategies named | none>   (competed candidate builds at /rite-build)
 Reviewer loop: <n> iter · cross-model: ran (codex) | off
 Plan: hardened in place | <n> deltas routed via Spec Drift Guard → /rite-plan repair
 Next: /rite-build   (builds the vetted plan)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "DevRites — disciplined senior-engineer workflow skills pack for Claude Code",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",

package/scripts/check-cross-refs.py

@@ -29,7 +29,11 @@ WORKSPACE_ARTIFACTS = {
     "questions.md", "drift.md", "evidence.md", "browser-evidence.md", "touched-files.md",
     "review.md", "seal.md", "ship.md", "brief.md", "design-brief.md", "strategy.md",
     "polish-report.md", "handoff.md", "eng-review.md", "test-plan.md", "references.md",
+    # forge competition record (work/<slug>/forge-report.md) — written when a Forge: yes slice competes candidates
+    "forge-report.md",
     "conventions.md", "coverage.md", "analysis.md", "learnings.md",
+    # developer-experience scorecard (work/<slug>/devex.md) + project-level retro ledger (.devrites/retro.md)
+    "devex.md", "retro.md",
     # spec-quality checklists (.devrites/work/<slug>/checklists/<domain>.md)
     "functional.md", "data-model.md", "interaction.md", "non-functional.md", "edge-cases.md",
 }

package/scripts/run-behavioral-evals.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+# scripts/run-behavioral-evals.sh — validate the SHAPE of DevRites behavioral evals.
+#
+# Trigger evals (run-evals.sh) test whether the right skill *fires*. Behavioral
+# evals test whether a gating skill's discipline *holds under pressure* — does it
+# resist the rationalizations it documents in `rules/anti-patterns.md` (and its own
+# `reference/anti-patterns.md`), or does the agent talk itself past the gate. Each
+# scenario pairs a pressure prompt with the resistance a holding response shows and
+# the capitulation markers a failed one shows.
+#
+# This script is the DETERMINISTIC, zero-token CI gate — the analog of run-evals.sh's
+# schema path and spec-validate.sh: it checks that every behavioral eval is well-formed
+# so a malformed one can't reach the live grader. It does NOT invoke a model. Executing
+# the scenarios against a live Claude (does the skill actually resist?) is the labeled /
+# nightly rung documented in evals/behavioral/README.md.
+#
+# Usage:
+#   scripts/run-behavioral-evals.sh                                  # validate every evals/behavioral/*.json
+#   scripts/run-behavioral-evals.sh evals/behavioral/rite-prove.json # validate one file
+#
+# Exit: 0 all valid (or no behavioral evals present — opt-in, never a failure) ·
+#       1 shape violation(s) · 2 missing parser
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# Overridable so the test harness can exercise the opt-in no-op path against a
+# scratch directory; defaults to the real behavioral-eval set.
+BEHAVIORAL_DIR="${DEVRITES_BEHAVIORAL_DIR:-$ROOT/evals/behavioral}"
+
+if [[ $# -gt 0 ]]; then
+  FILES=("$@")
+else
+  if [[ ! -d "$BEHAVIORAL_DIR" ]]; then
+    echo "No evals/behavioral/ directory — behavioral evals are opt-in; nothing to validate."
+    exit 0
+  fi
+  FILES=()
+  while IFS= read -r f; do
+    [[ "$f" == */README.md ]] && continue
+    FILES+=("$f")
+  done < <(find "$BEHAVIORAL_DIR" -type f -name '*.json' | sort)
+fi
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  echo "No behavioral eval files — behavioral evals are opt-in; nothing to validate."
+  exit 0
+fi
+
+if command -v python3 >/dev/null 2>&1; then
+  PARSER="python3"
+elif command -v jq >/dev/null 2>&1; then
+  PARSER="jq"
+else
+  echo "Need python3 or jq to validate JSON." >&2
+  exit 2
+fi
+
+FAILED=0
+TOTAL=0
+SCENARIOS=0
+
+for file in "${FILES[@]}"; do
+  TOTAL=$((TOTAL + 1))
+  printf '== %s ==\n' "$file"
+
+  if [[ "$PARSER" == "python3" ]]; then
+    if OUT=$(python3 - "$file" <<'PY'
+import json, sys, pathlib
+path = pathlib.Path(sys.argv[1])
+try:
+    data = json.loads(path.read_text())
+except Exception as e:
+    print(f"  FAIL: INVALID JSON: {e}")
+    sys.exit(1)
+
+errors = []
+for key in ("skill", "description", "scenarios"):
+    if key not in data:
+        errors.append(f"missing top-level key: {key}")
+
+scenarios = data.get("scenarios", [])
+if not isinstance(scenarios, list):
+    errors.append("scenarios is not a list")
+    scenarios = []
+elif len(scenarios) == 0:
+    errors.append("scenarios is empty — a behavioral eval needs at least one")
+
+seen_ids = {}
+for i, s in enumerate(scenarios):
+    if not isinstance(s, dict):
+        errors.append(f"scenario[{i}] not an object")
+        continue
+    sid = s.get("id")
+    if not sid or not isinstance(sid, str):
+        errors.append(f"scenario[{i}] missing non-empty string id")
+    elif sid in seen_ids:
+        errors.append(f"scenario[{i}] duplicate id {sid!r} (also scenario[{seen_ids[sid]}])")
+    else:
+        seen_ids[sid] = i
+    where = sid or f"[{i}]"
+    # Non-empty string fields.
+    for k in ("rationalization", "pressure", "source"):
+        v = s.get(k)
+        if not isinstance(v, str) or not v.strip():
+            errors.append(f"scenario {where} missing non-empty {k}")
+    # Non-empty list-of-string fields.
+    for k in ("expected_resistance", "capitulation_markers"):
+        v = s.get(k)
+        if not isinstance(v, list) or len(v) == 0:
+            errors.append(f"scenario {where} missing non-empty {k} list")
+        elif not all(isinstance(x, str) and x.strip() for x in v):
+            errors.append(f"scenario {where} {k} has an empty / non-string entry")
+
+if errors:
+    for e in errors:
+        print(f"  FAIL: {e}")
+    sys.exit(1)
+
+print(f"  skill: {data['skill']}")
+print(f"  scenarios: {len(scenarios)}")
+print(f"__COUNT__ {len(scenarios)}")
+PY
+    ); then rc=0; else rc=$?; fi
+  else
+    if OUT=$(jq -r '
+      if (.skill and .description and (.scenarios|type=="array") and (.scenarios|length > 0)) then
+        ( [ .scenarios[]
+            | select(
+                ((.id|type=="string") and (.id|length>0))
+                and ((.rationalization|type=="string") and (.rationalization|length>0))
+                and ((.pressure|type=="string") and (.pressure|length>0))
+                and ((.source|type=="string") and (.source|length>0))
+                and ((.expected_resistance|type=="array") and (.expected_resistance|length>0))
+                and ((.capitulation_markers|type=="array") and (.capitulation_markers|length>0))
+              ) ] | length
+        ) as $ok
+        | if $ok == (.scenarios|length)
+          then "  skill: \(.skill)\n  scenarios: \(.scenarios|length)\n__COUNT__ \(.scenarios|length)"
+          else "  FAIL: \((.scenarios|length) - $ok) scenario(s) missing required fields"
+          end
+      else
+        "  FAIL: missing required keys or empty scenarios"
+      end
+    ' "$file"); then rc=0; else rc=$?; fi
+  fi
+
+  COUNT=$(printf '%s\n' "$OUT" | sed -n 's/^__COUNT__ //p')
+  OUT=$(printf '%s\n' "$OUT" | grep -v '^__COUNT__' || true)
+  printf '%s\n' "$OUT"
+
+  if [[ ${rc:-0} -ne 0 ]] || [[ "$OUT" == *"FAIL"* ]]; then
+    FAILED=$((FAILED + 1))
+  else
+    SCENARIOS=$((SCENARIOS + ${COUNT:-0}))
+  fi
+done
+
+echo
+printf 'Validated %d behavioral eval file(s); %d scenario(s); %d failed.\n' "$TOTAL" "$SCENARIOS" "$FAILED"
+
+if [[ $FAILED -gt 0 ]]; then
+  exit 1
+fi
+
+echo
+echo "Note: this is shape validation only — it does not execute the scenarios."
+echo "To grade whether the skills actually resist under pressure (live model):"
+echo "  see evals/behavioral/README.md — the labeled / nightly rung."
+exit 0

package/scripts/run-evals.sh

@@ -26,6 +26,9 @@ else
   FILES=()
   while IFS= read -r f; do
     [[ "$f" == */README.md ]] && continue
+    # Behavioral evals have their own schema + validator (run-behavioral-evals.sh);
+    # they are not 20-query trigger evals, so keep them out of this scan.
+    [[ "$f" == */behavioral/* ]] && continue
     FILES+=("$f")
   done < <(find "$EVALS_DIR" -type f -name '*.json' | sort)
 fi

package/scripts/validate.sh

@@ -14,7 +14,7 @@ good() { printf 'ok: %s\n' "$*"; }
 
 PUBLIC="rite rite-spec rite-adopt rite-temper rite-define rite-vet rite-plan rite-build rite-prove rite-polish rite-review rite-seal rite-ship rite-status rite-doctor rite-resolve rite-pressure-test rite-zoom-out rite-prototype rite-handoff rite-autocomplete"
 INTERNAL="devrites-interview devrites-source-driven devrites-doubt devrites-ux-shape devrites-frontend-craft devrites-browser-proof devrites-debug-recovery devrites-api-interface devrites-audit"
-AGENT_FILES="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-strategy-reviewer devrites-plan-reviewer devrites-slice-wright"
+AGENT_FILES="devrites-spec-reviewer devrites-code-reviewer devrites-test-analyst devrites-frontend-reviewer devrites-security-auditor devrites-performance-reviewer devrites-devex-reviewer devrites-doubt-reviewer devrites-simplifier-reviewer devrites-strategy-reviewer devrites-plan-reviewer devrites-retrospector devrites-slice-wright"
 
 # ---- 1. bash -n on every shell script ------------------------------------
 section "bash syntax (bash -n)"