devrites 2.2.0 → 2.4.0

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

@@ -1,6 +1,6 @@
 ---
 name: rite-learn
-description: Review the auto-captured learning ledger and promote recurring lessons to project rules — the human-gated half of the cross-feature learning loop. Capture is automatic (`/rite-seal` appends dismissed-finding classes + dead-ends to `.devrites/learnings.md` on every GO; the review skills load it before a fan-out), so the system learns without a command; this skill mines that ledger across features and decides which recurring lessons graduate into a rule (propose, don't impose). Use when the user says "what have we learned", "rite learn", "harvest lessons", "promote our learnings", or after several features ship. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
+description: Review the auto-captured learning ledger and promote recurring lessons to project rules or principles — the human-gated half of the cross-feature learning loop. Capture is automatic (`/rite-seal` appends dismissed-finding classes + dead-ends to `.devrites/learnings.md` on every GO; the review skills load it before a fan-out), so the system learns without a command; this skill mines that ledger across features and decides which recurring lessons graduate into a rule (propose, don't impose). Use when the user says "what have we learned", "rite learn", "harvest lessons", "promote our learnings", or after several features ship. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
 argument-hint: "[--mine | \"<lesson to record>\"]"
 user-invocable: true
 disable-model-invocation: true
@@ -45,6 +45,11 @@ it never edits source or rule files on its own.
    you could swap onto any project says nothing).
 3. **Classify each candidate** into its durable home:
    - **project rule** — a craft/standard that belongs in a `.claude/rules/*` file or `CLAUDE.md`.
+   - **project principle** — a recurring correction that is really a *non-negotiable invariant*
+     (not just an idiom or a craft standard): graduate it to `.devrites/principles.md`
+     ([`principles.md`](../../rules/principles.md)). This is the **trusted, gating** layer — higher
+     stakes than a rule — so `/rite-learn` **drafts** the principle + a dated Governance entry for
+     the human to confirm; it never writes a principle silently.
    - **conventions-ledger entry** — a proven project idiom for `.devrites/conventions.md`.
    - **dismissed-finding class** — a pattern reviewers keep flagging that is *intentional here*;
      recording it stops the recurring false positive (`learnings.md`, loaded pre-fan-out).
@@ -53,9 +58,12 @@ it never edits source or rule files on its own.
    times, the proposed home) via `AskUserQuestion` — the human picks which to promote. Never
    promote a lesson to a rule silently; an unproven "lesson" hardened into a rule is its own slop.
 5. **Record the accepted.** For each the user accepts, append it with `learnings.sh add <slug>
-   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule** or
-   **ledger** promotion, draft the exact edit and let the user confirm it through the normal flow
-   — `/rite-learn` writes the ledger, not the rule files. Then `touch .devrites/.learnings-reviewed`
+   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule**,
+   **principle**, or **ledger** promotion, draft the exact edit and let the user confirm it through
+   the normal flow — `/rite-learn` writes the ledger, not the rule or principle files. A
+   **principle** promotion is the highest-stakes of these: draft the `.devrites/principles.md` entry
+   **plus its dated Governance line**, and let the human confirm before it lands — a principle is a
+   gate, so it is amended deliberately, never auto-written. Then `touch .devrites/.learnings-reviewed`
    so the SessionStart learnings nudge snoozes until new signal accumulates.
 
 ## How the ledger is used
@@ -66,6 +74,11 @@ convention** raises the bar. The ledger is an **untrusted prior** — a fresh ob
 live code always overrides a ledger entry (see `.claude/rules/security.md`). Confidence in a
 recorded lesson never raises its authority.
 
+A **project principle** (`.devrites/principles.md`) is the opposite layer — prescriptive,
+trusted, and **gating**. Promoting a lesson there is a deliberate amendment, not a prior the next
+fan-out can override: a violation becomes a blocking finding, not a suppressed false positive.
+That asymmetry is why principle promotion is human-confirmed and dated, never auto-written.
+
 ## Gotchas
 - Evidence first: a lesson without ≥2 real occurrences is speculation. Cite the features.
 - Don't pad the ledger. Five real lessons that change behaviour beat thirty rubber-stamped rows.

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

@@ -49,7 +49,9 @@ don't load both up front.
 4. **If UI scope detected** read [`reference/ui.md`](reference/ui.md), and read
    `design-brief.md` if present (the UX/UI contract `devrites-ux-shape` shaped at spec and
    `devrites-frontend-craft` refined while building) so the polish honors the agreed
-   direction + states. Then run
+   direction + states. **Read the `## Visual Verdict` table in `browser-evidence.md` if present:
+   its `FAIL` and `PARTIAL` rows are the normalize/quality-bar worklist** — fix the root cause of
+   each (a missing state, an off-token CTA, an anti-slop hit), don't decorate around it. Then run
    **Phase 3 (normalize)** → **Phase 4 (UI polish)**. Honor argument modes:
    - `bolder | quieter | distill | harden` — passed to Phase 4 as the
      emphasis dial.

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

