devrites 3.0.6 → 3.1.0

package/pack/.claude/skills/rite-spec/reference/state-workspace.md

@@ -19,9 +19,12 @@ Load that schema before creating or updating workspace artifacts.
       decisions.md
       assumptions.md
       questions.md
+      decision-coverage.md       # from /rite-clarify
       plan.md                    # from /rite-define
       tasks.md                   # from /rite-define
       traceability.md            # from /rite-define
+      eng-review.md              # from /rite-vet
+      test-plan.md               # from /rite-vet
       state.md
       evidence.md                # from /rite-build or /rite-prove (proof.md alias supported)
       browser-evidence.md        # UI only
@@ -46,8 +49,10 @@ canonical files and preserves aliases rather than deleting old ones.
 - `/rite-spec` creates the workspace map, `brief.md`, `spec.md`, `decisions.md`,
   `assumptions.md`, `questions.md`, `state.md`, optional `references.md` /
   `references/`, and optional `design-brief.md` for UI.
+- `/rite-clarify` adds `decision-coverage.md`.
 - `/rite-define` adds `architecture.md`, `plan.md`, `tasks.md`, and
   `traceability.md`.
+- `/rite-vet` adds `eng-review.md` and `test-plan.md`.
 - Later phases add only the artifact they own. Do not create optional files as
   empty placeholders; absence means the phase has not produced that artifact.
 - Each artifact starts with a summary and links to deeper source files instead of
@@ -61,7 +66,7 @@ canonical files and preserves aliases rather than deleting old ones.
 # <Feature> Workspace
 phase: spec
 status: running
-next_action: /rite-define after spec readiness passes
+next_action: /rite-clarify after spec readiness passes
 last_updated: <date>
 
 ## Artifact map
@@ -69,6 +74,7 @@ last_updated: <date>
 | --- | --- |
 | brief.md | Objective and bounds |
 | spec.md | Product contract |
+| decision-coverage.md | Clarification verdict; absent until /rite-clarify |
 | architecture.md | Technical map; absent until /rite-define |
 | plan.md | Technical approach; absent until /rite-define |
 | tasks.md | Vertical slices; absent until /rite-define |
@@ -79,7 +85,8 @@ last_updated: <date>
 | Phase / role | Read |
 | --- | --- |
 | Spec | brief.md, spec.md, questions.md |
-| Build | state.md, tasks.md, plan.md |
+| Clarify | spec.md, decisions.md, assumptions.md, questions.md |
+| Build | state.md, decision-coverage.md, eng-review.md, test-plan.md, tasks.md, plan.md |
 | Review | traceability.md, evidence.md, decisions.md |
 
 ## Blocking gates
@@ -100,6 +107,8 @@ None.
 | slice_mode | none |
 | risk | none |
 | next_action | <single command + reason> |
+| return_phase | <later phase; retrofit clarification only> |
+| return_next_action | <saved command; retrofit clarification only> |
 
 ## Awaiting human
 Only present when status is awaiting_human.
@@ -112,7 +121,8 @@ Only present when status is awaiting_human.
 
 `state.md` is a compact cursor, not a history file. Put proof in `evidence.md`,
 decisions in `decisions.md`, assumptions in `assumptions.md`, and drift in
-`drift.md`.
+`drift.md`. Omit both `return_*` rows outside a later-phase `/rite-clarify`
+retrofit; `devrites-engine clarify-return` owns their atomic lifecycle.
 
 ## questions.md entry format
 

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

@@ -5,15 +5,13 @@ argument-hint: "[feature-slug] [--mode expand|selective|hold|reduce]"
 user-invocable: true
 ---
 
-# /rite-temper: temper the spec before you plan
+# /rite-temper: review scope and risk before planning
 
-Take a readied spec and **temper** it: heat it (raise ambition on the *outcome*), then
-quench it (pre-mortem + prune the *solution surface*): stronger and less brittle. The one
-DevRites step that decides scope/ambition on a written spec and folds the result into the
-canonical contract, so `/rite-define` plans the **hardened** spec. Optional for small work
-(significance-gated: auto-skips low-stakes specs), but always invoked inside
-`/rite-autocomplete`. **Read the active workspace first**; if there's no readied
-`spec.md`, tell the user to run `/rite-spec`.
+Review a readied spec for outcome ambition, scope, pre-mortem risks, and unnecessary
+solution surface. Fold accepted decisions into the canonical contract before
+`/rite-define`. This step is optional for small work and skips low-stakes specs, but
+`/rite-autocomplete` always invokes it. **Read the active workspace first**; if there
+is no readied `spec.md`, tell the user to run `/rite-spec`.
 
 ## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
 Pull on demand: `patterns.md` +
