devrites 2.6.1 → 3.0.0

package/pack/generated/claude/skills/rite-spec/reference/interview-patterns.md

@@ -0,0 +1,56 @@
+# Interview patterns
+
+Question ladders by domain. Pull the rung that matches the biggest current unknown.
+Each question still follows the protocol: one at a time, best guess attached.
+
+## Vague ask? Map the decision tree first
+For a fuzzy one-liner (`"design a contact page"`, `"add reporting"`), sketch the branches
+the answer splits into, then resolve each **depth-first** — one branch to a decision before
+opening the next:
+
+```text
+contact page
+├─ purpose?   ── sales lead | support request | general
+├─ fields?    ── name/email/message | + company/phone | file upload
+├─ on submit? ── email | ticket/CRM | DB row | embedded third-party form
+└─ success?   ── inline confirm | redirect | autoresponder
+```
+
+Once per interview you may **challenge the premise** instead of refining it
+(*"is a form even the right answer, or a mailto / booking link?"*) — a good reframe
+collapses whole branches. Then use the domain ladders below for each open branch.
+
+## Objective / problem
+- "What does success look like in one sentence?"
+- "Who hits this, how often, and what do they do today instead?"
+- "If we shipped only one thing here, what must it be?"
+
+## Scope boundaries
+- "What is explicitly **out** of scope for this first version?"
+- "Is this a new capability or a change to an existing flow?"
+- "What's the smallest version that's still useful?" (→ slice 1)
+
+## Data model
+- "What are the core entities and how do they relate?"
+- "What's the source of truth, and can these fields change after creation?"
+- "Any uniqueness, ordering, or soft-delete needs?"
+
+## UX / flow
+- "Walk me through the happy path screen by screen."
+- "What are the empty / loading / error / permission-denied states?"
+- "Brand surface (marketing) or product surface (app UI)?" (drives craft)
+
+## Integration / external
+- "Which external systems or APIs are involved, and who owns them?"
+- "Sync or async? What happens when the dependency is down?"
+
+## Non-functional
+- "Any latency, scale, or volume targets I should design to?"
+- "Auth/permission rules? Anything sensitive (PII, secrets, payments)?"
+
+## Acceptance
+- "How will we *prove* this works — what's the test or observation?"
+- "What would make you reject the PR?"
+
+## Anti-references (taste)
+- "Show me one thing that does this well, and one that does it badly."

package/pack/generated/claude/skills/rite-spec/reference/investigation.md