@@ -36,9 +36,14 @@ the affected criteria/routes to refresh proof before `/rite-seal`.
 **Step 0:** Read `.claude/rules/core.md` first. The other rule files load on demand;
 pull these via `Read` when relevant:
 - `testing.md` — pyramid, determinism, no-flake discipline.
+- `spec-grammar.md` — when the spec uses structured `### Requirement:` / `#### Scenario:`
+  blocks, each scenario (WHEN/THEN) is one observable behavior to walk and prove.
 - `performance.md` — measure first when perf is in scope.
 - `observability.md` — when the change has a runtime surface (endpoint, job, integration,
   user flow): telemetry must be present **and observed to emit**, not assumed.
+- `developer-experience.md` — when the change ships a developer-facing surface (API / CLI / SDK /
+  webhook / config / error messages / getting-started): **measure** the DX scorecard (run the flow,
+  time time-to-hello-world, capture the verbatim error text), don't assert it.
 
 ## Operating rules
 - Evidence over confidence. Feature scope only — fix within the feature or record a
@@ -71,7 +76,19 @@ pull these via `Read` when relevant:
    (`devrites-browser-proof`): routes, viewports, screenshots (opened + described),
    console, network, interaction paths, and design-reference match if references exist.
 5. **Map results to acceptance** — walk `spec.md` acceptance criteria; note which are now
-   proven and which aren't. If `test-plan.md` exists, also walk its acceptance→test map and
+   proven and which aren't. **If the spec uses the structured grammar** (`### Requirement:` /
+   `#### Scenario:` blocks — `spec-grammar.md`), walk it **per scenario**: each `#### Scenario:`
+   WHEN/THEN is one observable behavior that needs a passing asserting test (the WHEN is the
+   arrange, the THEN the assert). A scenario with no covering result is an unproven gap =
+   blocker, the same standing as an uncovered acceptance criterion. Re-run the grammar gate
+   first so a requirement hand-edited to malformed since `/rite-spec` can't masquerade as proven:
+   ```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-validate rc=$?"; } || true
+   ```
+   If `test-plan.md` exists, also walk its acceptance→test map and
    per-gap requirements — a planned test (especially a regression-Critical) with no covering
    result is an unproven gap, not a pass. **Also walk the test-plan interaction inventory**
    (every interactive element + user flow): each must have a passing asserting test. An
@@ -107,6 +124,16 @@ pull these via `Read` when relevant:
    span actually emits, and record that observation in `evidence.md`. Instrumentation never seen
    emitting is unproven, not done. Skip entirely for pure-internal / docs / config / type-only
    changes — don't instrument a typo fix.
