@gobing-ai/spur 0.2.5 → 0.2.8

package/spur-cli/config/tasks/section-matrix.yaml

@@ -0,0 +1,188 @@
+# Section-Status-Matrix: which sections are required/optional/forbidden per task status.
+# Design §3.2 — evaluated CLI-side only. Ships permissive; tightened by compliance data.
+#
+# Each VARIANT (the unified template axis — TASK_VARIANTS) maps status →
+# { required, optional, forbidden } section lists. Sections reference the canonical
+# section vocabulary (§2.1). `gate: true` on a status makes L2 violations hard errors.
+#
+# The variant is selected by a task's `template:` frontmatter (default: `standard`).
+# It drives BOTH validation (`spur task check`) AND creation (`buildTaskSkeleton`).
+$schema: "@gobing-ai/spur/schemas/section-matrix.schema.json"
+
+variants:
+  # Workhorse general-purpose task.
+  standard:
+    backlog:
+      required: [Background]
+      forbidden: [Solution, Review, Testing]
+    # todo = "ready to execute" (§2.3): fully specified and HITL-reviewable.
+    # Design + Plan + Acceptance Criteria are required so a task can be reviewed
+    # and approved before any code is written. Solution stays forbidden — it is
+    # the implementation change-map (file:line), authored at wip/testing.
+    todo:
+      required: [Background, Acceptance Criteria, Design, Plan]
+      optional: [Q&A, Requirements]
+      forbidden: [Solution, Review, Testing]
+    wip:
+      required: [Background, Acceptance Criteria, Design, Plan]
+      optional: [Q&A, Requirements, Solution]
+      forbidden: [Review]
+    testing:
+      required: [Solution, Testing]
+      optional: [Background, Review]
+    # done REQUIRES the evidence trio (Solution/Testing/Review). The spec sections
+    # a task was built from (Design/Plan/AC/…) are OPTIONAL, not forbidden, so a
+    # finished task keeps its design history rather than being stripped to pass the
+    # closed-world gate. gate:true still hard-fails a missing required section.
+    done:
+      required: [Solution, Testing, Review]
+      optional: [Background, Requirements, Acceptance Criteria, Q&A, Design, Plan]
+      gate: true
+    blocked:
+      required: [Background]
+      optional: [Plan, Solution]
+    cancelled:
+      required: []
+      optional: [Background]
+
+  # Feature implementation — AC pre-seeded from the linked feature's scenarios.
+  feature-impl:
+    backlog:
+      required: [Background]
+      forbidden: [Solution, Review, Testing]
+    todo:
+      required: [Background, Acceptance Criteria, Design, Plan]
+      optional: [Q&A, Requirements]
+      forbidden: [Solution, Review, Testing]
+    wip:
+      required: [Background, Acceptance Criteria, Design, Plan]
+      optional: [Q&A, Requirements, Solution]
+      forbidden: [Review]
+    testing:
+      required: [Solution, Testing]
+      optional: [Background, Requirements, Acceptance Criteria, Design, Plan, Review]
+    # done keeps the spec sections optional (see `standard` rationale above) so a
+    # finished feature-impl task retains its Design/Plan/AC history.
+    done:
+      required: [Solution, Testing, Review]
+      optional: [Background, Requirements, Acceptance Criteria, Q&A, Design, Plan]
+      gate: true
+    blocked:
+      required: [Background]
+      optional: [Plan, Solution]
+    cancelled:
+      required: []
+      optional: [Background]
+
+  # Bug / issue report — repro in Background, verified Root Cause, then fix.
+  issue:
+    backlog:
+      required: [Background]
+      forbidden: [Solution, Review]
+    todo:
+      required: [Background, Root Cause, Plan]
+      optional: [Acceptance Criteria, Design, Q&A]
+      forbidden: [Solution, Review]
+    wip:
+      required: [Background, Root Cause, Plan]
+      optional: [Design, Solution, Q&A]
+      forbidden: [Review]
+    testing:
+      required: [Root Cause, Solution, Testing]
+      optional: [Background, Review]
+    done:
+      required: [Root Cause, Solution, Testing, Review]
+      optional: [Background, Acceptance Criteria, Design, Plan, Q&A]
+      gate: true
+    blocked:
+      required: [Background]
+      optional: [Root Cause, Plan]
+    cancelled:
+      required: []
+      optional: [Background]
+
+  # Code-review result task — the deliverable is the P1–P4 findings table.
+  #
+  # The review template scaffolds Background (with #### Review Findings sub-section),
+  # Plan (checklist), and Review (forward reference for post-implementation reflection).
+  # Plan and Review are optional at backlog/todo so the template renders cleanly;
+  # Review becomes required at wip+.
+  #
+  # Solution and Testing are optional at wip+ — not required, but tolerated so that
+  # a review-findings task that evolves into implementation work (the common dogfood
+  # follow-up path) can carry a change-map and coverage data without matrix violations.
+  # The required list guards the real deliverables; optional is permissive on purpose.
+  review:
+    backlog:
+      required: [Background]
+      optional: [Plan, Review]
+      forbidden: [Testing]
+    todo:
+      required: [Background, Plan]
+      optional: [Q&A, Review]
+      forbidden: [Testing]
+    wip:
+      required: [Background, Review]
+      optional: [Plan, Q&A, Solution, Testing]
+    testing:
+      required: [Background, Review]
+      optional: [Plan, Solution, Testing]
+    done:
+      required: [Background, Review]
+      optional: [Plan, Q&A, Solution, Testing]
+      gate: true
+    blocked:
+      required: [Background]
+      optional: [Plan, Review, Solution]
+    cancelled:
+      required: []
+      optional: [Background]
+
+  # Process / docs / chore — lightweight: Background + Plan, no Solution/AC gate.
+  meta:
+    backlog:
+      required: [Background]
+      forbidden: [Review]
+    todo:
+      required: [Background, Plan]
+      optional: [Q&A, Design]
+      forbidden: [Review]
+    wip:
+      required: [Background, Plan]
+      optional: [Q&A, Design, Solution]
+      forbidden: [Review]
+    testing:
+      required: [Background, Plan]
+      optional: [Solution, Testing]
+    done:
+      required: [Background, Plan]
+      optional: [Solution, Testing, Review]
+    blocked:
+      required: [Background]
+      optional: [Plan]
+    cancelled:
+      required: []
+      optional: [Background]
+
+  # Brainstorm template (minimal idea capture).
+  brainstorm:
+    backlog:
+      required: [Background]
+      forbidden: [Solution, Review, Testing]
+    todo:
+      required: [Background]
+      optional: [Q&A]
+    wip:
+      required: [Background, Plan]
+      optional: [Q&A, Design]
+      forbidden: [Review]
+    testing:
+      required: [Background, Solution]
+      optional: [Testing]
+      forbidden: [Review]
+    done:
+      required: [Background, Solution]
+    blocked:
+      required: [Background]
+    cancelled:
+      required: []

