devrites 2.6.1 → 3.0.0

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

@@ -1,134 +1,110 @@
 # `spec.md` template
 
-Write **what** to build and **why** — never **how** (implementation goes in `plan.md`,
-written later by `/rite-define`). Ground every section in the codebase you investigated;
-don't invent files, commands, or conventions.
+Write the product contract: WHAT users get, WHY it matters, how success is
+measured, and what is out of scope. Keep HOW in `plan.md`; put topology and
+diagrams in `architecture.md` / `flows.md`; put coverage in `traceability.md`.
 
-**Two hard rules:**
-1. **Mark every unknown** with `[NEEDS CLARIFICATION: the exact question]` instead of
-   guessing. Open markers block `/rite-define` and `/rite-build` (no silent assumptions).
-2. **No implementation details** in the spec — no tech/library/endpoint choices in the
-   requirements or success criteria. Those are technology-agnostic.
+Rules:
+
+1. Mark unknowns with `[NEEDS CLARIFICATION: <question>]`; blocking unknowns
+   stop `/rite-define`.
+2. Use stable IDs: `REQ-001` for requirements and `AC-001` for acceptance.
+3. Link to source artifacts instead of duplicating them.
+4. Keep the file compact. If it exceeds the schema budget, add
+   `Budget override: <reason>`.
 
 ```markdown
 # Spec: <Feature>
-Slug: <kebab-case>   Created: <date>   Status: Draft | Ready
+Slug: <kebab-case>
+Status: Draft | Ready
+Created: <date>
+
+## Problem
+What is broken, missing, or costly today.
 
-## Objective
-One paragraph: what this delivers and the value. WHAT + WHY, not HOW.
+## Goal
+One paragraph describing the user-visible outcome and why it matters.
+
+## Non-goals
+- <Explicitly out of scope.>
 
 ## Users / actors
-Who uses it and the goal each has.
-
-## Problem statement
-What's broken/missing today; what users do instead.
-
-## User scenarios  *(prioritized, each independently testable)*
-Order by importance; each scenario should be shippable + verifiable on its own → it
-becomes a build slice. Use Given/When/Then.
-- **P1** — Given <state>, When <action>, Then <observable outcome>.
-- **P2** — Given <state>, When <action>, Then <observable outcome>.
-- **P3** — ...
-
-## Functional requirements  *(testable, unambiguous)*
-Number them so tasks and the seal can reference them.
-- **FR-001**: The system MUST <capability>.
-- **FR-002**: The system MUST <capability>.
-- **FR-003**: The system MUST NOT <prohibited behavior>.
-  (Mark gaps: "FR-004: [NEEDS CLARIFICATION: is export CSV-only or also XLSX?]")
-
-## Key entities / data model   *(if data is involved, else "none")*
-Entities, key fields, relationships, lifecycle (created/updated/soft-deleted). No DB
-schema here — that's the plan.
-
-## API / UI impact   *(else "none")*
-Endpoints + contracts (shape, status, errors) at the WHAT level; screens + the states
-each must handle (default/loading/empty/error/success/disabled).
-
-## Design references   *(if the human supplied any, else "none")*
-The screenshots / mockups / Figma / video / links that define the target look & behavior,
-from references.md. Name what each shows and which scenarios it governs.
-- R1 — references/<file> or <url> — <what it shows> → governs <scenario/FR>
-
-## UX/UI design brief   *(if the feature touches UI, else "n/a")*
-When UI is involved, `devrites-ux-shape` writes the feature-level **`design-brief.md`** here
-(design direction, key states, interaction model, visual-direction probe) — the target
-`/rite-build` builds to. Summarize its direction in one line; the full brief lives in
-`design-brief.md`.
-- Direction: <color strategy> · "<scene sentence>" · anchors: <ref A, ref B>
-
-## Success criteria  *(measurable AND technology-agnostic)*
-Observable outcomes that mean "this worked". Numbers where possible. No tech names.
-- Good: "A user exports 10k rows and receives a complete file in under 5s."
-- Good (UI): "The list view matches reference R1 at 1280px and 375px."
-- Bad: "The /export Sidekiq job uses streaming CSV." (that's HOW — belongs in plan)
+| Actor | Need |
+| --- | --- |
+| <actor> | <goal> |
+
+## Requirements
+- REQ-001: The system MUST <observable product behavior>.
+- REQ-002: The system MUST NOT <prohibited behavior>.
 
 ## Acceptance criteria
-Binary, evidence-backed checklist; each maps to a scenario/FR. See acceptance-criteria.md.
-- [ ] [AC1] <criterion> (FR-00x)
+Each criterion is binary and evidence-backed; every item maps to at least one
+requirement and later to at least one slice in `traceability.md`.
+
+- [ ] AC-001: Given <state>, when <action>, then <observable outcome>. (REQ-001)
+- [ ] AC-002: Given <state>, when <action>, then <observable outcome>. (REQ-002)
+
+For behavioral or high-risk requirements, use the structured form below. Keep the
+`AC-###` ID inside the scenario so traceability remains machine-checkable.
 