@@ -23,65 +21,70 @@ invent one), `documentation.md` (ADR-style `decisions.md` entries), `afk-hitl.md
 that needs more than the default pre-mortem) selected by the section's risk).
 
 ## Operating rules
-- **Ambition on outcomes, minimalism on the surface.** Raise the success bar and solve the
-  *real* problem; never add speculative capability/abstraction. The reconciliation hinge:
-  bigger ambition, smaller surface.
-- **Every scope change routes through the Spec Drift Guard:** it only becomes real by being
-  written into `spec.md` as a recorded, confirmable decision. Expansion is **opt-in** (HITL
+- **Raise outcome ambition without expanding the solution unnecessarily.** Solve the
+  underlying problem without adding speculative capability or abstraction.
+- **Route every scope change through the Spec Drift Guard.** A scope change takes effect
+  only when `spec.md` records the confirmed decision. Expansion is **opt-in** (HITL
   confirm; AFK pauses: see autocomplete policy). Nothing auto-grows into the build.
-- **Bound ambition by reversibility.** Auth / migration / public-API / data-model touches get
-  the *opposite* of ambition: maximum conservatism; they always pause (irreversible-risk list).
+- **Apply maximum caution to hard-to-reverse changes.** Auth, migration, public API, and
+  data-model changes always pause under the irreversible-risk list.
 - **Honest verdict.** Never round "needs work" up to "ready"; record every scope call's *why*.
+- **Search before asking.** Apply `afk-hitl.md` decision ownership; only human-owned calls
+  enter the interactive walk.
 - **You write; the reviewer judges.** You are the single canonical writer (`strategy.md` +
   the spec edits); the reviewer agent is read-only.
-- **Demand the spec-quality checklists for big features.** `/rite-temper` only fires on
-  significant specs: exactly where vague requirement prose is most expensive. Before hardening,
+- **Require spec-quality checklists for significant features.** Before hardening,
   confirm `checklists/<domain>.md` exist and pass (`rite-spec/reference/spec-checklists.md`); a
   scope expansion you fold in **adds its own** rows (new Success/Acceptance criteria get
-  "unit-tested for English" too). A folded expansion with an unquantified criterion is a CRITICAL
-  fail that re-opens the readiness gate.
+  checklist rows too). A folded expansion with an unquantified criterion is a CRITICAL
+  failure that reopens the readiness gate.
 
 ## Workflow
 0. **Read `.claude/skills/devrites-lib/reference/standards/core.md`**, then run
    `devrites-engine preamble` for deterministic workspace orientation.
-   Then read the workspace: `spec.md` (+ `decisions.md`,
+   Then read the workspace: `spec.md`, `decision-coverage.md` (+ `decisions.md`,
    `assumptions.md`, `design-brief.md` if UI), `state.md`. Require `Spec gate: passed`: else
-   STOP → `/rite-spec`. If a plan already exists, scope changes route through `/rite-plan
+   STOP → `/rite-spec`. Require `Decision coverage: CLEAR`: else STOP →
+   `/rite-clarify`. If a plan already exists, scope changes route through `/rite-plan
    repair` (record in `drift.md`), not a blind spec edit.
 1. **Significance test:** [`reference/significance.md`](reference/significance.md). Low-stakes
-   / shape-not-meaning work → write the one-line `skipped — low stakes (<trigger>)` verdict to `strategy.md`,
+   / shape-not-meaning work → write the exact one-line `skipped — low stakes (<trigger>)` verdict to `strategy.md`,
    set `state.md` `Next step: /rite-define`, and recommend it. Otherwise fire the full pass below.
 2. **FORWARD pass + mode selection:** [`reference/scope-modes.md`](reference/scope-modes.md).
    First, the **one-sentence-intent test**: state the whole change's intent in a single sentence.
    If you can't without an "and" that joins two unrelated outcomes, it is **two features**: the
