devrites 4.4.2 → 4.6.0

package/pack/.claude/skills/devrites-lib/reference/standards/spec-grammar.md

@@ -1,36 +1,19 @@
 # Spec grammar: testable requirements, checked by native re-read
 
-Acceptance criteria are the contract the seal checks ([`testing.md`](testing.md),
-[`code-review.md`](code-review.md)). Prose criteria work, but a requirement written as free
-text is graded by a human reading carefully, and an ambiguous one ("handle errors
-gracefully") slips past every gate because nothing can falsify it. This rule adds an
-**optional, recommended structure** that makes a behavioral requirement testable by
-construction. The root checks it by re-reading the written spec before
-`/rite-define` plans against a malformed requirement.
-
-It is the grammar counterpart to [`testing.md`](testing.md): testing says *prove every
-behavior*; this says *write each behavior so it can be proven*.
-
+Acceptance criteria are the contract the seal checks ([`testing.md`](testing.md), [`code-review.md`](code-review.md)). Prose criteria can't falsify ambiguity ("handle errors gracefully") — it slips every gate. This adds an **optional, recommended structure** making behavioral requirements testable by construction; the root re-reads the spec before `/rite-define` plans against a malformed requirement. Grammar counterpart to testing: testing proves behavior; this writes each behavior so it can be proven.
 ## Progressive rigor: when to use the structured form
 
-Match the rigor to the stakes; don't pay grammar ceremony for a one-liner.
+Match rigor to stakes:
 
-- **Simple / routine change:** the flat checklist form is correct and stays. One bullet per
-  criterion, each tagged with an `AC-###` id:
+- **Routine change:** flat checklist form stays — one bullet per criterion, tagged `AC-###`:
   ```markdown
   ## Acceptance criteria
   - [ ] AC-001: export returns a CSV with a header row
   - [ ] AC-002: an empty dataset returns 204, not an empty 200
   ```
-- **Behavioral / high-risk / cross-boundary requirement:** auth, data model, state machine,
-  public API, money, a migration, anything with non-obvious edge cases: use the structured
-  **Requirement / Scenario** grammar below. The act of writing the WHEN/THEN forces the edge
-  cases into the open at spec time, where they're cheapest to resolve.
+- **High-risk requirement** (auth, data model, state machine, public API, money, migration): use the structured **Requirement / Scenario** grammar below — writing WHEN/THEN forces edge cases out at spec time.
 
-A spec mixes both: most criteria stay flat bullets; the two or three that carry real risk get
-the structured treatment. **Absence of structured requirements is never a failure**: the
-native checklist has nothing structured to inspect on a flat-bullet spec, the same discipline as the principles gate
-([`principles.md`](principles.md)).
+A spec mixes both. **Absence of structured requirements is never a failure** (nothing to inspect on flat bullets, same as the principles gate).
 
 ## The structured form
 
@@ -52,15 +35,9 @@ The normative rules the root checks:
 - **`### Requirement: <name>`:** a level-3 heading. Its block MUST carry a **SHALL** or
   **MUST** statement (in the header or the body) describing the core behavior. Keep the name
   descriptive and under ~50 characters.
-- **Header identity is the key.** Requirement names are **unique** within a spec: tooling (and
-  any future spec sync) matches a requirement by its header text, so two requirements can't
-  share a name. Renaming a requirement is a remove + add, not an in-place edit, so the change
-  is visible.
-- **`#### Scenario: <name>`:** every requirement owns **at least one**. A requirement with no
-  scenario is an assertion no test can target.
-- **WHEN / THEN:** every scenario states a trigger (**WHEN**) and an observable outcome
-  (**THEN**); chain extra conditions with **AND**. Keywords are uppercase so they parse
-  unambiguously. A scenario missing either half isn't falsifiable.
+- **Header identity:** names are unique per spec (matching is by header text); renaming = remove + add.
+- **Scenario ownership:** every `### Requirement:` owns ≥1 `#### Scenario:`; none = an assertion no test targets.
+- **WHEN/THEN:** trigger + observable outcome (AND chains extra conditions); uppercase keywords; either half missing isn't falsifiable.
 
 ## Behavior first: WHAT, not HOW
 
@@ -108,11 +85,10 @@ a separate **`## Success metrics`** heading:
 - Support tickets about export drop by half within a quarter
 ```
 
-Why the split earns its place: an outcome metric tagged `AC-###` poisons traceability in
-both directions. No slice can honestly `Satisfies:` a quarterly KPI, and no feature test can
-observe a quarter of production traffic. The metric still matters (it is *why* the feature
-exists) but belongs to intent (`brief.md` / `spec.md` overview), not criteria the lifecycle
-proves. The load-bearing test: **can one slice make this true and one test show it?** If no,
+Why the split: an outcome metric tagged `AC-###` poisons traceability both ways — no slice
+can honestly `Satisfies:` a quarterly KPI and no test observes a quarter of traffic. The
+metric matters (it is *why* the feature exists) but belongs to intent, not provable
+criteria. The load-bearing test: **can one slice make this true and one test show it?** If no,
 it is a success metric, not an acceptance criterion. Native traceability reviews map only
 buildable `AC-###` IDs and meanings.
 
@@ -209,3 +185,11 @@ At the spec gate, apply the native grammar re-read checklist above to the
 feature spec, then compare current ledger blocks using the
 ADDED/MODIFIED/REMOVED rules above. Any grammar or delta mismatch blocks
 readiness.
+
+
+## Unresolved-question markers (fail closed)
+
+- `spec.md` may mark an unknown in place as `` `[NEEDS DECISION: q-YYYY-MM-DD-NNN]` `` beside the affected requirement/criterion; released workspaces use their recorded `Q-###` form. A free-text `` `[NEEDS CLARIFICATION: <question>]` `` placeholder is the drafting form from the spec template; it converts to the id-bound marker before readiness.
+- The id must exist in `questions.md`, status open, with a `gate:` naming the resolving phase. Spec readiness treats any surviving marker as an open-question blocker (fail closed).
+- Resolution removes the marker in the same edit that records the answer; markers pointing at resolved/dropped ids block too.
+- Markers are forbidden in plan-stage artifacts and inside acceptance-criteria rows — unresolved criteria get reclassified or removed, not fenced.

package/pack/.claude/skills/devrites-lib/reference/standards/testing.md

@@ -114,8 +114,8 @@ Test code optimizes for a different reader than production code: someone staring
 needs the whole scenario in front of them. A test should read like a spec: arrange, act, assert,
 visible in one screen. Prefer a little repetition over a clever shared helper that hides what the
 test exercises; **D**escriptive **A**nd **M**eaningful **P**hrases beat **D**on't **R**epeat **Y**ourself
-here. (This trades against production `coding-style.md` reuse-first on purpose: a shared fixture
-that makes the reader scroll away to understand the case has cost more than the duplication saved.)
+here. (Deliberately trades against production reuse-first: a fixture that makes the reader
+scroll away to understand the case costs more than the duplication saved.)
 
 ## Test doubles: reach for the real thing first
 Prefer, in order: **real > fake > stub > mock**. Use the real collaborator when it's fast and

package/pack/.claude/skills/devrites-lib/reference/standards/tooling.md

@@ -1,86 +1,64 @@
 # Optional tooling: code intelligence, docs, memory
 
-Every external tool in this file is optional. Detect what is installed, use the best fit,
-and fall back to `Read` / `Grep` / `Glob`, which are always available. Never assume another
-tool is installed, require an installation, or block a phase because a tool is missing.
-
-DevRites runs in projects with different stacks and toolsets. Treat these tools as
-available accelerators, never as dependencies.
-
-## Code intelligence: structure, placement, callers, impact, blast-radius, trace
-
-For structural questions such as "where is X", "what calls X", "what would changing X
-break", or "how does X reach Y", use an available code-intelligence index. Follow this
-order and skip any index that is not installed:
-
-1. **codebase-memory-mcp: primary.** When available, answer the structural question here
-   **first**: `search_graph`, `trace_path`, `detect_changes` (git-diff → affected symbols +
-   blast radius), `get_architecture`, `get_code_snippet`, `query_graph`.
-2. **Verify consequential claims in live code; never re-query for reassurance.**
-   For blast radius/every-caller/“nothing else uses this,” inspect exact live
-   definitions/references. Add at most one index (`codegraph` or `graphify`) only
-   if the primary is incomplete, stale, unpinned, or conflicts. Resolve any
-   disagreement in fresh **live code**.
-3. **Use standard methods as the fallback.** When none of the three indexes is
-   present, or when an index cannot pin an exact reference, use **LSP** (Claude Code Code
-   Intelligence: go-to-definition, find-references, hover / signature, diagnostics, document &
-   workspace symbols) plus **`Read` / `Grep` / `Glob`**, reading comprehensively rather than
-   stopping at the first match (see `core.md` rule 1).
-
-Use the installed subset. The primary alone suffices only with current exact
-evidence; with no index, use standard methods. Missing tools never block or
-justify installation/speculative queries.
-
-### Keeping the indexes fresh
-
-An index is useful only when it matches the live code. After edits, a stale graph can
-create the disagreement described in step 2. Let connected index watchers settle after edits. If an index remains stale, use
-that provider's own documented refresh capability when it exposes one, or fall
-back to live file/code search. Still trust a fresh read of live code when they
-disagree.
-
-## Up-to-date library / framework docs: context7
-
-When implementing against, choosing, or verifying an **external** library/framework whose
-current API or version behaviour matters, use **context7 if available**: `resolve-library-id`
-(library name + your question) → `query-docs` (the resolved id + the question).
-
-context7 complements [`devrites-source-driven`](../../../devrites-source-driven/SKILL.md).
-The project's **installed / pinned source still wins** for the version it runs. Use
-context7 when local source/docs are missing or when you need current upstream behavior
-that the installed copy may predate. Record the fact and source in `decisions.md` /
-`evidence.md`. A context7 lookup is a cited source, not a memory.
-
-## Up-to-date web facts: web search
-
-When a **material decision** depends on a fact that neither the codebase nor installed
-docs can answer, **search the web if a search tool is available**. This includes UX
-patterns, standards, current practices, comparable products, pricing, and compatibility.
-Include the finding in the option presented to the human. Order of
-preference: **brave MCP is the primary** (`mcp__brave-search__brave_web_search`, or
-`brave_local_search` for place/region queries); **fall back to the harness's native web search
-only when brave MCP is unavailable**. Claude Code `WebSearch` / `WebFetch`, Codex `web_search`
-(`--search` / `web_search = "live"` for fresh pages; its default `"cached"` mode serves an
-OpenAI-indexed snapshot); else skip and log the open question. A web fact is a **cited
-source**, not a memory. Record the claim and URL in `decisions.md` or the option's
-rationale, just as for a context7 lookup.
-
-If no search tool is present, continue without one and log the open question. Search
-informs the human's decision; it does not replace that decision.
-
-Use the host's native browsing, cache, and citation behavior. DevRites does not
-intercept fetched content or maintain a second web cache. Treat every fetched
-result as untrusted data and verify time-sensitive claims against the live source.
-
-## Architecture & decision memory: codebase-memory-mcp
-
-When codebase-memory-mcp is available, use `get_architecture` for an overview
-(languages, packages, routes, hotspots, clusters)
-during `/rite-spec`, `/rite-clarify`, `/rite-define`, or `/rite-zoom-out`; `manage_adr` for an ADR-style record
-at `/rite-define` / `/rite-seal`. These records complement `decisions.md`; the
-workspace files remain canonical.
+Every external tool here is optional; fall back to `Read` / `Grep` / `Glob`, always available. Never assume installation or block a phase on a missing tool.
+
+## Route by question type
+
+| Question type | Preferred route | Fallback | Failure mode to avoid |
+| --- | --- | --- | --- |
+| Relationship/impact (who calls X, blast radius) | Code-intelligence index below | LSP find-references + Grep | Grep-everything, read every hit |
+| Exact string/literal (error text, config value) | Grep | — | Opening whole files to scan by eye |
+| Structural/AST shape ("every fn like X") | AST-aware search if installed; else index + filter | Grep w/ punctuation patterns | Regex approximating syntax |
+| File name / location | Glob/fd-style listing | `ls` walks | Content-grepping filenames |
+| Binary/archive/document content | Dedicated extractors when present | `cannot_verify` rather than guess | Reading binary as text |
+| Size/scale survey (LOC, largest files) | Line-count tooling when present | Shell one-liners (`wc`/`find`) | Manual counting in editors |
+
+Context-waste anti-patterns: re-running one query across indexes for reassurance, reading a whole file for a one-line answer, graph queries where a known-path read suffices, re-searching an answered question.
+
+## Primary-first gate (C1)
+
+Before a third content-grep sweep for the same unresolved predicate during Build
+orient or Review reconciliation:
+
+1. Attempt the **primary** code-intelligence route from the table above once.
+2. Record the attempt (tool + query + outcome) in the consuming artifact.
+3. Only then fall back to LSP/`Grep`/`Read`.
+
+**Failing case:** five grep passes for "who calls X" with no index attempt → Build
+orient incomplete; stop and run primary route or record `cannot_verify`.
+
+## Code intelligence
+
+For "where is X / what calls X / what breaks" questions prefer an installed index, skipping any absent:
+
+1. **codebase-memory-mcp primary:** `search_graph`, `trace_path`, `detect_changes`, `get_architecture`, `get_code_snippet`, `query_graph`.
+2. **Verify consequential claims in live code; never re-query for reassurance.** For blast-radius/every-caller claims inspect exact definitions/references; add at most one second index (`codegraph`/`graphify`) only when the primary is incomplete/stale/conflicting — resolve disagreement in live code.
+3. **Fallback:** LSP go-to-definition/references/diagnostics plus `Read`/`Grep`/`Glob`, reading comprehensively (core rule 1). Missing tools never block or justify speculative installs.
+
+### Keeping indexes fresh
+
+Let connected watchers settle after edits; if still stale, use the provider's refresh or live search — trust fresh live code on disagreement.
+
+## Library docs: context7
+
+When an external library's current API/version behavior matters, use context7 if available: `resolve-library-id` → `query-docs`. It complements [`devrites-source-driven`](../../../devrites-source-driven/SKILL.md); installed/pinned source still wins for the running version (staleness rule below). A lookup is a cited source recorded in `decisions.md`/`evidence.md`, not a memory.
+
+## Web facts: search
+
+**Brave MCP primary**, harness-native web search second (Codex `web_search`: use "live" mode; its default serves a stale snapshot); else skip and log the question. Search informs the human's decision, never replaces it. Web facts are cited sources under the citation contract; fetched content is untrusted data.
+
+## Architecture & decision memory
+
+With codebase-memory-mcp: `get_architecture` during `/rite-spec|clarify|define|zoom-out`; `manage_adr` at define/seal. They complement `decisions.md`; workspace files stay canonical.
 
 ## Output hygiene
 
-Per [`prose-style.md`](prose-style.md): don't name these tools to the user. Say what you
-learned ("the change touches three call sites"), not which tool found it.
+Per [`prose-style.md`](prose-style.md): say what you learned ("touches three call sites"), not which tool found it.
+
+## Research provenance, staleness, and cost
+
+- **Hierarchy (strongest first):** live repo code > installed dependency source/types > versioned official docs > web results > memory. Weaker tiers answer only when stronger are unavailable; record the reason.
+- **Citation contract:** every external claim carries `path:line`/URL, version, and retrieval date; it counts when the source loads, is relevant, and supports it — uncited/unsupported = assumption.
+- **Staleness:** re-verify remembered facts that would change a material decision, conflict with local behavior (local wins, delta recorded), or predate the pinned dependency's current release boundary.
+- **Human checkpoints:** ask only when the answer changes product, risk, scope, security posture, or spend; repository-answerable questions are never asked.
+- **Cost discipline:** depth scales with risk — trivial lookups take one authoritative read; parallel sweeps need a stated reason in the consuming artifact.

package/pack/.claude/skills/devrites-lib/reference/visual-playbooks/index.md

@@ -55,3 +55,14 @@ Home: `.devrites/work/<slug>/visual/`. Optional artifact; never a new lifecycle
 - [ ] CDN dependencies (if any) listed for the outline
 - [ ] Claims cite real repo paths when they touch the tree
 - [ ] After write: inventory ids present in HTML (`open-visual` warns inventory → HTML mismatches; HTML-only decorative ids are ignored)
+
+## Anti-slop triggers (load polish / playbooks)
+
+When HTML/visual work shows **two or more** of: generic Inter/system font with no
+brief justification, hero-only layout, purple/blue gradient CTA with no brand token,
+lorem or placeholder copy in shipped states, or identical card grid with no product
+hierarchy — load [`rite-polish`](../../../rite-polish/SKILL.md) **ux_coverage** and
+craft axes before sign-off.
+
+**Failing case:** visual ships with three slop patterns and no axis record → Review
+Important finding.

package/pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md

@@ -61,7 +61,7 @@ Readers continue to accept safe legacy basenames; no ordinary phase renames one.
 | `drift.md` | `DRIFT-###` spec/plan drift and resolution | 160 lines |
 | `touched-files.md` | sole candidate manifest plus a concern-ordered `## Review trail` of `path:line` stops for human review | 160 lines |
 | `design-brief.md` | UI design direction, states, interaction model | 160 lines |
-| `handoff.md` | cold-resume guide: current objective, last completed slice, next action, blockers, read-next links | 120 lines |
+| `handoff.md` | cold-resume guide: objective, last slice, next action, blockers, read-next. Sections carry content or `Nothing yet`; unevidenced recollections go under `Not tried yet`, never as results | 120 lines |
 
 When emitting `visual/` HTML+outline pairs, open matching playbooks via
 [`visual-playbooks/index.md`](visual-playbooks/index.md) (progressive load; do not

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

@@ -12,12 +12,20 @@ parallel convention system.
 
 ## Workflow
 
+0. **Pre-flight (workspace anchor).** Resolve the active `.devrites/work/<slug>/` path
+   and confirm `state.md` is writable. Missing slug, wrong repo root, or unreadable
+   workspace blocks Adopt before inspection. **Failing case:** adopt starts without a
+   confirmed workspace slug → stop; do not infer from cwd alone.
+
 1. Read core; resolve repository/sub-area and next objective. Ask once only if material.
 2. Follow [`reference/adoption.md`](reference/adoption.md): inspect current
    behavior, architecture and placement, callers, reusable seams, repository/CI
    commands, visible code/test patterns, non-obvious constraints, and any touched
-   load-bearing seam that needs `characterize-before-modify`. Read existing
-   `AGENTS.md`, `CLAUDE.md`, product, and design guidance.
+   load-bearing seam that needs **characterize-before-modify** (record disposition:
+   `characterized` with see-it-fail stub, or `deferred` with evidence why safe).
+   **Failing case:** plan touches auth middleware with no characterize row → Adopt
+   fails until disposition is recorded. Read existing `AGENTS.md`, `CLAUDE.md`, product,
+   and design guidance.
 3. Create the workspace and write `spec.md`, `decisions.md`, `assumptions.md`,
    `questions.md`, and `state.md`. The spec separates the current baseline from
    the measurable next objective.

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

@@ -43,6 +43,9 @@ Wright applies anti-slop; root verifies returns and never patches source.
 - Evidence beats confidence. Never weaken tests, skip TDD, widen writers, or
   self-approve. Drift → [`spec-drift-guard.md`](reference/spec-drift-guard.md);
   checkpoint → [`checkpoint.md`](reference/checkpoint.md).
+- Async readiness waits during slice work follow
+  [`debug-recovery.md`](../devrites-lib/reference/standards/debug-recovery.md)
+  (bounded poll + last-signal artifact; no blind sleep as primary strategy).
 
 ## Workflow Artifact branch
 
@@ -62,3 +65,12 @@ approved fail-on-red proof, record, AFK accounting, and stop. Use
 [`reply contract`](../devrites-lib/reference/reply-contract.md). HITL never starts
 the next slice automatically; AFK chains only within its durable remaining
 budget; Prove starts only after all slices are built.
+
+## Phase exit (observable)
+
+**Complete when:** the dispatched wright returns green proof for the slice,
+`git diff --name-only` ⊆ allowlist, independent test analysis admits no Critical
+gap, and `state.md` cursor advances with recorded evidence paths.
+
+**Failing case:** wright reports "done" but proof command was not executed or
+failed → slice incomplete; do not advance cursor.

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

@@ -21,7 +21,9 @@ prerequisite skill to run.
 > review use `/rite-review`; to prove a finished feature use `/rite-prove`.
 
 ## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+
 Pull on demand:
+
 - `principles.md`: the project invariants (`.devrites/principles.md`); code that violates a
   MUST principle is the highest-severity gap and produces a remediation slice.
 - `spec-grammar.md`: buildable acceptance criteria vs `## Success metrics` (outcome KPIs the
@@ -34,6 +36,7 @@ Pull on demand:
   triggered applicability rows; missing failure/recovery behavior is partial or absent.
 
 ## Operating rules
+
 - **APPEND-ONLY, never rewrite.** The only write to `tasks.md` is **appending** new
   `SLICE-###` entries. Never rewrite, renumber, reorder, or delete an existing slice
   (including slices a prior convergence appended). Never edit `spec.md` or `plan.md`. Never
@@ -58,6 +61,7 @@ Pull on demand:
   workspace changes.
 
 ## Workflow
+
 0. **Read `.claude/skills/devrites-lib/reference/standards/core.md`** first (the always-on
    operating rules), then resolve the active slug, require its `state.md`, and
    read the cursor directly.
@@ -103,10 +107,25 @@ Pull on demand:
    `/rite-prove` if the code already
    converged).
 
+## Completion evidence (fail-closed)
+
+Before reporting "clean" or recommending `/rite-prove`, confirm:
+
+- [ ] Every buildable AC/REQ in the assessment inventory has a built/partial/absent
+      classification with live-code citation
+- [ ] `tasks.md` is byte-for-byte unchanged when clean, or append-only when gaps exist
+- [ ] `traceability.md` updated only for appended slices
+- [ ] No narrative "done" without the checklist above
+
+**Failing case:** all units marked built but one AC lacks a test or runtime citation →
+report partial, append slice, route `/rite-vet`.
+
 ## Appended slice format
+
 Use the complete
 [`canonical slice grammar`](../devrites-lib/reference/workspace-artifact-schema.md#canonical-slice-grammar)
 with one added `Convergence:` field after `Satisfies:`:
+
 ```markdown
 <!-- Convergence 2026-07-07: slices below appended by /rite-converge — live code assessed against intent. -->
 ## SLICE-014 <name of the unmet capability>

package/pack/.claude/skills/rite-define/reference/plan-template.md

@@ -44,6 +44,16 @@ List vertical `SLICE-###` increments, AC coverage, and risk-first order within d
 tiers. Wide refactors use expand → green migrate batches → contract, or an integration
 branch + final verify slice.
 
+## Architecture admission
+
+Promote to ADR only **irreversible cross-boundary** choices (public contract,
+security invariant, migration that cannot roll back). Reversible config, helper
+placement, library version, or env default stays in `plan.md` / `decisions.md` as
+implementation-local or planning-owned — not architecture.
+
+**Failing case:** "Use env `FOO=bar` as default" recorded under Architecture decisions
+→ Vet requests downgrade to implementation-local horizon with observable trigger.
+
 ## Architecture decisions
 Decisions + rationale (mirror to `decisions.md`). Prefer reuse and invariants over
 scaffolding. Medium+ entries add `Binds:`/`Prevents:`. Interfaces name invariants, I/O,
@@ -105,7 +115,10 @@ otherwise simplify.
 | <e.g. new dependency X> | <reason> | <why the in-repo option won't work> |
 
 ## Rollback
-Risky-step backout: migration/flag/revert/backup.
+Every risky step (migration, destructive write, flag widening, contract change) names its
+backout before Build: **trigger** (what aborts it), **procedure** (down-migration / flag
+off / revert / restore), and **rollback-verification proof** (command + observed state).
+"Revert if needed" is not a rollback plan.
 
 ## Scope boundaries
 Untouched scope; copy spec “Ask first”/“Never do.”
@@ -120,7 +133,7 @@ Framework/library sources (triggers source-driven).
 - [ ] Applicability matches live evidence; outputs name owner, recovery, slice, proof
 - [ ] `MVP cut` is shippable/self-contained: ACs proven, no dependency below
 - [ ] Deviations are justified
-- [ ] Destructive/migration steps have rollback
+- [ ] Destructive/migration steps have rollback (trigger + procedure + verification proof); spec Prohibitions carry into slices verbatim
 - [ ] Each `Mode: HITL` slice has `Gate`, `SLA`, `Checkpoint`
 - [ ] Human choices resolved; checkpoints need unavailable pre-code evidence/action approval
 - [ ] All horizon items remain; blockers/planning items resolved or validly spiked;

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

@@ -18,26 +18,26 @@ of one authority; it cannot promote a rule alone.
 
 ## Workflow
 
-1. Read [durable promotion](../devrites-lib/reference/standards/documentation.md#promote-durable-guidance).
-   Bound the archive; inspect applicable
-   `AGENTS.md`/`CLAUDE.md`, accepted ADRs, and relevant
-   `.devrites/archive/*/{decisions,drift,review,seal}.md` files.
-2. In broad mode, dispatch exact `devrites-retrospector` fresh/read-only; reconcile its
-   claims against cited files.
-3. Keep a correction repeated in two features or one explicit durable product/architecture
-   decision with rationale. Drop one-off, generic, or stale items.
-4. Verify claims against live authoritative repository sources. State the currentness signal,
-   applies/does-not-apply scope, and `unknown` where unverifiable.
-5. Search guidance for the same/contrary rule. Choose one existing canonical owner: nearest
-   instruction/standard, architecture ADR, or feature `decisions.md`; name discovery.
-6. Show the exact edit and duplicate/conflict/supersession disposition. Update, narrow,
-   replace, or retire contradictions; apply only after user approval of the exact edits.
+1. Read [durable promotion](../devrites-lib/reference/standards/documentation.md#promote-durable-guidance);
+   bound the archive; inspect applicable `AGENTS.md`/`CLAUDE.md`, accepted ADRs, and relevant `.devrites/archive/*/{decisions,drift,review,seal}.md`.
+2. Broad mode dispatches exact fresh/read-only `devrites-retrospector`; reconcile its claims against cited files.
+3. Keep corrections repeated in two features, a judgement call made twice, or a defect class seen twice; drop one-off preferences, task-specific detail, generic advice.
+4. Verify claims against live authoritative sources; state currentness signal, applies/does-not-apply scope, `unknown` where unverifiable.
+   **Research promotion requires:** each external claim carries **URL + retrieval date
+   (ISO)** in the proposal. A finding without dated URL fails learn promotion.
+   **Failing case:** "best practice is X" with no source → reject promotion.
+5. Search guidance for same/contrary rules; choose one existing canonical owner (nearest instruction/standard, architecture ADR, or feature `decisions.md`) and name discovery.
+6. Show the exact edit + duplicate/conflict/supersession disposition; update/narrow/replace/retire contradictions; apply only after user approval of exact edits.
 
 ## Rules
 
 - Live repository evidence outranks memory; unverifiable is unknown, not false.
-- Never create a learning ledger/index/queue, score, timeline, or parallel authority.
-- Rejected directions return only when evidence changes their rationale.
+- Never create a learning ledger/index/queue, score, timeline, or parallel authority; rejected directions return only when evidence changes their rationale.
+- A declined lesson persists as a declined decision entry (reason recorded) in the nearest owning decisions file — not re-litigated without new evidence.
+- Contradiction outranks staleness: actively misleading guidance outranks merely old guidance.
+- A proposal names the **retrospective failing case**: the concrete past feature/artifact the
+  rule would have caught. None → generic advice — drop.
+- ≤3 accepted lessons per round; proposals extend/narrow but never lower an existing bar (revisions show old text beside new); duplicates consolidate into one canonical edit — simplification (deletions/merges) counts toward the cap.
 
 ## Output
 

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

@@ -26,6 +26,19 @@ live in `reference/code.md` and `reference/ui.md`; read only the phase in scope.
   [`agents.md`](../devrites-lib/reference/standards/agents.md). Never edit source inline or
   run two correction writers concurrently.
 
+## Polish axes (C3 — completeness vs craft)
+
+Score **separately**; conflating them hides gaps:
+
+| Axis | Question | Failing case |
+| --- | --- | --- |
+| **ux_coverage** | Did we compare every stated alternative/state? | Omitted empty/error state treated as agreement |
+| **completeness** | Are required states, copy, and flows present? | Hero-only layout with no loading/error |
+| **craft / anti-slop** | Does the UI avoid generic template patterns? | Inter + purple gradient hero with no product-specific hierarchy |
+| **distinction** | Is there one intentional signature detail? | Polished but indistinguishable from a template |
+
+Incomplete comparison is **not** agreement. Record axis deltas in `polish-report.md`.
+
 ## Orchestration
 
 0. **Read** `.claude/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules). The

package/pack/.claude/skills/rite-polish/reference/anti-ai-slop.md

@@ -52,13 +52,10 @@ match the neighbors.
   dots as set dressing.
 
 ### Copy & data realism
-Placeholder content is a tell even when the layout is clean:
-- **Fake-perfect numbers** — `99.99%`, `10,000+`, `$1M`. Real data is ragged: `47.2%`, `1,283`.
-- **Placeholder people/brands** — "John Doe", "Acme", "Nexus". Invent specific, plausible ones.
-- **Filler verbs** — Elevate / Seamless / Unleash / Supercharge / Next-Gen. Say what it does.
-- **Copy self-audit** — re-read every visible string before shipping; anything grammatically
-  broken, referent-unclear, or "an LLM trying to sound thoughtful" gets rewritten. AI-cute
-  copy is worse than boring copy.
+Placeholder content is a tell even when the layout is clean: fake-perfect numbers
+(`99.99%`, `10,000+` — real data is ragged), placeholder people/brands ("John Doe",
+"Acme"), filler verbs (Elevate / Seamless / Unleash). Re-read every visible string before
+shipping; AI-cute copy is worse than boring copy.
 
 ### Category-reflex check — run at two altitudes
 
@@ -90,6 +87,8 @@ Each is pass/fail by counting or grep, not judgment:
 - **Layout families** (hero, image+text split, card grid, bento, table…): no family more
   than twice per page; never 3 consecutive image+text zigzags.
 - **Icons**: 0 emoji-as-icon; exactly one icon set imported.
+- **State presence in code**: default+hover+focus-visible+active+disabled for every interactive element; loading/error/empty where data delays or fails — an unreachable state's screenshot proves nothing.
+- **Form inputs**: no border-width shifts between states; focus ring from outline/ring (not border swap); consistent control height; reserved helper slot; disabled beyond opacity alone.
 
 ## Code anti-slop (UI **and** backend)
 - **Over-defensive checks** — `if (x && x.length > 0)` repeated, layered null guards,
@@ -158,49 +157,11 @@ Each is pass/fail by counting or grep, not judgment:
   Reuse → extend → build new (`coding-style.md`, `patterns.md`); duplication beats the *wrong*
   abstraction, but pasted clones are slop, not a deliberate AHA call.
 
-### Comment density — before / after
-
-```js
-// Before (slop): a comment narrating almost every line
-function calculateTotal(items) {
-  // initialize the total to zero
-  let total = 0;
-  // loop through each item in the items array
-  for (const item of items) {
-    // add the item price to the total
-    total += item.price;
-  }
-  // return the final total
-  return total;
-}
-
-// After: the names carry it; no comment needed
-function sumPrices(items) {
-  return items.reduce((total, item) => total + item.price, 0);
-}
-
-// A comment that earns its place — it explains WHY, not what:
-// Prices are in minor units (cents); the gateway rejects fractional amounts.
-const total = sumPrices(items);
-```
-
-## Why these are banned
-They signal "a model generated this" rather than "this team designed/wrote this." They
-ignore the product's register and the project's idiom, add noise, hide bugs (defensive
-catches), bloat the diff (over-engineering, beyond-spec), and often fail accessibility
-or correctness review. They're cargo-cult, not craft.
-
-## What to do instead
-- **UI**: project tokens / shared components / consistent type & spacing
-  (`design-system-discovery.md`); content shapes layout; motion serves feedback;
-  reserve modals for focused interrupting tasks.
-- **Code**: validate at trust boundaries (don't sprinkle null checks); catch narrow,
-  recover or rethrow; one clear name per concept; one responsibility per function;
-  reuse before write (`coding-style.md`); implement exactly the spec; let inherent
-  complexity be — don't pad with ceremony.
-- If the project **does** use one of these intentionally, follow the project. Consistency
-  beats the rule.
-
-## When in doubt: ask
-A "robust" check or shiny abstraction you can't justify in one sentence is probably slop.
-Delete it; or ask the user if it should exist.
+## Why banned, what instead
+They signal model-generated rather than team-designed work: they ignore register and
+idiom, add noise, hide bugs (defensive catches), bloat diffs, and often fail a11y or
+correctness review. Instead: project tokens/components, validate at trust boundaries,
+catch narrow and rethrow, one clear name per concept, reuse first (`coding-style.md`),
+implement exactly the spec. If the project intentionally uses one of these, follow the
+project — consistency beats the rule. A check or abstraction you can't justify in one
+sentence is slop: delete it or ask.

package/pack/.claude/skills/rite-pr-feedback/SKILL.md

@@ -24,8 +24,13 @@ Step 0: Read `.claude/skills/devrites-lib/reference/standards/core.md`, plus `gi
 2. **Fetch.** Use GitHub GraphQL/CLI to collect unresolved review threads with file, line, author, body, and thread id. Completion: every unresolved thread is represented once, or the fetch error is reported.
 3. **Legitimacy gate.** For each item, read the surrounding code and classify: `fix`, `not-addressing`, `declined`, `reply-only`, or `needs-human`. Deduplicate overlapping items.
 4. **Fix approved items.** Apply contained fixes, add/update tests when behavior changes, and run targeted checks. Larger product/API/security calls become `needs-human`.
-5. **Commit/push.** Stage only touched files. Commit only if changes exist; push the branch.
-   **Completion:** changed files are committed/pushed with SHA evidence, or no commit is created because the diff is empty.
+5. **Commit/push.** Stage only touched files; commit only if changes exist; push the branch.
+   Push rejected (protected branch, non-fast-forward, hooks): stop and report the exact
+   rejection — never force-push or rewrite a shared branch. Post-push checks fail: record
+   the failing check, choose fix-forward or revert, put the choice + reason in the thread
+   reply — never a silent red push.
+   **Completion:** committed/pushed with SHA evidence and green checks, or no commit (empty
+   diff), or the push failure reported verbatim.
 6. **Reply and resolve.** Reply to every thread with outcome and evidence. Resolve only `fix`, `not-addressing`, `declined`, and `reply-only`; leave `needs-human` open.
    **Completion:** every thread has one recorded outcome and only permitted terminal outcomes are resolved.
 7. **Verify.** Fetch unresolved threads again and report remaining intentional opens.