@gobing-ai/spur 0.3.20 → 0.3.23

package/config/rules/typescript/prefer-accessible-role-for-button-queries.yaml

@@ -0,0 +1,31 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Forbid getByLabelText queries on button accessible names in web component tests.
+#
+# WHY: HTML `<button>` elements are non-labellable per WHATWG HTML spec. In DOM Testing
+# Library, `getByLabelText` queries elements associated with `<label>` tags. When used to
+# query a `<button>` with an `aria-label` attribute, it works when happy-dom DOM state is
+# fresh, but throws `TestingLibraryElementError: element associated with this label is non-labellable`
+# when running in full multi-file test suites on CI (e.g. Linux runners).
+# Real incident: CI-only failure in apps/web/tests/modules/task-kanban/components.test.tsx on 2026-07-24.
+#
+# FIX: Use `getByRole('button', { name: '...' })` or `getByRole('button', { name: /.../ })`,
+# which queries the W3C accessible name provided by `aria-label`.
+include:
+  - "apps/web/tests/**/*.test.ts"
+  - "apps/web/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+
+rules:
+  - id: prefer-accessible-role-for-button-queries
+    description: >
+      Do not query button accessible names with `getByLabelText` in web React tests.
+      `<button>` elements are non-labellable per WHATWG spec, causing timing-dependent
+      CI failures when tests run sequentially in a single process.
+      Use `getByRole('button', { name: ... })` instead.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        pattern: "getByLabelText\\(['\"]Sort "

package/config/templates/docs/00_ADR.md

@@ -4,29 +4,39 @@ doc: 00_ADR
 owns: WHY — which cross-cutting decision was made, and the one-line reason
 authority: authoritative
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: any structural change
+edit_rules: 99 §6.1
+sync: [T1, T2]
 ---
 
 # Architecture Decision Records
 
-> Authoritative on **decisions**. Lower number wins — this doc overrides all others on decisions.
-> Each entry is append-only; supersession is by a new dated entry, never by editing an old one.
-> Only real cross-cutting decisions belong here — not implementation notes, not feature status, not
-> how-to guidance. Entries that grow past decision + reason are carrying mechanism that belongs in
-> `03`/`04`; link it instead of inlining it.
+## ADR-001 — Adopt this doc structure
 
-## ADR-001 — (example) Adopt this doc structure
+**Status:** Accepted · **Date:** {{init-date}}
 
-- **Date:** 1970-01-01
-- **Status:** accepted
-- **Context:** Project needs a single source of truth for decisions and scope.
-- **Decision:** Adopt the Spur doc structure (`00`–`05` + `99` constitution).
-- **Reason:** Separates WHY (`00`) from WHAT (`01`) from HOW (`03`/`04`) — one fact, one home.
+**Decision.** Adopt the Spur doc structure (`00`–`05` + `99` constitution).
+
+**Why.** Separates WHY (`00`) from WHAT (`01`) from HOW (`03`/`04`) — one fact, one home.
+
+**Detail:** `docs/99_PROJECT_CONSTITUTION.md` §4.1.
 
 <!--
-Add new ADRs here. Copy the entry shape above (Date, Status, Context, Decision, Reason).
+Add new ADRs here. Entry shape (per 99 §6.1):
+
+## ADR-NNN: <Decision title, outcome-shaped>
+
+**Status:** Accepted | Accepted (design) | Superseded by ADR-MMM | Skipped · **Date:** YYYY-MM-DD
+
+**Decision.** <What was decided — the smallest complete statement of the choice.>
+
+**Why.** <One line. The single strongest reason.>
+
+**Detail:** <pointer into 03/04/plans — depth never lives here.>
+
 A decision that reverses a prior ADR adds a new entry that says "supersedes ADR-NNN".
 An Amendment records the decision delta + one-line reason — not the mechanism. Implementation
 paths, detailed semantics, and multi-paragraph rationale belong in 03/04, not in the amendment.
--->
+-->

package/config/templates/docs/01_PRD.md

@@ -4,14 +4,15 @@ doc: 01_PRD
 owns: WHAT — product vision, users, scope (in / out / deferred)
 authority: authoritative-on-scope
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: adding a command or feature
+edit_rules: 99 §6.2
+sync: [T1, T4, T6]
 ---
 
 # Product Requirements Document
 
-> Authoritative on **scope**. In-scope vs out-of-scope vs deferred lives here and nowhere else.
-
 ## 1. Vision
 
 _(One sentence: what this product is and who it is for.)_
@@ -28,10 +29,14 @@ _(One sentence: what this product is and who it is for.)_
 
 - _(capability the product delivers)_
 
-### Out of scope
+### Supporting
 
-- _(explicitly excluded capability — prevents scope creep)_
+- _(capability that enables an in-scope item but is not user-facing)_
 
 ### Deferred
 
-- _(capability intentionally postponed — not a commitment)_
+- _(capability intentionally postponed — not a commitment; carry the condition that would reactivate it)_
+
+### Out of scope
+
+- _(explicitly excluded capability — prevents scope creep)_

package/config/templates/docs/02_ROADMAP.md

@@ -4,19 +4,27 @@ doc: 02_ROADMAP
 owns: WHEN — phases, current vs deferred, sequencing
 authority: derived
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+derived_from: [00_ADR, 01_PRD]
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: placing work in a phase
+edit_rules: 99 §6.3
+sync: [T5]
 ---
 
 # Roadmap
 
-> Derived from `01_PRD` (scope) and `00_ADR` (decisions). Edit when phase status changes.
-
 ## Phases
 
