devrites 5.10.1 → 5.11.0

package/pack/generated/devin/skills/rite-spec/reference/anti-patterns.md

@@ -0,0 +1,27 @@
+# rite-spec: anti-patterns
+
+Load this when standing a non-trivial decision in `/rite-spec`, or when the
+agent feels reluctance toward investigation depth, gap-closing, or
+placement decisions.
+
+Pack-wide rationalizations + red flags: see [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "User said *just make it work*: no spec needed." | Vague asks are exactly where `/rite-spec` earns its keep; load `devrites-interview` and ask one question at a time. |
+| "I already understand the request." | Then writing the placement + acceptance criteria takes minutes and saves drift later. Investigation isn't for *you*, it's for `/rite-define`. |
+| "Too small for a spec." | If it's big enough for `/rite-build`, it's big enough for one paragraph of WHAT/WHY + measurable acceptance. |
+| "No design refs were attached, so skip references." | Skip the *gathering*, not the *acknowledgement*. Note "no references provided" in the spec: silence is ambiguous. |
+| "I can resolve gaps as I build." | Drift discovered at slice 3 costs more than 5 questions answered now. |
+| "I'm confident of the answer, so I'll just decide this myself." | Confidence changes the *cost* of the question, not its *owner*. A material decision (scope · placement · data model · UX · security · migration · acceptance) is put to the human as a ranked option set: near-certainty just makes it a one-pick confirm, never a silent decision. |
+| "Presenting options for every gap is over-asking." | Over-asking is many questions at once or asking what the codebase answers. One ranked option set per *material* gap, recommended-first, is the opposite: it hands the human the decision cheaply. Reversible low-impact details you still auto-decide and log. |
+
+## Red Flags
+
+- About to start writing `spec.md` without a Placement & integration section.
+- Spec has no measurable acceptance criteria: "works as expected" is not measurable.
+- A `[NEEDS CLARIFICATION]` marker remains on a blocking item.
+- Design references were attached but never opened, saved, or indexed in `references.md`.
+- The investigation didn't read the module/component that currently owns this area.

package/pack/generated/devin/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/devin/skills/rite-spec/reference/investigation.md

@@ -0,0 +1,83 @@
+# Investigation before specification
+
+Understand the requirement, decide where it belongs, define the outcome, and identify
+every issue and gap. Resolve material gaps with the user before the spec is ready. A
+gap first found during `/rite-build` is a drift event.
+
+Use a code-intelligence index if available (see
+`../../devrites-lib/reference/standards/tooling.md`) for structural questions such as
+where code lives, what calls it, and what it could break. With none present, use
+Read/Grep/Glob. When a gap depends on an external fact, such as a standard, UX pattern,
+or comparable product, **search the web if available** (brave MCP preferred;
+`../../devrites-lib/reference/standards/tooling.md`). Cite the finding in the option
+presented to the human.
+
+## Check the archive first
+Before external research, check whether the project already shipped related work. Search
+the archive for the feature's key nouns. A hit may indicate an extension, conflict, or
+replacement and provides prior decisions:
+Use native file search over `.devrites/archive/*/{spec,decisions}.md`.
+- **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 request and problem:** restate the goal and the problem behind it (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**
+   - 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. **Outcome:** the result and how to observe it (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.
+8. **Human prerequisites:** credentials, accounts, approval windows, or irreversible
+   action-time decisions the acceptance path requires. Separate these from agent-owned
+   implementation and diagnostic work.
+
+Design/reference materials the human supplies: see [references-intake](references-intake.md).
+
+## Gap analysis (present → desired)
+State the present and desired states. Their delta defines the work; unknowns in that
+delta are gaps. Resolve them before `/rite-define`. Mark each gap inline with
+`[NEEDS CLARIFICATION: question]`.
+
+## Present gaps and issues as options
+For each material gap or issue that changes scope, placement, data model, UX, security,
+migration risk, or acceptance, **ask the human** one gap at a time with 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, but do not settle a material decision. High confidence may
+make the answer a one-pick confirmation; it does not change the decision owner.
+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 problem, current behavior, placement, and outcome 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.
+- Every foreseeable build-time human prerequisite is resolved, assigned, or justified as an
+  action-time gate; objective repair/retry work is not disguised as a question.
+- No blocking `[NEEDS CLARIFICATION]` remains. The spec covers the gaps found during
+  authoring and records correct placement. This is the `/rite-spec` readiness gate
+  before `/rite-clarify` performs the systematic topology scan.

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

@@ -0,0 +1,36 @@
+# Spec question protocol
+
+For vague or unknown intent, invoke `devrites-interview` for ordered one-question turns,
+recommendations, option sets, pass limits, reframing, and closure.
+This file owns only Spec-specific coverage and recording. Render through
+[`Option set`](../../devrites-lib/reference/standards/afk-hitl.md#option-set-how-every-gap-is-presented).
+
+## Coverage gate: am I done asking?
+Each dimension MUST be **resolved** or **explicitly deferred** (logged, non-blocking),
+never 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).
+- [ ] **Human prerequisites**: credentials, approval windows, irreversible action-time gates
+  (or "none").
+
+An agent recommendation is not a user answer. A human-owned material product, scope, UX,
+compatibility, or acceptance choice closes only by the user's option selection, free-form
+answer, or explicit deferral. Packets MAY be bounded; readiness MUST NOT. Rescan and continue
+while blockers remain. If the user stops, keep them blocking and MUST NOT pass `/rite-spec`
+readiness.
+
+## Spec question boundary
+- Search code, decisions, authoritative docs before asking discoverable facts.
+- Decide and log agent-owned reversible implementation/test details.
+- Record tooling failures as prerequisites or blockers; never ask the human to authorize repair.
+- Ask only material choices, not everything at once.
+
+## Record
+Confirmed answers → `decisions.md` (with rationale). Agent-owned reversible, low-impact
+technical assumptions →
+`assumptions.md`. Open non-blocking items → `questions.md`.

package/pack/generated/devin/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/devin/skills/rite-spec/reference/spec-checklists.md

@@ -0,0 +1,89 @@
+# Spec-quality checklists
+
+Before `/rite-define`, test requirement prose for completeness, clarity, and
+measurability—not implementation. “Banner is prominent” lacks a threshold; ask
+whether export defines empty data, never whether `exportCsv()` handles `[]`.
+Function/file/library checks belong to `/rite-vet` and `/rite-prove`.
+
+## Output: one file per requirement domain
+
+Emit `.devrites/work/<slug>/checklists/<domain>.md` per covered domain; skip
+`none`. Each domain maps gaps 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` | Invariants; security/privacy/accessibility, latency/scale, compatibility, operations, and human-only proof prerequisites. |
+| `edge-cases.md` | Empty/boundary/invalid/concurrent/failure/recovery paths plus the spec's applicability map. |
+
+## 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 | REQ-001..004 | — |
+| 3 | Are all enumerations closed — no "etc." / "and so on" / open "…"? | pass | — | — |
+```
+
+Verdict: `pass | fail | n/a`. A fail is **CRITICAL** when ambiguity changes build
+or acceptance: unquantified success, open enumeration, ambiguous data shape,
+undefined stated-flow edge, or contradictory requirements. Other vague prose is
+**minor**: record it; do not block.
+
+## Question bank
+
+Each question checks one requirement-prose failure mode:
+
+- **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.
+- **Assumptions:** no material behavior, scope, data, security, or proof fact survives as a
+  hidden assumption; verify it or record an owned/deadlined assumption or blocking question.
+- **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.
+- **Stakeholders:** affected actors/operators are named; conflicting outcomes have an
+  explicit priority or decision owner rather than two simultaneously impossible promises.
+- **Applicability:** topology, data, integration, security, UI/i18n/time zone, and
+  compatibility/delivery rows are `applies` with IDs or specifically justified `not applicable`.
+- **Failure/recovery:** each partial, timeout, invalid, interrupted, or unavailable state
+  implied by an applicable row has a user outcome, system state, and safe retry/recovery rule.
+- **Data:** schema/backfill/concurrency/tenant/retention implications state invariants and
+  prohibited loss/leakage; implementation detail stays for Define.
+- **Integration:** timeout, invalid/partial response, auth/rate-limit/outage, duplicate,
+  ordering, and version-change behavior is specified when the boundary can produce it.
+- **Preservation:** each material brownfield outcome appears in `Existing behavior
+  to preserve` with preserving REQ/AC and current evidence. Missing/vague “no
+  regressions” or unjustified `none` is CRITICAL.
+  **Failing case:** brownfield login still works but the table has no evidence column
+  → CRITICAL until a test path, command, or observed contract is named.
+- **Backstops:** each row names an independent held-out, property/metamorphic, or
+  direct behavioral check and the failure it discriminates; confidence/presence/self-review fail.
+- **Non-functional:** each NFR names affected REQ/AC IDs or a bounded `global` scope;
+  human-only proof prerequisites name their owner.
+
+## Readiness gate
+
+The spec **Readiness gate** at the bottom of
+[`spec-template.md`](spec-template.md) requires every
+emitted `checklists/<domain>.md` to 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 step 0 and **hard-blocks while any CRITICAL is
+unchecked**. A spec without checklists is not yet checked, so define stops and routes
+back here.
+
+## Discipline
+
+- Score honestly. Do not soften a checklist question to pass a weak spec.
+- Don't pad. Five real questions that find one CRITICAL beat thirty rubber-stamped rows.
+- If a question needs a function name, it belongs in `/rite-vet`'s `test-plan.md`.

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

@@ -0,0 +1,154 @@
+# `spec.md` template
+
+Contract WHAT users get, WHY, success, and scope. HOW belongs in `plan.md`,
+topology in `architecture.md`/`flows.md`, coverage in `traceability.md`.
+
+Use `[NEEDS CLARIFICATION: <question>]` (blocking stops `/rite-clarify`); before readiness
+every surviving marker converts to a gated `Q-###` open question ([`spec-grammar.md`](../../devrites-lib/reference/standards/spec-grammar.md) §
+Unresolved-question markers — fail closed). Stable `REQ-001`/`AC-001` IDs; link, never
+duplicate, source artifacts; over-budget requires `Budget override: <reason>`.
+
+```markdown
+# Spec: <Feature>
+Slug: <kebab-case>
+Status: Draft | Ready
+Created: <date>
+
+## Problem
+<What is broken, missing, or costly.>
+
+## Goal
+<User-visible outcome and why it matters.>
+
+Capability impact: <affected capability/ies and change | none — specific justification>
+
+## Non-goals
+- <Explicitly out of scope.>
+
+## Existing behavior to preserve
+List affected observable public/security/data/operational outcomes that MUST
+survive; map preserving REQ/AC plus current test/runtime/contract/source evidence.
+No implementation detail. True greenfield: `none — no existing behavior in the affected scope`.
+
+| Existing outcome | Preserved by | Current evidence |
+| --- | --- | --- |
+| <outcome that must not regress> | REQ-001 / AC-001 | <current evidence> |
+
+Each preservation row **must** cite current evidence (test, runtime, contract, or
+observed behavior). An empty or vague evidence cell blocks Spec readiness.
+
+**Failing case:** row lists REQ-001 with evidence "none" or "TBD" → readiness gate
+fails until evidence is named or the outcome is removed from scope.
+
+## Stakeholders and priorities
+| Actor/stakeholder | Observable outcome | Conflict / priority rule |
+| --- | --- | --- |
+| <actor or affected owner> | <goal, protection, or operational need> | <none or how competing goals resolve> |
+
+## Constraints and invariants
+- INV-001: <fact that MUST remain true across success, failure, retry, and recovery>.
+- <security/privacy/accessibility/performance/compatibility/data/operational constraint,
+  or `none — <specific reason>` for a materially relevant category>.
+
+## Requirements
+- REQ-001: The system MUST <observable product behavior>.
+- REQ-002: The system MUST NOT <prohibited behavior>.
+
+## Acceptance criteria
+Binary/evidence-backed; each maps to a requirement and later a traceability slice.
+
+- [ ] AC-001: Given <state>, when <action>, then <outcome>. (REQ-001)
+- [ ] AC-002: Given <state>, when <action>, then <outcome>. (REQ-002)
+
+Behavioral/high-risk work uses this grammar, with the AC ID inside the scenario:
+
+### Requirement: <name>
+The system SHALL <core observable behavior>.
+
+#### Scenario: <name>
+- [ ] AC-003: **WHEN** <trigger> **THEN** <observable outcome>. (REQ-001)
+
+## Edge Coverage
+Use `covered | backstop | dismissed | unresolved`; target an existing REQ/AC
+unless dismissed. `backstop` requires a named independent held-out,
+property/metamorphic, or direct behavioral check plus the wrong behavior it
+discriminates. If unavailable, use `unresolved`; presence/prose/self-judgment cannot pass.
+
+| Edge ID | Requirement/AC | Class | Status | Reason/backstop |
+| --- | --- | --- | --- | --- |
+| EDGE-001 | AC-001 | empty/error/permission/race/migration | covered | <evidence/rationale> |
+
+## Prohibitions (must-NOT)
+Bespoke only; generic security/privacy stays in standards. Status:
+`resolved/test | resolved/judgment | dismissed | unresolved`.
+
+| Prohibition ID | Requirement/AC | Status | Test/evidence |
+| --- | --- | --- | --- |
+| PROH-001 | REQ-002 | resolved/test | <test/evidence link> |
+
+## Failure and recovery behavior
+| Trigger / partial state | User-visible outcome | System state | Recovery / retry rule | Requirement/AC |
+| --- | --- | --- | --- | --- |
+| <timeout, invalid input, interruption, dependency loss> | <clear bounded outcome> | <unchanged/pending/reconciling> | <who/what can safely recover> | <REQ/AC> |
+
+## Applicability map
+Use `applies | not applicable`; a non-applicable row needs a specific reason. The
+status routes Define/Vet/Build/Prove to the named standard without copying it here.
+
+| Concern | Status and trigger | Affected REQ/AC/invariant |
+| --- | --- | --- |
+| Repository topology (nested/mono/multi-repo, languages, services, generated/vendor) | <status + reason> | <ids> |
+| Data integrity (writes, schema/migration, concurrency, tenant, retention/privacy) | <status + reason> | <ids> |
+| Integration reliability (API/webhook/queue/job/cache/cross-service) | <status + reason> | <ids> |
+| Security boundary (authn/authz, hostile input/files, secrets, privilege) | <status + reason> | <ids> |
+| UI/accessibility/i18n/time-zone behavior | <status + reason> | <ids> |
+| Compatibility/delivery (old/new versions, config, flag, rollout/rollback) | <status + reason> | <ids> |
+
+## Edge cases
+- <Boundary note not captured above.>
+
+## AI-SPEC annex
+- Model/RAG/agent/eval/LLM-output scope: `ai-spec.md` from `ai-spec-template.md`.
+- Otherwise: not applicable.
+
+## Success metrics
+- <Metric or observable proof.>
+
+## Scope boundaries
+- Owns: <surface/behavior>.
+- Does not own: <adjacent area>.
+- Placement summary: <module/layer>; full map in `architecture.md`.
+
+## Coverage seed
+- Actors/journeys/components: <material surfaces>.
+- States/data/contracts/integrations: <material boundaries>.
+- Operations/proof: <config, observability, rollout/rollback, evidence constraints>.
+
+## References
+- `brief.md`: request/outcome/scope; `architecture.md`: placement/integration;
+  `flows.md`: Mermaid-first diagrams (optional `visual/<flow>.html`+`.outline.md` companion
+  + link when richer presentation earns it — load playbooks via
+  [`index.md`](../../devrites-lib/reference/visual-playbooks/index.md)); `decisions.md`: decisions;
+  `decision-coverage.md`: Clarify topology/verdict; `traceability.md`: Define coverage;
+  `design-brief.md`: UI direction.
+
+## Open questions
+| Question ID | Gate | Question | Impact |
+| --- | --- | --- | --- |
+| Q-001 | blocking | [NEEDS CLARIFICATION: <question>] | AC-001 |
+
+## Readiness gate
+- [ ] No blocking clarification or open `blocking`/`escalating` question; REQ/AC IDs are valid and ACs independently provable.
+- [ ] Stakeholder conflicts/priority rules, constraints, and invariants are explicit;
+      implementation preferences are not disguised as requirements.
+- [ ] Existing affected behavior maps to preserving REQ/AC + current evidence, or uses the exact justified greenfield `none`.
+- [ ] Edge rows target REQ/AC or justify dismissal; every backstop names independent discriminating evidence, else `unresolved`.
+- [ ] Prohibitions resolve/dismiss; `resolved/test` links evidence.
+- [ ] Each material failure/partial state names user outcome, system state, recovery,
+      and REQ/AC; no silent success or blind retry remains.
+- [ ] Every applicability row is `applies` with affected IDs or has a specific
+      evidence-backed `not applicable` reason.
+- [ ] AI has `ai-spec.md` and UI has `design-brief.md`; out-of-scope work states not applicable.
+- [ ] Non-goals/scope are explicit; capability impact is singular/specific and matches ledger deltas.
+- [ ] Architecture/flows/decisions are linked, not duplicated; Coverage seed names Clarify surfaces.
+```