-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.
-
-## Constraints
-Tech/time/compatibility/perf/security/compliance constraints that bound the solution.
-
-## Placement & integration  *(where it lives — from investigation.md)*
-So the work is **correctly placed to be used**, not bolted on:
-- **Owns / lives in**: the module / layer / file / component that should hold this, + the
-  right seam.
-- **Reuse / extend**: existing patterns, components, utilities to build on — not duplicate.
-- **Integration points**: callers & dependents; data read/written; APIs / events /
-  contracts touched (how it interacts with the rest of the system).
-- **Affected areas**: the real modules / routes / models / components this change touches.
-- **Blast radius**: what could break (from the code-graph impact / callers).
-
-## Commands discovered
-- Tests: <cmd>   Build/typecheck: <cmd>   Lint: <cmd>   Run/dev: <cmd>
-(From package scripts / Makefile / Gemfile / pyproject / go.mod / CI.)
-
-## Test strategy
-What proves each acceptance criterion (unit/integration/e2e/manual).
-
-## Browser proof strategy   *(if UI, else "n/a")*
-Which proof-ladder rung, which routes/viewports, and which design references to verify against.
-
-## Risks
-Ranked. Include migration / data / security / UX risks.
-
-## Gaps, issues & decisions  *(drive the open count toward zero before /rite-define)*
-Every material gap/issue found in investigation, the options offered to the user, and the
-outcome. Resolved here = not rediscovered as drift later.
-| Item | Type (gap / issue / conflict) | Options offered | Decision (owner) | Status |
-|------|------------------------------|-----------------|------------------|--------|
-| <e.g. token scope> | gap | per-user / per-session / follow-up | per-session (user) | resolved |
-
-## Open questions  *( [NEEDS CLARIFICATION] register )*
-List every open marker; blocking ones must be zero at the gate.
-
-## Boundaries
-- **Always do**: conventions to follow without asking.
-- **Ask first**: new deps, second design system, schema/migration, auth changes, scope expansion.
-- **Never do**: destructive ops, drive-by refactors, unrelated cleanup.
-
-## Readiness gate  *(must pass before /rite-define plans it)*
-- [ ] No blocking `[NEEDS CLARIFICATION]` markers remain (deferred ones are non-blocking)
-- [ ] **Placement decided** — where it lives + integration points are known
-- [ ] All material gaps/issues have a recorded decision
-- [ ] **Every spec dimension resolved or explicitly deferred** — objective · scope · data model · UX · integration · non-functional · acceptance (see question-protocol.md "Coverage 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))
+#### Scenario: <name>
+- [ ] AC-003: **WHEN** <trigger> **THEN** <observable outcome>. (REQ-001)
+
+## Edge Coverage
+Deterministic boundary checklist for the requirements. Use `covered`, `backstop`,
+`dismissed`, or `unresolved`; every row targets an existing REQ/AC unless dismissed.
+
+| Edge ID | Requirement/AC | Class | Status | Reason/backstop |
+| --- | --- | --- | --- | --- |
+| EDGE-001 | AC-001 | empty/error/permission/race/migration | covered | <test/evidence or rationale> |
+
+## Prohibitions (must-NOT)
+Only bespoke constraints; generic security/privacy canon stays in project standards.
+Use `resolved/test`, `resolved/judgment`, `dismissed`, or `unresolved`.
+
+| Prohibition ID | Requirement/AC | Status | Test/evidence |
+| --- | --- | --- | --- |
+| PROH-001 | REQ-002 | resolved/test | <test/evidence link> |
+
+## Edge cases
+- <Narrative notes for boundary cases not captured in the table.>
+
+## AI-SPEC annex
+- Required when the feature touches model calls, RAG, agents, evals, or LLM output: `ai-spec.md` from `ai-spec-template.md`.
+- Otherwise: not applicable.
+
+## Measurable success
+- <Metric or observable proof that the feature worked.>
+
+## Scope boundaries
+- Owns: <product surface or behavior>.
+- Does not own: <adjacent area>.
+- Placement summary: <one-line module/layer summary>; full technical map lives in `architecture.md`.
+
+## References
+- `brief.md` - request, objective, non-goals, success definition.
+- `architecture.md` - technical placement and integration points.
+- `flows.md` - diagrams when useful.
+- `decisions.md` - ADR-style product/technical decisions.
+- `traceability.md` - AC/REQ coverage once `/rite-define` runs.
+- `design-brief.md` - UI direction when UI is in scope.
+
+## Open questions
+| Question ID | Gate | Question | Impact |
+| --- | --- | --- | --- |
+| Q-001 | blocking | [NEEDS CLARIFICATION: <question>] | AC-001 |
+
+## Readiness gate
+- [ ] No blocking `[NEEDS CLARIFICATION]` markers remain.
+- [ ] Requirements use `REQ-###` IDs.
+- [ ] Acceptance criteria use `AC-###` IDs and are independently provable.
+- [ ] Edge Coverage rows target existing REQ/AC IDs or carry a dismissal reason.
+- [ ] Prohibitions have resolved/dismissed status; `resolved/test` rows link test/evidence.
+- [ ] AI features have `ai-spec.md`; non-AI work states the annex is not applicable.
+- [ ] Non-goals and scope boundaries are explicit.
+- [ ] Architecture/flows/decisions are linked out instead of duplicated here.
+- [ ] UI work has `design-brief.md`; non-UI work states UI is out of scope.
 ```

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

@@ -1,167 +1,156 @@
-# `.devrites/` state workspace — canonical format
+# `.devrites/` state workspace
 
-The shared state contract for **all** DevRites skills. Every phase reads the active
-workspace first; if none exists, it stops and tells the user to run `/rite-spec <feature>`
-(which creates it).
+This is the writer-facing companion to the canonical schema in
+[`devrites-lib/reference/workspace-artifact-schema.md`](../../devrites-lib/reference/workspace-artifact-schema.md).
+Load that schema before creating or updating workspace artifacts.
 
 ## Layout
-```
+
+```text
 .devrites/
-  README.md                       # what this dir is (seeded at install)
-  ACTIVE                          # single line: active feature slug, or empty
+  ACTIVE
   work/
     <feature-slug>/
-      brief.md                    # short user-facing objective
-      spec.md                     # what to build + why (from /rite-spec)
-      checklists/                 # spec-quality checklists — "unit tests for English", one <domain>.md per requirement domain (from /rite-spec; gated at spec readiness)
-      references/                 # saved design/reference assets (screenshots, exports, video)
-      references.md               # index of design references (saved files + links)
-      strategy.md                 # strategic review: scope mode + pre-mortem + dimension scores (from /rite-temper; optional — always invoked, significance-gated, in /rite-autocomplete)
-      plan.md                     # how to build it (from /rite-define)
-      tasks.md                    # ordered vertical slices (from /rite-define)
-      eng-review.md               # engineering plan review: scope challenge + axis findings + failure modes + parallelization (from /rite-vet — run on every plan; depth scales light/full, never skipped; always in /rite-autocomplete)
-      test-plan.md                # build-readable coverage target: coverage diagram + per-gap test requirements + acceptance→test map (from /rite-vet; read by /rite-build + /rite-prove)
-      coverage.md                 # traceability matrix: AC-id → slice(s) → test (from /rite-define; walked by /rite-prove + /rite-seal)
-      devex.md                    # developer-experience scorecard — predicted (/rite-vet) → measured (/rite-prove) → reconciled (/rite-seal); only when a developer-facing surface is in scope
-      state.md                    # phase, active slice, risk, next step
-      questions.md                # asked questions + answers
-      decisions.md                # decisions + rationale (+ a `## Dead ends` section: approaches tried that failed + why, so retries don't repeat them)
-      assumptions.md              # explicit assumptions still standing
-      drift.md                    # spec/plan drift observations + resolutions
-      touched-files.md            # files changed or intentionally inspected
-      evidence.md                 # commands run + results
-      forge-report.md             # competitive-build record: K candidates → winner + grafts (from /rite-build on a `Forge: yes` slice; rare)
-      browser-evidence.md         # screenshots, routes, console, viewport checks
-      design-brief.md             # UX/UI contract — if UI involved (from /rite-spec via devrites-ux-shape; refined per slice in /rite-build)
-      polish-report.md            # normalize+polish output
-      review.md                   # review findings + decisions
-      seal.md                     # final GO / NO-GO decision (from /rite-seal)
-      ship.md                     # ship record: commit/tag, acceptance, follow-ups (from /rite-ship)
-      handoff.md                  # human/next-agent-facing handoff summary (overwritten each handoff)
+      README.md                  # compact workspace map (feature.md/index.md aliases supported)
+      brief.md
+      spec.md
+      architecture.md            # from /rite-define
+      flows.md                   # optional, only when useful
+      decisions.md
+      assumptions.md
+      questions.md
+      plan.md                    # from /rite-define
+      tasks.md                   # from /rite-define
+      traceability.md            # from /rite-define
+      state.md
+      evidence.md                # from /rite-build or /rite-prove (proof.md alias supported)
+      browser-evidence.md        # UI only
+      drift.md                   # drift only
+      touched-files.md           # from /rite-build
+      design-brief.md            # UI only
+      handoff.md                 # from /rite-handoff
+      references.md
+      references/
   archive/
-    <feature-slug>/               # closed features (moved here by /rite-ship close-out; all .md preserved)
+    <feature-slug>/
 ```
 
-## Rules
-- **Slug**: kebab-case, derived from the objective (`add-csv-export`, not `feature1`).
-- All artifacts are **human-readable Markdown** — they must survive context compaction
-  and a fresh session. (`references/` also holds binary assets the human supplied.)
-- **`/rite-spec` creates the workspace** and writes `spec.md` (+ `references/`,
-  `references.md`, `brief.md`, `questions.md`, `decisions.md`, `assumptions.md`; **plus
-  `design-brief.md` when the feature touches UI**, via `devrites-ux-shape`) and sets
-  `ACTIVE`. **`/rite-define` reads `spec.md`** and adds `plan.md` + `tasks.md` and updates
-  `state.md`. Other skills read the active workspace; none create a new one.
-- Each phase **updates `state.md`** and the relevant evidence files.
-- Don't create `checklists/` / `strategy.md` / `eng-review.md` / `test-plan.md` /
-  `coverage.md` / `devex.md` / `evidence.md` / `forge-report.md` / `browser-evidence.md` /
-  `design-brief.md` / `polish-report.md` / `review.md` / `seal.md` / `ship.md` / `handoff.md`
-  until the producing phase runs — absence is meaningful (it means "not done yet").
-  `coverage.md` is the `/rite-define` traceability matrix; `devex.md` is the conditional DX
-  scorecard (only when a developer-facing surface is in scope — greenfield no-op otherwise);
-  `forge-report.md` records a competitive `Forge: yes` build and is absent on the common
-  single-path slice. `strategy.md` is written by `/rite-temper` (which may also edit `spec.md` /
-  `decisions.md` / `assumptions.md` via the Spec Drift Guard); its absence means the spec was
-  planned without a strategic review. `eng-review.md` + `test-plan.md` are written by `/rite-vet`
-  (which also hardens `plan.md` / `tasks.md`, and routes acceptance-changing deltas via the Spec
-  Drift Guard); their absence means the plan was built without an engineering review. `handoff.md`
-  is written by `/rite-handoff` and overwritten each handoff (latest snapshot, not a log).
-- **`/rite-ship` closes the feature**: it writes `ship.md`, sets `state.md` phase `done`,
-  then archives `.devrites/work/<slug>/` → `.devrites/archive/<slug>/` (every `.md`
-  preserved) and clears `.devrites/ACTIVE`. Closing **relocates** the audit trail; it
-  never deletes it. Re-open by moving the dir back and re-pointing `ACTIVE`.
-
-## `state.md` template
-```markdown
-# State: <slug>
-
-- Phase: spec | temper | plan | vet | build | prove | polish | review | seal | ship | done   # `temper` (pre-plan) + `vet` (post-plan, pre-build) only when those optional reviews ran; spec→plan→build directly otherwise
-- Status: running | awaiting_human | blocked | done
-- Active slice: <N — name> | none
-- Slice mode: AFK | HITL | none
-- Spec gate: passed <iso> | none                    # optional — set when the spec readiness gate passes
-- Plan approved: <iso> | none                       # optional — /rite-define sets it when the human confirms the plan
-- AFK slices remaining: <n> | none                  # mutable counter; initialized from .devrites/AFK max_slices on first AFK build
-- Risk: <highest current risk> | none
-- Next step: <single recommended command + why>
-
-## Awaiting human   (only when Status == awaiting_human)
-- qid: <q-YYYY-MM-DD-NNN>
-- gate: advisory | validating | blocking | escalating
-- question: <crisp text>
-- proposed: <agent's tentative answer>
-- raised_at: <iso>
-- blocking_slices: [<slice ids that cannot advance until answered>]
-
-## Slice progress
-- [ ] Slice 1: <name> — <pending|built>
-- [ ] Slice 2: ...
-
-## Log
-- <date> <phase>: <one line of what happened>
-```
+Backward compatibility: if an installed project already uses
+`.devrites/features/<slug>/`, keep reading and updating that workspace. New
+writer instructions should prefer `.devrites/work/<slug>/`; migration adds
+canonical files and preserves aliases rather than deleting old ones.
 
-A slice is only ever `pending` or `built`. Acceptance proof lives at the **feature**
-level in `evidence.md` (recorded by `/rite-prove`), not per slice — there is no per-slice
-`proven` / `done` state.
+## Creation rules
 
-## `.devrites/AFK` sentinel (AFK mode toggle)
+- Slug is kebab-case and comes from the objective.
+- `/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-define` adds `architecture.md`, `plan.md`, `tasks.md`, and
+  `traceability.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
+  copying their content.
+- Use stable IDs: `REQ-001`, `AC-001`, `SLICE-001`, `DEC-001`, `Q-001`,
+  `DRIFT-001`, `EVID-001`.
 
-Presence of the file `.devrites/AFK` puts DevRites into **AFK mode**: skills that would
-normally pause for the user instead log to `questions.md` (when the gate severity allows
-it — see [`.claude/rules/afk-hitl.md`](../../../rules/afk-hitl.md)) and continue.
-`.devrites/AFK` presence is the **single source of truth** for run mode (the shared preamble
-derives it); skills re-read the sentinel at decision time rather than trusting a mirrored
-`state.md` field. The file content is optional YAML configuring loop discipline:
+## README.md template
 
-```yaml
-# .devrites/AFK — presence = AFK mode active. All keys optional.
-max_slices: 10                       # read-only INITIAL budget; the mutable remaining count lives in state.md
-notify: "ntfy.sh/my-topic"           # shell command run on awaiting_human transition; see afk-discipline.md for the env table
-allow_gates: [advisory, validating]  # gate severities AFK may auto-handle; everything else pauses
+```markdown
+# <Feature> Workspace
+phase: spec
+status: running
+next_action: /rite-define after spec readiness passes
+last_updated: <date>
+
+## Artifact map
+| File | Job |
+| --- | --- |
+| brief.md | Objective and bounds |
+| spec.md | Product contract |
+| architecture.md | Technical map; absent until /rite-define |
+| plan.md | Technical approach; absent until /rite-define |
+| tasks.md | Vertical slices; absent until /rite-define |
+| traceability.md | Coverage dashboard; absent until /rite-define |
+| evidence.md | Proof log; absent until /rite-prove |
+
+## Read next
+| Phase / role | Read |
+| --- | --- |
+| Spec | brief.md, spec.md, questions.md |
+| Build | state.md, tasks.md, plan.md |
+| Review | traceability.md, evidence.md, decisions.md |
+
+## Blocking gates
+None.
 ```
 
-`max_slices` is **read-only config** — never rewritten in place. The mutable remaining
-count lives in `state.md` as `AFK slices remaining: <n>`, initialized from `max_slices` on
-the first AFK build and decremented per built slice (the cap is enforced by
-`tick-afk.sh`, not by prose).
+## state.md template
 
-Absent or empty file = AFK active with defaults (`max_slices: unlimited`, no `notify`,
-`allow_gates: [advisory]`). **Destructive migrations, auth/authz boundary changes, and
-public-API breaks always pause regardless of `allow_gates`** — AFK never silently accepts
-irreversible risk.
+```markdown
+# State
+
+## Cursor
+| Key | Value |
+| --- | --- |
+| phase | spec |
+| status | running |
+| active_slice | none |
+| slice_mode | none |
+| risk | none |
+| next_action | <single command + reason> |
+
+## Awaiting human
+Only present when status is awaiting_human.
+| Key | Value |
+| --- | --- |
+| question_id | Q-001 |
+| gate | blocking |
+| blocking_slices | SLICE-001 |
+```
 
-## `questions.md` entry format
+`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`.
 
-`questions.md` is append-only. Each entry:
+## questions.md entry format
 
 ```markdown
-## q-2026-05-28-001
+## Q-001
 status: open | answered | dropped
-slice: 03-list-endpoint              # which slice raised it (or "spec" / "plan")
+slice: spec | plan | SLICE-001
 gate: advisory | validating | blocking | escalating
-question: <one crisp sentence the human can answer>
-options: |                           # ranked option set, recommended FIRST
-  1. <recommended> (Recommended) — <dimension-tagged rationale + trade-off>
-  2. <alternative> — <rationale + trade-off>
-  3. Something else — describe it
-proposed: <the recommended option restated — the HITL default + AFK auto-pick>
-raised_at: 2026-05-28T17:30:00Z
-answered_at: <iso when status flips to answered>
-answer: <chosen option / human's reply, verbatim>
-supersedes: <q-... if this replaces an answered entry, else omit>
+question: <one crisp sentence>
+options:
+  1. <recommended> (Recommended) - <trade-off>
+  2. <alternative> - <trade-off>
+proposed: <best current answer>
+raised_at: <iso>
+answered_at:
+answer:
+impact: <affected AC/REQ/slice IDs>
 ```
 
-Canonical schema + rules (gate taxonomy, option-set contract): [`.claude/rules/afk-hitl.md`](../../../rules/afk-hitl.md).
-`/rite-resolve <qid> "<answer>"` is the canonical mutator — manual edits work but the
-skill keeps `state.md` and `questions.md` consistent.
+No open blocking/escalating question may remain before define/build/prove gates.
+
+## brief.md template
 
-## `brief.md` template
 ```markdown
-# <Feature>
-Objective: <one sentence — what and for whom>
-Why now: <one line>
-Definition of done: <one line>
+# Brief: <Feature>
+
+## Objective
+<One sentence.>
+
+## Non-goals
+- <Explicitly out of scope.>
+
+## Success definition
+<One sentence that says what "done" means.>
 ```
 
-`decisions.md`, `assumptions.md`, `questions.md`, `drift.md`, `touched-files.md` are
-append-only running logs — date-stamped bullet entries.
+## Compactness
+
+High-traffic files should stay within the budgets in
+`workspace-artifact-schema.md`. If a file truly must exceed its budget, add
+`Budget override: <reason>` near the top.

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

@@ -1,6 +1,6 @@
 ---
 name: rite-status
-description: Read-only report on the active feature — phase, active slice, next action, evidence, open questions, drift, risks, and handoff readiness. Not for invoking phases or for the menu (use `/rite`).
+description: User-invoked read-only active-feature report: phase, active slice, next action, evidence, open questions, drift, risks, and handoff readiness.
 argument-hint: "[feature-slug]"
 user-invocable: true
 disable-model-invocation: true
@@ -12,22 +12,21 @@ Read-only. Report where the active feature stands. **Do not run any phase.**
 
 ## Load state
 
-Run this snippet (the shared DevRites preamble — one canonical command that
-resolves the install layouts: installed `.claude/` → plugin via `${CLAUDE_SKILL_DIR}`
-→ repo `pack/`, with a graceful fallback to reading `state.md`; default slug =
-`.devrites/ACTIVE`):
+Run the shared DevRites preamble plus the machine snapshot (default slug = `.devrites/ACTIVE`):
 
 ```bash
-P=.claude/skills/devrites-lib/scripts/preamble.sh
-[ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
-[ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
-[ -f "$P" ] && bash "$P" [feature-slug] || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
+devrites-engine preamble [feature-slug]
+devrites-engine snapshot [feature-slug]
 ```
 
-The preamble prints the active workspace's `state.md` and the list of artifacts
-present. The `!`-prefix dynamic-context-injection idiom is **not** used here so
-the skill stays portable across harnesses; the script is the cross-harness
-mechanism.
+The preamble is the human-readable orientation digest: it prints `state.md`, artifacts
+present, run mode, and open-question counts. The snapshot is the canonical
+cross-harness machine contract: phase, section completeness, current slice,
+evidence/drift/review freshness, capability readiness, and **both** host-specific
+next-command forms under `nextCommands` (`claude` = `/rite-*`, `codex` = `$rite-*`).
+Use the command form for the current host; do not invent or hardcode one.
+The `!`-prefix dynamic-context-injection idiom is **not** used here so the skill
+stays portable across harnesses; the `devrites` binary is the cross-harness mechanism.
 
 ## What to output
 
@@ -43,7 +42,8 @@ Otherwise summarize from the loaded state, concisely:
    `awaiting_human`, render the `Awaiting human` block from `state.md` (qid, gate,
    question, proposed, raised_at, blocking_slices) and instruct
    `/rite-resolve <qid> "<answer>"`.
-4. **Next action** — the single recommended next command.
+4. **Next action** — the single recommended next command from `snapshot.nextCommands`
+   for the current host.
 5. **Evidence** — what's proven vs unproven (from `evidence.md` /
    `browser-evidence.md`).
 6. **Open questions** — count by gate (from `questions.md`:
@@ -88,16 +88,20 @@ context into the workspace before the session ends.
 
 ## Output format
 
-**Footer first** — `/rite-status` *is* the status meter: render it by running the progress footer (`progress.sh`, resolved like the step-0 preamble — canonical snippet in `devrites-lib/SKILL.md`). The slice meter + flow ribbon answer "where am I / how much is left". Then the handoff-readiness check:
+**Progress first** — `/rite-status` *is* the status meter: render it by running
+`devrites-engine progress`. Then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md))
+as a read-only status variant:
 ```
-Ready for handoff: yes / partial (n gaps) / no
-
-Gaps (if any):
-- state.md "next action" lists 2 options, not 1
-- 3 open questions raised in conversation not yet in questions.md
-- ...
+Done: status read for <slug>; phase <phase> and active slice <slice|n/a>.
+Changed: workspace only
+Evidence: <current proof summary | not applicable yet>
+Open: <none | questions n | drift n | blockers n | handoff gaps n>
+Next: <single recommended command>
+Record: .devrites/work/<slug>/state.md
+↻ Hygiene: <handoff ready | /rite-handoff before /clear>
 ```
 
 If gaps exist, the recommended next command is to **persist them first** (see
-`.claude/rules/core.md` — "Persistence before stopping"). Only then
+`.claude/skills/devrites-lib/reference/standards/core.md` — "Persistence before stopping"). Only then
 move to the phase's next action.