-   sharpest scope-creep signal there is; recommend splitting the spec (or narrowing this one) before
-   tempering further. Then diverge on the *outcome* (the 10-star version of the real problem), and
-   commit **exactly one** scope mode (`expand` opt-in · `selective` · `hold-rigor` · `reduce-to-MVP`)
-   with its rationale and the **hinge** (what would change the call). `$ARGUMENTS` `--mode` is a
+   scope-creep signal; recommend splitting or narrowing the spec before continuing.
+   Then consider the 10-star outcome for the underlying problem and choose **exactly one**
+   scope mode (`expand` opt-in · `selective` · `hold-rigor` · `reduce-to-MVP`) with its
+   rationale and the condition that would change the choice. `$ARGUMENTS` `--mode` is a
    hint, not a command.
 3. **INVERSION pass:** pre-mortem in past tense ("it shipped and failed: what went wrong"),
    each top risk carrying likelihood + mitigation + the slice it will bind to; then the **YAGNI
    ledger** (each candidate scope item gets the "imagine the later refactor" test; defer unless
    now-cost is trivial AND deferred-cost is large).
-   - **Deepen on demand.** When a specific scope call, requirement, or risk needs sharper thinking
-     than the default pre-mortem gives, pull the 3-5 techniques from
+   **Interruption pre-mortem:** audit the spec forecast and assumptions for unresolved behavior,
+   proof prerequisites, approvals, access, and irreversible gates. Resolve facts and reversible
+   details now; retain only unavailable-pre-code or mandatory action-time checkpoints.
+   - **Deepen on demand.** When a scope decision, requirement, or risk needs more analysis
+     than the default pre-mortem provides, choose 3-5 techniques from
      [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) whose *when-to-reach-for-it* matches that
      section's risk (irreversible decision → Red-Team/Blue-Team + Assumption Audit; sizing → Delphi;
-     vague requirement → Steelman-then-Attack), offer them, and run the chosen one **on that one
-     section**. Record what it changed, not that you ran it. Optional: the default passes stand on
-     their own.
+     vague requirement → Steelman-then-Attack), offer them, and run the chosen one **on that
+     section**. Record what changed, not the technique name. The default passes remain
+     sufficient when no deeper analysis is needed.
 4. **Score the 9 dimensions:** [`reference/review-dimensions.md`](reference/review-dimensions.md).
    Cite evidence *before* the band; **gate on the floor** (the weakest dimension, not an average).
    **Completion:** all nine dimensions have cited evidence, a band, and one explicit floor verdict.
-5. **Walk the findings WITH the human: do not batch-dump.** The artifact is the *output* of an
-   interactive review, not a substitute for it: surface each material scope call / finding via
+5. **Review human-owned findings with the human; do not batch them.** `strategy.md`
+   records the interactive review but does not replace it. Present each material scope decision through
    `AskUserQuestion`, one at a time, best-guess + **why**. Each material scope call ends as a
    **recorded decision**: a resolved `questions.md` qid (HITL) or a `decisions.md` ADR (AFK):
-   so the walk leaves an auditable trail, not just chat. (AFK gate policy is single-sourced in
+   so the review leaves an auditable record outside chat. (AFK gate policy is single-sourced in
    [`reference/significance.md`](reference/significance.md): `hold-rigor` + `reduce-to-MVP`
    auto-apply, **any `expand` is a blocking pause**, irreversible-risk always pauses.)
+   Apply objective clarity, mitigation, and assumption fixes directly.
 6. **Write `strategy.md` + fold back:** [`reference/strategy-template.md`](reference/strategy-template.md).
-   **One drift rule (decide by whether a plan exists):** *no `plan.md` yet* (the normal pre-define
+   **Choose the drift path based on whether a plan exists:** *no `plan.md` yet* (the normal pre-define
    case) → update `spec.md` **through the Spec Drift Guard**. *Success criteria* **and**
    *Acceptance criteria* for each opt-in expansion / cut, **Non-goals** for every deferred item,
    *Constraints* **and** *Risks* the pre-mortem demands, and the gaps/decisions table; *`plan.md`
@@ -90,22 +93,33 @@ that needs more than the default pre-mortem) selected by the section's risk).
    decision · why-not · what-would-change-it) and `assumptions.md` (every "we'll probably need X" →
    assumption-to-verify). **Every scope delta must carry a recorded human decision**: a resolved
    `questions.md` qid (HITL) or a `decisions.md` ADR (AFK within the ceiling); a folded change with