+5c. **Developer-experience measure (developer-facing surface only).** If the feature ships a public
+   API, CLI, SDK/library, webhook, config/env contract, error/exit path, or the getting-started flow
+   (`developer-experience.md`), **exercise it** rather than reading it: run the getting-started steps
+   on a clean state and **time time-to-hello-world**; invoke the CLI `--help` / call the endpoint /
+   import the package; trigger the failure path and capture the **verbatim** error text. For a docs or
+   quickstart page, capture it through the browser-proof ladder (`devrites-browser-proof`) and describe
+   the screenshot. Write the **measured** scorecard to `devex.md` (beside the `/rite-vet` prediction the
+   boomerang reconciles at `/rite-seal`) and the headline numbers + error strings to `evidence.md`. A
+   scorecard from "the code looks fine" is Source mode, not proof. Skip entirely when no developer-facing
+   surface is in scope — don't DX-measure an internal refactor.
 6. **On failure** → [failure-triage](reference/failure-triage.md) +
    `devrites-debug-recovery`. Reproduce → isolate → fix within scope → re-run; if a fix
    would exceed scope, record a blocker.
@@ -120,9 +147,11 @@ pull these via `Read` when relevant:
 ```
 Proved: <feature>
 Acceptance criteria proven: <n / total>
+Scenarios proven: <n / total | n/a (flat acceptance)>
 Tests:  <cmd → pass/fail (counts)>
 Build:  <cmd → pass/fail>   Lint: <cmd → pass/fail>
 Browser: <ladder rung used + summary | n/a>
+DevEx:  <measured TTHW + getting-started/error-message verdict → devex.md | n/a (no dev-facing surface)>
 Unresolved failures / blockers: <none | list>
 Next: /rite-polish   (finish the feature → /rite-review → /rite-seal)
 ↻ Hygiene: /clear before /rite-polish (evidence.md + browser-evidence.md captured; debug trails noisy). See rules/context-hygiene.md.

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

@@ -23,6 +23,9 @@ express lane:**
 - **Ambiguous scope** — you'd have to guess what "done" means, or the ask hides a design
   decision (data model, new dependency, second design system).
 - Security-sensitive input handling, or a measurable performance-critical path.
+- Would **break a declared project principle** (`.devrites/principles.md`) with no recorded,
+  human-approved exception — the express lane never relaxes a project gate; a needed exception is
+  a deliberate human decision, so route it to `/rite-spec`.
 
 If none hold, the change is small + reversible + unambiguous → proceed. **When in doubt,
 escalate** — the cost of the full lifecycle on a small change is minutes; the cost of the
@@ -34,6 +37,7 @@ Read `.claude/rules/core.md` first. Then the small set this lane actually needs:
 - `testing.md` — TDD, **completeness** (every touched behavior/element asserted) +
   **assertion strength** (no tautological tests; see it fail first), scaled to the change.
 - `error-handling.md` / `security.md` — only if the change touches input/errors.
+- `principles.md` — when `.devrites/principles.md` exists; a change that breaks an invariant is a gate, not a quick fix.
 
 ## Workflow
 0. **Orient.** Read `core.md`. If a `.devrites/` workspace is active, run the preamble to
@@ -53,10 +57,11 @@ Read `.claude/rules/core.md` first. Then the small set this lane actually needs:
 4. **Prove (scoped).** Run the **targeted** tests + typecheck / lint for what changed (not
    the whole suite) → green. Record the command + output. A tautological test that can't
    fail is not proof.
-5. **Review-lite + ship.** Self-review the diff (correctness, scope, idiom — one pass, no
-   subagent fan-out). Show the diff, then on the user's confirm commit it (Conventional
-   Commits, atomic) — or hand to `/rite-ship` if a workspace is active. **Never push without
-   the user asking.**
+5. **Review-lite + ship.** Self-review the diff (correctness, scope, idiom, and — if
+   `.devrites/principles.md` exists — no declared invariant broken; this is `/rite-frame`'s AUDIT
+   pass — one pass, no subagent fan-out). Show the diff, then on the user's confirm commit it
+   (Conventional Commits, atomic) — or hand to `/rite-ship` if a workspace is active. **Never push
+   without the user asking.**
 
 ## Escalation (mid-flight) — the Spec Drift Guard still applies
 If the "small" change turns out to be not small — a second slice appears, a real design

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,8 +38,11 @@ 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. |
+| `doubt-coverage` rc=1, or a stood decision (boundary / data-model / auth / public-API / migration / branching) recorded in `decisions.md` with no `devrites-doubt` verdict | **Important** — and **NO-GO** when the undoubted decision is an irreversible-risk class (auth / public-API / migration), the same standing as an unproven acceptance criterion. `/rite-build` step 4 records the verdict + logs a `doubt` footprint; absence here means doubt was skipped. Genuinely-empty `Decisions stood` on every slice is a valid pass — confirm, don't assume. |
 
 ## Workflow
 1. **Run the shared orientation preamble** — it prints `state.md`, the artifacts present,
@@ -53,7 +57,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,20 +67,49 @@ 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
    definition); a slice marked `built (pending review)` is not done.
+4a. **Doubt coverage — every stood decision was independently doubted.** Run the deterministic
+   check, then judge it against `decisions.md`:
+   ```bash
+   DC=.claude/skills/devrites-lib/scripts/doubt-coverage.sh
+   [ -f "$DC" ] || DC="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/doubt-coverage.sh"
+   [ -f "$DC" ] || DC=pack/.claude/skills/devrites-lib/scripts/doubt-coverage.sh
+   [ -f "$DC" ] && { bash "$DC" <slug>; echo "doubt-coverage rc=$?"; } || echo "(doubt-coverage gate unavailable — confirm by hand each stood decision carries a devrites-doubt verdict)"
+   ```
+   The script proves the **footprint half** (a `doubt` dispatch was logged per `/rite-build`
+   step 4); you prove the **verdict half**: every decision in `decisions.md` that crosses a doubt
+   trigger (boundary / data-model / auth / public-API / migration / branching / "safe" / "scales")
+   must carry a recorded `devrites-doubt` verdict — `accept`, or a `reject` whose required changes
+   were resolved. Per the severity gate: **rc=1 or a triggering decision with no verdict is an
+   Important finding**, escalating to **NO-GO** when the undoubted decision is irreversible-risk
+   (auth / public-API / migration). A genuinely-empty `Decisions stood` across every slice passes —
+   confirm it against `decisions.md`, don't assume it.
 5. Check **security, data, migration, rollback** risk —
    [risk-and-rollback](reference/risk-and-rollback.md). If `strategy.md` exists (from
    `/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 +131,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-seal/reference/anti-patterns.md