-| Phase | Status | Items |
-|-------|--------|-------|
-| Phase 0 — Foundation | ✅ done | _(list the real, shipped deliverable names)_ |
-| Phase 1 — _(name)_ | ⏳ planned | _(items)_ |
+| Phase | Status | Items | Exit criterion |
+|-------|--------|-------|----------------|
+| Phase 0 — Foundation | ✅ done | _(list the real, shipped deliverable names)_ | _(what must be true to exit)_ |
+| Phase 1 — _(name)_ | ⏳ planned | _(items)_ | _(what must be true to exit)_ |
 
 **Status legend:** ✅ done · 🔶 partial · ⏳ planned · 💤 deferred
+
+<!--
+Markers: [x] done · [~] partial · [ ] pending. [x]/[~] carry a one-line evidence note.
+When a deliverable lands under a different name than planned, rewrite the bullet to the real name.
+Insert sub-phases (1.5) rather than renumbering existing ones.
+-->

package/config/templates/docs/03_ARCHITECTURE.md

@@ -4,14 +4,16 @@ doc: 03_ARCHITECTURE
 owns: HOW — module boundaries, data flow, runtime model, invariants
 authority: derived
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+derived_from: [00_ADR, 01_PRD]
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: cross-module, seam, or schema work
+edit_rules: 99 §6.4
+sync: [T1]
 ---
 
 # Architecture
 
-> Derived (ADR wins). Read before cross-module/seam/schema work; edit when boundaries or mechanisms change.
-
 ## 1. Module map
 
 ```
@@ -24,4 +26,9 @@ _(Describe the primary data path: input → processing → output. Name the seam
 
 ## 3. Invariants
 
-- _(state or property that always holds — the thing tests should protect)_
+- _(state or property that always holds — phrased so a constraint rule or reviewer can check it mechanically)_
+
+<!--
+Describes the CURRENT architecture only. Future/accepted designs go in sections explicitly
+titled "(accepted design — ADR-NNN; not yet built)". On conflict with 00, the ADR wins; fix here.
+-->

package/config/templates/docs/04_DESIGN.md

@@ -1,17 +1,29 @@
 ---
 name: Design
 doc: 04_DESIGN
-owns: SURFACE — concrete shapes: every CLI command, flag, config key, env var, table, DTO
+owns: SURFACE — concrete shapes: every CLI command, flag, config key, env var, table, DTO; index over docs/design/
 authority: derived
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+derived_from: [00_ADR, 01_PRD]
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: changing a command, flag, env var, or schema
+edit_rules: 99 §6.5
+sync: [T3, T9]
 ---
 
 # Design
 
-> Derived. Concrete shapes — every command, flag, config key, env var, schema, and DTO. Edit when
-> a surface changes.
+> **Index page** over `docs/design/` satellites (99 §4.5). Each surface area gets a
+> `docs/design/<slug>.md` satellite; this index carries the surface map + pointers.
+> Edit order: satellite first, then index row — same change (T9).
+
+## UI/UX boundary
+
+Repository-root `DESIGN.md` owns all UI/UX design, including visual language, design tokens,
+components, layout, interaction, accessibility, and responsive behavior. Read and update it for UI
+work; keep this document focused on non-UI surface design. If `DESIGN.md` is absent, follow the
+project's established UI conventions rather than adding UI guidance here.
 
 ## 1. CLI commands
 
@@ -19,12 +31,18 @@ updated_at: 1970-01-01T00:00:00.000Z
 _(command) <positional> [--flag <value>] [--json]
 ```
 
-| Command | Description |
-|---------|-------------|
-| _(command)_ | _(one-line description)_ |
+| Command | Description | Design doc |
+|---------|-------------|------------|
+| _(command)_ | _(one-line description)_ | `docs/design/_(slug)_.md` |
 
 ## 2. Configuration keys
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | _(key)_ | _(type)_ | _(default)_ | _(description)_ |
+
+<!--
+Shapes only — rationale lives in 00/03. Behavioral notes are shapes ("resolving zero rules exits 1"
+— keep); justifications are not ("...because a silent gate is the worst failure mode" — cut).
+Transcribe command signatures from the code registrations, never from memory.
+-->

package/config/templates/docs/05_FEATURES.md

@@ -1,16 +1,22 @@
 ---
 name: Features
 doc: 05_FEATURES
-owns: STATUS — feature decomposition + state
+owns: STATUS — feature decomposition + state; index over docs/features/
 authority: derived
 version: 1.0.0
-created_at: 1970-01-01T00:00:00.000Z
-updated_at: 1970-01-01T00:00:00.000Z
+derived_from: [00_ADR, 01_PRD]
+owner: _(project owner)_
+updated_at: {{init-date}}
+read_before: finding a feature's state
+edit_rules: 99 §6.6
+sync: [T4, T9]
 ---
 
 # Features
 
-> Derived. Feature status roll-up. Edit when a feature's status changes.
+> **Index page** over `docs/features/` satellites (99 §4.5). Both the satellites and this index's
+> generated region are **tool-owned** (e.g. `spur feature`/`ftree`); edit through the tool, never
+> with raw file writes. Edit order: satellite first, then refresh index (T9).
 
 ## Status legend
 
@@ -18,6 +24,11 @@ updated_at: 1970-01-01T00:00:00.000Z
 
 ## Feature tree
 
-| ID | Feature | Status | Parent | Notes |
-|----|---------|--------|--------|-------|
-| F1 | _(root feature)_ | ⏳ planned | — | _(one-line scope)_ |
+| ID | Feature | Status | Parent | Notes | Satellite |
+|----|---------|--------|--------|-------|-----------|
+| F1 | _(root feature)_ | ⏳ planned | — | _(one-line scope)_ | `docs/features/F1__(slug)_.md` |
+
+<!--
+Never trust a row you have not verified — check status against code before citing or building on it.
+One item per satellite; <feature-id> is the stable grep anchor. Renaming is a tool operation.
+-->