-   no recorded decision is the batch-dump failure. **Re-check the spec Readiness gate** (it fails if
-   any folded scope delta lacks its decision). Update `state.md`: `Phase: temper`,
+   no recorded decision is invalid. **Re-check the spec Readiness gate** (it fails if
+   any folded scope delta lacks its decision or leaves a foreseeable human build choice).
+   After any edit to `brief.md`, `spec.md`, `decisions.md`, `assumptions.md`, or
+   `questions.md`, re-scan the affected coverage rows, assumption audit, residual uncertainty,
+   and closed gates. Partial/Missing, an unowned material assumption, or an open
+   blocking/escalating question routes `/rite-clarify`/HITL; never refresh past it. Only after the
+   matrix is re-closed, run `devrites-engine readiness-digest coverage <slug>` and replace the
+   complete `Coverage inputs SHA-256` line in `decision-coverage.md`.
+   Update `state.md`: `Phase: temper`,
    `Next step: /rite-define`; on a blocking pause (expand / irreversible / a dimension still below
    bar) write the `Awaiting human` block + `Status: awaiting_human` before stopping.
 7. **Adversarial verification loop:** dispatch [`devrites-strategy-reviewer`](../../agents/devrites-strategy-reviewer.md)
-   (fresh context, **only** the hardened spec + the rubric: no authoring reasoning). Resolve
+   through the file-backed fresh-context contract in
+   [`agents.md`](../devrites-lib/reference/standards/agents.md), with **only** the hardened
+   spec + rubric: no authoring reasoning. Resolve
    actionable findings by editing `spec.md`/`strategy.md`, re-dispatch; **cap ≤3 iterations**. A
-   dimension still below bar after 3 → blocking question (HITL) or AFK gate-ceiling entry;
-   irreversible-risk findings always pause. If sub-agents are unavailable, do the independent
-   rubric pass yourself in a separate read, discarding the authoring reasoning (a flagged
-   fallback, not an independent review).
+   dimension still below bar after 3 is classified by decision ownership: a product/scope/risk
+   choice becomes a blocking question; an objective spec defect stays blocked with the exact
+   required edit and routes to `/rite-spec`, not `/rite-resolve`. Irreversible-risk findings
+   always pause. Use the shared capability ladder; an inline final-rung pass is labeled
+   `independence: fallback`, never an independent review. After an accepted edit to a
+   coverage-bound input, repeat step 6's revalidation and digest refresh before handoff.
 8. **STOP.** Report the mode, the scope deltas, and the floor verdict; recommend `/rite-define`.
 
-> **Mid-flight discipline.** When tempted to dump findings into `strategy.md` and skip the
-> walk-through, expand the surface (not the outcome), grow scope without the Drift Guard, or
-> score before citing evidence: see [`reference/anti-patterns.md`](reference/anti-patterns.md).
+> **Mid-flight discipline.** Do not replace the interactive review with `strategy.md`,
+> expand implementation surface without need, grow scope outside the Drift Guard, or score
+> before citing evidence. See [`reference/anti-patterns.md`](reference/anti-patterns.md).
 
 ## Output
 
@@ -115,12 +129,13 @@ Default success shape:
 ```
 Done: spec tempered for <slug>; mode <expand|selective|hold-rigor|reduce-to-MVP|skipped-low-stakes>.
 Changed: strategy.md, spec.md, decisions.md, assumptions.md
-Evidence: dimension floor <band>; reviewer loop <n>; spec readiness re-checked pass
+Evidence: dimension floor <band>; reviewer loop <n>; spec readiness + decision coverage re-checked pass
 Open: <none | n deferred non-goals>
 Next: /rite-define
 Record: .devrites/work/<slug>/strategy.md
 ↻ Hygiene: /clear before /rite-define
 ```
 If readiness is blocked, use the shared `Stopped / blocked` form and route `Fix:`
-to `/rite-spec`; do not recommend `/rite-define`.
+to `/rite-clarify` for an uncovered decision surface or `/rite-spec` for an objective
+spec defect; do not recommend `/rite-define`.
 **DO NOT plan, slice, or write code here**. That's `/rite-define` and `/rite-build`.

package/pack/.claude/skills/rite-temper/reference/review-dimensions.md

@@ -1,23 +1,25 @@
-# Review dimensions + the floor-gate rubric
+# Review dimensions and floor-gate rubric
 
-The spec is scored on nine dimensions. Each catches a *different* failure mode: strength in
-one never compensates for collapse in another, so the gate is the **floor**, not an average.
+Score the spec on nine dimensions. A strong dimension cannot offset a failed one, so
+the gate uses the **lowest band**, not an average.
 
 ## The nine dimensions