package/spur-cli/config/tasks/templates/brainstorm.md

@@ -0,0 +1,29 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: brainstorm
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: []
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+### Q&A
+
+### Plan
+
+### References
+
+### History

package/spur-cli/config/tasks/templates/feature-impl.md

@@ -0,0 +1,50 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: task
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: []
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+### Acceptance Criteria
+
+```gherkin
+Feature: {{ NAME }}
+
+  Scenario: Basic acceptance
+    Given a precondition
+    When an action is taken
+    Then an expected result occurs
+```
+
+- [ ] Acceptance checklist item
+
+### Design
+
+### Plan
+
+- [ ] Implementation step
+
+### Solution
+
+### Testing
+
+### Review
+
+### References
+
+### History

package/spur-cli/config/tasks/templates/issue.md

@@ -0,0 +1,33 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: issue
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: ["bug"]
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+### Root Cause
+
+### Solution
+
+### Testing
+
+### Review
+
+### References
+
+### History

package/spur-cli/config/tasks/templates/meta.md

@@ -0,0 +1,31 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: meta
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: ["meta"]
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+### Plan
+
+- [ ] Implementation step
+
+### Testing
+
+### References
+
+### History

package/spur-cli/config/tasks/templates/review.md

@@ -0,0 +1,48 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: review
+template: review
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: ["review"]
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+#### Review Findings
+
+The code-review findings this task must address — logged here as **input** (what was found
+in the reviewed PR/commit/diff). Fix in priority order (P1 → P2 → …); re-review after.
+
+| Severity | File | Finding | Recommendation |
+| -------- | ---- | ------- | -------------- |
+| P1       |      |         |                |
+| P2       |      |         |                |
+
+### Plan
+
+- [ ] Fix P1 findings
+- [ ] Fix P2 findings
+- [ ] Fix all the remaining findings if any
+- [ ] Re-review the changed code
+
+### Review
+
+Post-implementation reflection — filled **after** the first fix round: what went wrong, what
+remains to fix before closing, and any **back-issues** (new findings surfaced by the fix).
+
+### References
+
+### History