@@ -0,0 +1,84 @@
+# Investigation — understand deeply before specifying
+
+The spec is only as good as the investigation behind it. Goal: understand the
+requirement **completely**, decide **where it correctly belongs**, name what it
+**resolves**, and surface every **issue and gap** — then drive the gaps to closure with
+the user so the spec ships fully-covered and correctly-placed. A gap found here is cheap;
+a gap found in `/rite-build` is a drift event.
+
+Use a code-intelligence index if available (see
+`../../devrites-lib/reference/standards/tooling.md`) for the structural parts below; it answers "where does this
+live / what calls it / what would it break" far more cheaply and accurately than reading files.
+With none present, fall back to Read/Grep/Glob. When a gap turns on a fact the codebase can't
+answer — a standard, a prevailing UX pattern, how comparable products solve it — **search the
+web if available** (brave MCP preferred; `../../devrites-lib/reference/standards/tooling.md`) and cite the finding in
+the option you present, so the human's pick is informed rather than guessed.
+
+## Prior art — check our own archive first (cheap, silent when empty)
+Before investigating outward, check whether we already shipped this. Grep the shipped
+archive for the feature's key nouns — a hit means an extension, a conflict, or a re-spec of
+solved work, and you inherit its decisions instead of re-deriving them:
+```bash
+devrites-engine archive-search "<key nouns>" 2>/dev/null \
+  || grep -rliE '<noun1>|<noun2>' .devrites/archive/*/spec.md 2>/dev/null
+```
+- **Overlap found** → read the overlapping `spec.md` + its `decisions.md`, then put it to
+  the human as a ranked option — *extend the shipped feature* · *this supersedes it* ·
+  *genuinely distinct* — same option-set contract as a gap.
+- **No archive / no hit** → skip silently; never block a spec on absent history (the
+  brownfield / principles no-op discipline).
+
+## Produce these findings (write into spec.md)
+1. **The real ask** — restate the goal and the *problem behind the request* (people ask
+   for "a dashboard" when they want an answer to a question). Who hits it, how often,
+   what they do today instead.
+2. **Current behavior** — how it works today, or what's absent. Read the actual code and
+   flows; don't assume.
+3. **Placement — where it should live** *(so it's correctly placed to be used)*
+   - Which module / layer / file / component should own this; the right seam.
+   - Existing patterns/components/utilities to **extend or reuse** instead of duplicating.
+   - **Integration points**: callers and dependents, the data it reads/writes, the
+     APIs/events/contracts it touches (interface analysis — how it interacts with the
+     rest of the system).
+4. **What it resolves** — the outcome/value and how we'll *observe* it's resolved (feeds
+   success + acceptance criteria).
+5. **Issues** — conflicts with existing code/UX/data/permissions, constraints, and
+   anything that makes the obvious approach wrong. Each issue gets a disposition.
+6. **Gaps** — unknowns, ambiguities, undecided behavior, missing inputs. **Every gap
+   becomes a question** (next section).
+7. **Blast radius** — what this change could break (use the code graph's impact/callers).
+   Informs risks, test strategy, and rollback.
+
+Also gather any **design/reference materials** the human supplies (screenshots, Figma,
+links, video) — see [references-intake](references-intake.md). They're part of
+understanding the requirement and become the target later phases verify against.
+
+## Gap analysis (present → desired)
+State the **present state** and the **desired state**; the delta is the work, and the
+**unknowns in the delta are the gaps**. Drive the count of open gaps toward zero before
+handing off to `/rite-define`. Mark each gap inline with `[NEEDS CLARIFICATION: question]`.
+
+## Turn gaps & issues into questions WITH options — you recommend, the human decides
+For each material gap/issue (one that changes scope, placement, data model, UX, security,
+migration risk, or acceptance), **put it to the human** — one gap at a time, as a ranked
+option set with the recommended option **first and marked `(Recommended)`** plus an escape
+hatch (via `AskUserQuestion` in HITL):
+```
+<gap/issue stated in one line>. Why it matters: <...>
+1. <recommended option> (Recommended) — <implication / where it places the work; cite any web/docs finding>
+2. <alternative> — <implication>
+3. <alternative> — <implication>
+4. Something else — I'll describe it
+```
+Investigate and recommend; don't settle a material decision yourself. Confidence in the answer
+lowers the *cost* of the question (a one-pick confirm), not its owner — present the set anyway.
+Only a **genuinely reversible, low-impact** gap is decided and recorded in `assumptions.md`
+without asking. Full render contract + AFK behaviour: [`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md).
+
+## Done when
+- The shipped archive was checked for prior art; any overlap was surfaced to the human.
+- The real problem, current behavior, placement, and what-it-resolves are written down.
+- Every issue has a disposition; every material gap is resolved **by a human pick** from its
+  option set (or explicitly deferred as non-blocking) — not settled silently on your confidence.
+- No blocking `[NEEDS CLARIFICATION]` remains — the spec is **fully covered and correctly
+  placed**. This is the `/rite-spec` readiness gate before `/rite-define` plans it.

package/pack/generated/claude/skills/rite-spec/reference/question-protocol.md

@@ -0,0 +1,31 @@
+# Spec question protocol
+
+For vague or unknown intent, invoke `devrites-interview`; it owns question order,
+one-question turns, best guesses, option sets, blocking-question budget, reframing,
+and completion. The shared HITL/AFK rendering contract lives in
+[`afk-hitl.md` § Option set](../../devrites-lib/reference/standards/afk-hitl.md#option-set--how-every-gap-is-presented).
+
+This reference owns only the spec-specific coverage and recording rules below.
+
+## Coverage gate — am I done asking?
+Before declaring the interview complete, each dimension is **resolved** or **explicitly
+deferred** (logged, non-blocking) — never silently skipped:
+- [ ] **Objective** — one-sentence success + the real problem behind it.
+- [ ] **Scope** — what's in vs explicitly out for v1.
+- [ ] **Data model** — core entities + relationships (or "none").
+- [ ] **UX / flow** — happy path + empty / loading / error / permission states (or "no UI").
+- [ ] **Integration** — external systems / APIs / contracts (or "none").
+- [ ] **Non-functional** — auth, sensitive data, latency / scale (or "n/a").
+- [ ] **Acceptance** — how each requirement is *proven* (test / observation).
+
+A blocking gap in any dimension keeps the interview open; a deferred one goes to
+`questions.md` and doesn't block. This feeds the `/rite-spec` readiness gate.
+
+## Spec question boundary
+- Things the codebase answers (read it first).
+- Reversible implementation details (decide and note as an assumption).
+- Everything at once "to be thorough." Thoroughness is depth on the few that matter.
+
+## Record
+Confirmed answers → `decisions.md` (with rationale). Standing assumptions →
+`assumptions.md`. Open non-blocking items → `questions.md`.

package/pack/generated/claude/skills/rite-spec/reference/references-intake.md

@@ -0,0 +1,62 @@
+# Reference intake — design/style materials from the human
+
+During spec, the human may supply screenshots, Figma, video, sites, or docs showing how the
+feature should look or behave. When present, inspect them, save local copies, and classify
+each as a fidelity **target**, hard **constraint**, or **inspiration** so a mood reference
+cannot become a pixel-match contract. No references is valid; skip this intake.
+
+## Gather + understand each reference
+- **Images / screenshots / mockups** — open and **view** them (the Read tool renders
+  images). Describe what they show: layout, components, spacing, states, the target look.
+- **Figma link** — if a Figma integration is available, pull its design context (frames,
+  tokens, components); otherwise record the link and ask the human for an export/screenshot
+  so there's something concrete to match offline.
+- **Links / reference sites / docs** — fetch and read for the relevant intent (tone,
+  layout, interaction, quality bar). Capture *why* it's a reference, not just the URL.
+- **Video** — note what it demonstrates (the expected interaction/flow). Save it; later
+  phases can step through it as tooling allows.
+
+## Save local assets into the workspace
+Copy any local file (screenshot, mockup, video, export) into
+`.devrites/work/<slug>/references/` so it's durable and connectable later:
+```
+mkdir -p .devrites/work/<slug>/references
+cp "<the file the human gave>" .devrites/work/<slug>/references/<clear-name>.<ext>
+```
+Use clear names (`login-mockup.png`, `checkout-flow.mp4`). Don't move the user's
+original; copy it. For remote-only refs (a live Figma/URL), record the link in the index.
+Index source/owner/license and **reference-only** or **may ship** usage; external screenshots
+never grant rights to copy brand, copy, or assets.
+
+## Index in `references.md`
+```markdown
+# References: <slug>
+| Ref | Role | Usage / provenance | Type | Location | Shows / why it's a reference | Informs |
+|-----|------|--------------------|------|----------|------------------------------|---------|
+| R1 | target | project; may ship | screenshot | references/login-mockup.png | approved composition + spacing | spec UI, slice 2, proof |
+| R2 | constraint | project; may ship | figma | https://figma.com/… | required tokens + components | all UI |
+| R3 | target | user; reference-only | video | references/checkout-flow.mp4 | approved step order + transitions | build, proof |
+| R4 | inspiration | external; reference-only | link | https://example.com | tone + density, not identity/layout | shape |
+```
+
+Roles are normative: **target** means compare fidelity, **constraint** means satisfy the
+named rule, and **inspiration** means extract the cited principle without copying identity,
+composition, copy, or distinctive assets. Usage is normative too: only **may ship** assets
+enter product code.
+
+## Feed them into the spec + the design brief
+- Use references to sharpen `spec.md` (UI impact, success/acceptance — e.g. "matches R1").
+- When the feature touches UI, these references are the primary input to **`devrites-ux-shape`**
+  (spec step 3a): they anchor the design direction and can seed the visual-direction probe
+  (a Figma link → pulled design context; reference sites → screenshots). The resulting
+  `design-brief.md` cites them by R-id **and role**.
+- A reference can *resolve a gap* ("which layout?") — record that in the gaps table.
+- If a reference **conflicts** with the existing design system, that's an issue to raise
+  with the human (match the system, or adopt the reference — their call).
+
+## Later phases use them (wire-through)
+`devrites-frontend-craft` builds to the approved brief and its **target** references,
+honors **constraints**, and uses **inspiration** only for the named principle. `/rite-prove`
+records rendered comparisons in `browser-evidence.md`; `/rite-polish` and `/rite-seal`
+reuse that same contract. Save and classify once here so every downstream phase makes the
+same fidelity decision.

package/pack/generated/claude/skills/rite-spec/reference/spec-checklists.md

@@ -0,0 +1,73 @@
+# Spec-quality checklists — "unit tests for the English"
+
+Before the spec hands off to `/rite-define`, test the **requirement prose itself** the way you'd
+unit-test code: is each requirement complete, unambiguous, and measurable? These checklists
+interrogate the *writing*, not the implementation — there is no code to run yet. A criterion like
+"the banner is prominent" passes a human skim and fails here ("prominent" is unquantified).
+Catching it now is a one-line spec edit; catching it at `/rite-prove` is a reslice.
+
+**Not implementation tests.** A checklist item asks "is *export* defined for an empty dataset?" —
+it does **not** ask "does `exportCsv()` handle `[]`?". The first tests the spec; the second is
+`/rite-vet`'s test-plan and `/rite-prove`'s job. These files never name a function, file, or library.
+
+## Output — one file per requirement domain
+
+Emit `.devrites/work/<slug>/checklists/<domain>.md`, one per domain the spec actually covers (skip
+a domain the spec marks "none"). The domains mirror the interview taxonomy, so a gap here maps to a
+`devrites-interview` dimension:
+
+| Domain file | Tests the prose of |
+|---|---|
+| `functional.md` | Functional requirements + scenarios — is each capability stated, bounded, testable? |
+| `data-model.md` | Key entities / data model — shapes, fields, lifecycle, relationships (skip if "none"). |
+| `interaction.md` | API / UI impact + UX states — every screen state and contract named (skip if no UI/API). |
+| `non-functional.md` | Constraints, auth / data sensitivity, latency / scale / compatibility budgets. |
+| `edge-cases.md` | Empty / boundary / invalid / concurrent / failure paths the requirements imply. |
+
+## Each item — a question, a verdict, the line it interrogates
+
+```markdown
+# Spec checklist: <domain> — <slug>
+Scored: <iso>   Verdict: pass | gaps (<n CRITICAL / n minor>)
+
+| # | Question (tests the requirement prose) | Verdict | Spec line | Severity |
+|---|---|---|---|---|
+| 1 | Is every quantitative qualifier ("prominent", "fast", "large") given a number or reference? | fail | "banner is prominent" | **CRITICAL** |
+| 2 | Does each requirement name an observable outcome a test could check? | pass | FR-001..004 | — |
+| 3 | Are all enumerations closed — no "etc." / "and so on" / open "…"? | pass | — | — |
+```
+
+Verdict is `pass` / `fail` / `n/a`. A `fail` carries a severity:
+- **CRITICAL** — the ambiguity would change the build or its acceptance: an unquantified
+  acceptance/success criterion, an incomplete enumeration in a requirement, an ambiguous data
+  shape, an undefined edge case on a stated flow, a contradictory pair of requirements.
+- **minor** — vague but non-load-bearing prose. Record it; it does not block.
+
+## The question bank (seed — extend per domain)
+
+Each question tests one of the failure modes of requirement prose:
+- **Measurability** — every "good / fast / prominent / simple / secure" carries a number, a budget,
+  or a named reference. No adjective stands in for a threshold.
+- **Completeness** — every enumeration is closed (no "etc."); every requirement with a precondition
+  states the failure branch; every entity names its required fields + lifecycle; every stated flow
+  names its empty / error / boundary behaviour.
+- **Clarity** — one entity, one name (no `user`/`customer`/`account` drift); no requirement two
+  readers would implement differently; no "should" where "MUST" is meant.
+- **Testability** — each acceptance criterion is binary and names (or clearly implies) its evidence.
+  A criterion only provable by reading code is a fail.
+- **Consistency** — no requirement contradicts another, the data model, or a non-goal.
+
+## How it feeds the readiness gate
+
+The spec **Readiness gate** (bottom of [`spec-template.md`](spec-template.md)) folds these in: every
+emitted `checklists/<domain>.md` must reach `Verdict: pass` (zero CRITICAL fails) before the gate
+passes. Minor fails are logged, not blocking. A single open CRITICAL keeps the spec `Status: Draft`.
+`/rite-define` reads the checklists at its step 0 and **hard-blocks while any CRITICAL is unchecked**;
+a spec that skips the checklists is treated as not-yet-scored — define stops and routes back here.
+
+## Discipline
+- Score honestly. A checklist you pass by softening the *question* instead of the *spec* is the
+  spec-quality version of weakening a test to go green — it defeats the gate.
+- Don't pad. Five real questions that find one CRITICAL beat thirty rubber-stamped rows.
+- These are *English* tests. The moment a question needs a function name to answer, it belongs in
+  `/rite-vet`'s `test-plan.md`, not here.

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

@@ -0,0 +1,110 @@
+# `spec.md` template
+
+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`.
+
+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>
+Status: Draft | Ready
+Created: <date>
+
+## Problem
+What is broken, missing, or costly today.
+
+## Goal
+One paragraph describing the user-visible outcome and why it matters.
+
+## Non-goals
+- <Explicitly out of scope.>
+
+## Users / actors
+| Actor | Need |
+| --- | --- |
+| <actor> | <goal> |
+
+## Requirements
+- REQ-001: The system MUST <observable product behavior>.
+- REQ-002: The system MUST NOT <prohibited behavior>.
+
+## Acceptance criteria
+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.
+
+### Requirement: <name>
+The system SHALL <core observable behavior>.
+
+#### 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/generated/claude/skills/rite-spec/reference/state-workspace.md

@@ -0,0 +1,156 @@
+# `.devrites/` state workspace
+
+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/
+  ACTIVE
+  work/
+    <feature-slug>/
+      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>/
+```
+
+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.
+
+## Creation rules
+
+- 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`.
+
+## README.md template
+
+```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.
+```
+
+## state.md template
+
+```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 |
+```
+
+`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 entry format
+
+```markdown
+## Q-001
+status: open | answered | dropped
+slice: spec | plan | SLICE-001
+gate: advisory | validating | blocking | escalating
+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>
+```
+
+No open blocking/escalating question may remain before define/build/prove gates.
+
+## brief.md template
+
+```markdown
+# Brief: <Feature>
+
+## Objective
+<One sentence.>
+
+## Non-goals
+- <Explicitly out of scope.>
+
+## Success definition
+<One sentence that says what "done" means.>
+```
+
+## 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.