-1. **Problem altitude & ambition:** is this solving the *right* problem at the right altitude,
-   or timidly improving the obvious path / over-reaching past the real need? Here, *under-
-   reaching* on the outcome is a failure, not just over-building.
-2. **Scope honesty & boundary:** are Non-goals explicit? Is there a Minimum Usable Subset and a
-   clear IN/OUT line? Flags grab-bags and a missing "Won't-have-this-time".
-3. **Premise & alternatives:** are the load-bearing premises stated and challenged, and is at
+1. **Problem choice and ambition:** does the spec solve the underlying problem, or only
+   make a minor improvement to the obvious path? It may also reach beyond the actual need.
+   Both insufficient outcome ambition and over-building are failures.
+2. **Scope and boundary:** are non-goals explicit? Is there a Minimum Usable Subset and
+   a clear IN/OUT line? Flag unrelated bundles and a missing "Won't-have-this-time".
+3. **Premise and alternatives:** are the consequential premises stated and challenged, and is at
    least one genuinely different approach (different data model / flow / boundary) considered
    with its trade-off? ("Alternatives considered" is one of the most useful parts of a spec.)
-4. **Pre-mortem risk coverage:** run in prospective hindsight; each top risk carries likelihood
-   + mitigation + the slice that owns it. **Unmitigated top risks are gating.**
+4. **Pre-mortem risk coverage:** assess the feature as if it shipped and failed. Each top risk carries likelihood
+   + mitigation + the slice that owns it. The interruption pre-mortem accounts for foreseeable
+   human prerequisites and action-time approvals instead of deferring generic uncertainty to
+   build. **Unmitigated top risks are gating.**
 5. **Over-engineering / YAGNI:** speculative capability, unused extension points, premature
    abstraction, second-system bloat. Apply the pack's standard (`patterns.md`) + the "imagine
    the later refactor" test. Defer unless now-cost is trivial AND deferred-cost is large.
-6. **Acceptance testability & done-ness:** every acceptance criterion measurable, technology-
+6. **Acceptance testability and completion:** every acceptance criterion measurable, technology-
    agnostic, and comparable **down to a baseline** ("better than the current workaround"), not
    up to an unbounded ideal. Vague adjectives ("fast/robust/intuitive") and "handles X
    gracefully" are flagged.
@@ -34,9 +36,8 @@ UI specs also inherit `rite-polish/reference/anti-ai-slop.md` at the cross-cutti
 dimension (design-system fit, anti-AI-slop), but `/rite-temper` reviews the *spec/design-brief*,
 not pixels; the built UI is judged later by `devrites-frontend-reviewer`.
 
-## The rubric: coarse bands, evidence first
-Score each dimension on a **labeled band**, never a 1-10 float or a composite number (labels do
-the work: matches the pack's severity-vocabulary stance):
+## Rubric
+Score each dimension on a **labeled band**, never a 1-10 float or composite number:
 
 | Band | Meaning |
 |---|---|
@@ -45,9 +46,8 @@ the work: matches the pack's severity-vocabulary stance):
 | **thin** | Under-addressed; a real gap to close before planning (Important). |
 | **broken** | Missing or wrong in a way that will cost a redo (Critical). |
 
-**Cite evidence before the band**: name the spec line / absence that justifies it; never score
-first and rationalize after. Borderline dimensions may be sampled twice; take the **lower** band
-(don't average up).
+**Cite evidence before assigning the band.** Name the spec line or absence that
+justifies it. Review a borderline dimension twice if needed and use the **lower** band.
 
 ## The floor-gate
 - **Pass** only when every dimension is `adequate` or `strong` **and** no unmitigated top
@@ -57,9 +57,11 @@ first and rationalize after. Borderline dimensions may be sampled twice; take th
   Suggestion / Nit / FYI**) so they compose with `/rite-review` and `/rite-seal`. `broken` →
   Critical, `thin` → Important; **FYI is band-independent**: an observation on a `strong` /
   `adequate` dimension, not a failing band.
-- **Don't double-count overlap.** Some dimensions key on the same evidence (e.g. #7
+- **Do not double-count overlap.** Some dimensions use the same evidence (e.g. #7
   irreversibility & #9 convention-fit both touch codebase realism; #1 ambition & #2 scope both
   touch over/under-reach). Don't fail two dimensions for the *same* root cause: cite the
-  evidence once, band it once, so one problem isn't laundered into two floor failures.
-- Below-bar dimension after the ≤3-iteration reviewer loop → blocking question (HITL) or AFK
-  gate-ceiling entry. Irreversible-risk findings always pause regardless of band.
+  evidence once and assign one band so one problem does not create two floor failures.
+- Below-bar dimension after the ≤3-iteration reviewer loop → classify by decision ownership:
+  product/scope/risk uncertainty becomes a blocking question; an objective prose/coverage defect
+  routes back to `/rite-spec` without inventing a human decision. Irreversible-risk findings
+  always pause regardless of band.