package/spur-cli/config/tasks/templates/standard.md

@@ -0,0 +1,48 @@
+---
+schema_version: 1
+name: "{{ NAME }}"
+description: ""
+status: backlog
+type: task
+profile: standard
+feature_id: null
+parent_wbs: null
+priority: P2
+tags: []
+dependencies: []
+created_at: "{{ CREATED_AT }}"
+updated_at: "{{ CREATED_AT }}"
+---
+
+## {{ WBS }}. {{ NAME }}
+
+### Background
+
+{{ BACKGROUND }}
+
+### Acceptance Criteria
+
+```gherkin
+Feature: {{ NAME }}
+
+  Scenario: Basic acceptance
+    Given a precondition
+    When an action is taken
+    Then an expected result occurs
+```
+
+- [ ] Acceptance checklist item
+
+### Plan
+
+- [ ] Implementation step
+
+### Solution
+
+### Testing
+
+### Review
+
+### References
+
+### History

package/spur-cli/config/templates/bdd/checklist.md

@@ -0,0 +1 @@
+- [ ] {{ CHECKLIST_ITEM }}

package/spur-cli/config/templates/bdd/gherkin.md

@@ -0,0 +1,8 @@
+```gherkin
+Feature: {{ FEATURE_NAME }}
+
+  Scenario: {{ SCENARIO_NAME }}
+    Given a precondition
+    When an action is taken
+    Then an expected result occurs
+```

package/spur-cli/config/templates/docs/00_ADR.md

@@ -0,0 +1,27 @@
+---
+name: Architecture Decision Records
+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
+---
+
+# 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.
+
+## ADR-001 — (example) Adopt this doc structure
+
+- **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.
+
+<!--
+Add new ADRs here. Copy the entry shape above (Date, Status, Context, Decision, Reason).
+A decision that reverses a prior ADR adds a new entry that says "supersedes ADR-NNN".
+-->

package/spur-cli/config/templates/docs/01_PRD.md

@@ -0,0 +1,37 @@
+---
+name: Product Requirements Document
+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
+---
+
+# 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.)_
+
+## 2. Users
+
+| User | Primary need |
+|------|-------------|
+| _(user persona)_ | _(their primary need)_ |
+
+## 3. Scope
+
+### In scope
+
+- _(capability the product delivers)_
+
+### Out of scope
+
+- _(explicitly excluded capability — prevents scope creep)_
+
+### Deferred
+
+- _(capability intentionally postponed — not a commitment)_

package/spur-cli/config/templates/docs/02_ROADMAP.md

@@ -0,0 +1,22 @@
+---
+name: Roadmap
+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
+---
+
+# 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)_ |
+
+**Status legend:** ✅ done · 🔶 partial · ⏳ planned · 💤 deferred

package/spur-cli/config/templates/docs/03_ARCHITECTURE.md

@@ -0,0 +1,27 @@
+---
+name: Architecture
+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
+---
+
+# Architecture
+
+> Derived (ADR wins). Read before cross-module/seam/schema work; edit when boundaries or mechanisms change.
+
+## 1. Module map
+
+```
+_(ascii tree or diagram of the major modules and their boundaries)_
+```
+
+## 2. Data flow
+
+_(Describe the primary data path: input → processing → output. Name the seams.)_
+
+## 3. Invariants
+
+- _(state or property that always holds — the thing tests should protect)_

package/spur-cli/config/templates/docs/04_DESIGN.md

@@ -0,0 +1,30 @@
+---
+name: Design
+doc: 04_DESIGN
+owns: SURFACE — concrete shapes: every CLI command, flag, config key, env var, table, DTO
+authority: derived
+version: 1.0.0
+created_at: 1970-01-01T00:00:00.000Z
+updated_at: 1970-01-01T00:00:00.000Z
+---
+
+# Design
+
+> Derived. Concrete shapes — every command, flag, config key, env var, schema, and DTO. Edit when
+> a surface changes.
+
+## 1. CLI commands
+
+```
+_(command) <positional> [--flag <value>] [--json]
+```
+
+| Command | Description |
+|---------|-------------|
+| _(command)_ | _(one-line description)_ |
+
+## 2. Configuration keys
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| _(key)_ | _(type)_ | _(default)_ | _(description)_ |