@@ -16,6 +16,7 @@ see [rules/anti-patterns.md](../../../rules/anti-patterns.md).
 | "Drift is small; resolve it inline and seal." | Unresolved drift = NO-GO, no exceptions. Route through `/rite-plan` to repair, then seal. |
 | "Reviewer findings overlap; average them away." | Surface disagreements explicitly. Averaging hides where the reviewers actually disagree. |
 | "Carry the old reviewer verdicts though the diff changed." | If the diff changed since `/rite-review`, re-run the Spec + Code axes — don't carry stale verdicts forward. |
+| "Build never doubted a decision, but the wright seemed confident — GO without checking." | Doubt is a gate, not a vibe. `doubt-coverage` rc=1 — or a stood boundary / data-model / auth / public-API / migration decision in `decisions.md` with no recorded `devrites-doubt` verdict — is an Important finding, escalating to NO-GO when the undoubted decision is irreversible-risk (auth / public-API / migration). An empty `Decisions stood` on every slice passes only when confirmed against `decisions.md`, never assumed. |
 
 ## Red Flags
 
@@ -25,3 +26,4 @@ see [rules/anti-patterns.md](../../../rules/anti-patterns.md).
 - `seal.md` written before walking *every* acceptance criterion one by one.
 - A NO-GO rounded up to GO "to be agreeable".
 - Unresolved drift, unresolved questions, or pending tasks — and you're sealing anyway.
+- `doubt-coverage` rc=1 left unexamined, or a stood irreversible-risk decision (auth / public-API / migration) carrying no recorded `devrites-doubt` verdict — and you're sealing GO anyway.

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.4.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",
 }