package/spur-cli/config/templates/docs/05_FEATURES.md

@@ -0,0 +1,23 @@
+---
+name: Features
+doc: 05_FEATURES
+owns: STATUS — feature decomposition + state
+authority: derived
+version: 1.0.0
+created_at: 1970-01-01T00:00:00.000Z
+updated_at: 1970-01-01T00:00:00.000Z
+---
+
+# Features
+
+> Derived. Feature status roll-up. Edit when a feature's status changes.
+
+## Status legend
+
+✅ done · 🔶 partial · ⏳ planned · 💤 deferred
+
+## Feature tree
+
+| ID | Feature | Status | Parent | Notes |
+|----|---------|--------|--------|-------|
+| F1 | _(root feature)_ | ⏳ planned | — | _(one-line scope)_ |

package/spur-cli/config/templates/docs/99_PROJECT_CONSTITUTION.md

@@ -0,0 +1,65 @@
+---
+name: Project Constitution
+doc: 99_PROJECT_CONSTITUTION
+owns: PROCESS — how the key files are maintained
+authority: authoritative-on-process
+version: 1.0.0
+created_at: 1970-01-01T00:00:00.000Z
+updated_at: 1970-01-01T00:00:00.000Z
+---
+
+# Project Constitution — How to Organize the Project
+
+> **This is a template.** Spur's own constitution at
+> [docs/99_PROJECT_CONSTITUTION.md](https://github.com/gobing-ai/spur/blob/main/docs/99_PROJECT_CONSTITUTION.md)
+> is the canonical version. Copy the full content there into this file for a real project, then
+> localize the Lessons section (§8) and the tool-binding column (§3).
+
+## 1. What this is & what this is not
+
+This is the **constitution** for the project's key files: an accumulated, machine-maintained set
+of rules and lessons for running the same file structure across different projects and
+cooperating with multiple coding agents (Claude Code, Codex, Gemini CLI, pi, Antigravity,
+OpenCode, OpenClaw, ...).
+
+- One copy lives in every project at `docs/99_PROJECT_CONSTITUTION.md`.
+- It is **byte-identical across projects** except the Lessons sections (§8) and the tool-binding
+  column (§3). When it improves in one project, propagate to the others — forks are drift.
+- It contains **zero project-specific facts** — no project command names, package names, feature
+  states, or decisions. Project facts live in the numbered docs this file governs.
+
+## 2. Authority model
+
+| Axis | Question | Winner |
+|------|----------|--------|
+| **Content** | What is true about the project? | Lower number wins: `00_ADR` is binding on *decisions*; `01_PRD` is authoritative on *scope*; `02`–`05` are derived |
+| **Process** | How are the key files maintained? | **This file** |
+
+## 3. Doc map
+
+| Doc | Owns the question | Authority |
+|-----|-------------------|-----------|
+| `00_ADR.md` | **WHY** — decisions + one-line reason | Authoritative (wins all) |
+| `01_PRD.md` | **WHAT** — product vision, scope | Authoritative on scope |
+| `02_ROADMAP.md` | **WHEN** — phases, sequencing | Derived |
+| `03_ARCHITECTURE.md` | **HOW** — module boundaries, data flow | Derived |
+| `04_DESIGN.md` | **SURFACE** — commands, flags, schemas | Derived |
+| `05_FEATURES.md` | **STATUS** — feature decomposition + state | Derived |
+| `99_PROJECT_CONSTITUTION.md` | **PROCESS** — how files are maintained | Authoritative on process |
+
+## 4. Sync triggers
+
+When a change touches one of these, the listed doc MUST be updated in the **same commit**:
+
+| ID | Trigger | Doc(s) |
+|----|---------|--------|
+| T1 | New cross-cutting decision | `00` first, then `03` mechanism |
+| T3 | Command/flag/config/schema/DTO added/changed | `04` + `AGENTS.md` |
+| T4 | Feature ships or changes state | `05` row |
+| T6 | Scope added / cut / deferred | `01` |
+
+## 5. Lessons
+
+| Date | Lesson |
+|------|--------|
+| 1970-01-01 | _(empty — add lessons as the project evolves)_ |