@gobing-ai/spur 0.3.77 → 0.3.80

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.3.77",
+            "version": "0.3.80",
             "source": "./plugins/sp"
         }
     ]

package/config/templates/AGENTS.md

@@ -90,35 +90,39 @@ Invoke CLI: `spur <noun> <verb> … --json` (or the project’s documented dev e
 
 ## Documentation
 
-**Process SSOT:** `docs/99_PROJECT_CONSTITUTION.md`. Operate with **`sp:doc-evolve`**
-(`drift-audit`, `sync-check`, `contract-verify`, `lesson-append`).
-
-**Conflict rule:** lower number wins on content (`00` decisions, `01` scope, `99` process). Fix
-authority first, then derived docs, then this file.
+Read [the constitution](docs/99_PROJECT_CONSTITUTION.md) before key-document edits.
+It owns document responsibilities and maintenance; `00` owns architectural choices,
+`01` product scope, and root `DESIGN.md` UI/UX. Use **`sp:doc-evolve`** for drift,
+sync and contract checks. Follow host/operator precedence.
 
 ### Doc map
 
-| Doc | Owns | Authority | When |
-| ------ | ------ | ----------- | ------ |
-| `docs/00_ADR.md` | **WHY** | Authoritative (content) | Structural change; dated entry before diverging |
-| `docs/01_PRD.md` | **WHAT** | Authoritative on scope | New feature/command |
-| `docs/02_ROADMAP.md` | **WHEN** | Derived | Phase placement |
-| `docs/03_ARCHITECTURE.md` | **HOW** | Derived (ADR wins) | Cross-module / seam / schema |
-| `docs/04_DESIGN.md` | **SURFACE** (+ `docs/design/`) | Derived | Same commit as surface code (T3) |
-| `docs/05_FEATURES.md` | **STATUS** (+ `docs/features/`) | Derived | Feature status (T4) |
-| `docs/99_PROJECT_CONSTITUTION.md` | **PROCESS** | Authoritative on process | Before editing numbered docs |
-| `AGENTS.md` (this file) | **ENTRY** | Derived | First every session |
-
-**Routing:** decision → `00`; scope → `01`; mechanism → `03`; surface → `04`; phase → `02`;
-feature status → `05`. Working-layer, audit, and satellite rules live in the project constitution.
+| File | Owns | Update when |
+| --- | --- | --- |
+| `AGENTS.md` | ENTRY: orientation, commands, constraints, owner links | Essential repo facts or routing change |
+| `DESIGN.md` | UI/UX: tokens, components, layout, interaction, accessibility | Shared UI design changes |
+| `docs/00_ADR.md` | WHY: lasting architectural choices and tradeoffs | A meaningful cross-module boundary or invariant changes |
+| `docs/01_PRD.md` | WHAT: vision, users, capability scope | Scope changes |
+| `docs/02_ROADMAP.md` | WHEN: phases, dependencies, exits | Phase commitments or sequencing change |
+| `docs/03_ARCHITECTURE.md` | HOW: current topology, data flow, runtime, invariants | Mechanisms or boundaries change |
+| `docs/04_DESIGN.md` + `docs/design/` | SURFACE: index and non-UI contracts | CLI/API/config/schema or boundary behavior changes |
+| `docs/05_FEATURES.md` + `docs/features/` | STATUS: entry to tool-owned feature records | Feature tool updates lifecycle/acceptance |
+| `docs/99_PROJECT_CONSTITUTION.md` | PROCESS: stable document-governance metadata | Authorized responsibility, authority or maintenance correction |
+
+**Placement guard:** feature approvals, task progress and test receipts do not belong in ADRs.
+Preserve ADR numbers and decision history when condensing. Tasks own execution evidence;
+existing context/learning storage owns lessons. Do not append either to the constitution.
+A constitution edit needs a specific governance defect and operator-authorized scope (§6.8).
+Update only owners whose facts changed; portable changes also update init templates.
+Keep `04` an index and `05` a pointer to the generated feature index, without duplicate ledgers.
 
 ---
 
 ## Design system
 
-**Conditional contract:** If repository-root `DESIGN.md` exists, leverage it dynamically as the industry-standard SSOT for UI design documentation — visual language, color tokens, typography, component specs, layout, micro-animations, accessibility, and responsive patterns. Read it before planning or implementing any UI changes, and keep affected work consistent with it. If `DESIGN.md` is absent, ignore it and continue with the project's established UI conventions.
-
-**Boundary distinction:** Root `DESIGN.md` owns UI/UX design guidance; `docs/04_DESIGN.md` owns non-UI surface design by default (command signatures, flags, config schemas, DTOs, and system boundaries). When working with design teams, choose `DESIGN.md` for UI/UX visual design and `docs/04_DESIGN.md` for non-UI API/schema surfaces.
+**Conditional contract:** Read root `DESIGN.md` before UI work when present; otherwise use
+established UI conventions. It owns visual and interaction design. Non-UI contracts belong in
+`docs/04_DESIGN.md` and its satellites; system mechanisms belong in `docs/03_ARCHITECTURE.md`.
 
 ---
 
@@ -183,8 +187,7 @@ catalog here or maintain generated per-platform capability copies in the project
   `BREAKING CHANGE:` footer.
 - Never commit secrets or `.env*`.
 - Surgical changes only — no drive-by refactors or speculative abstractions.
-- Surface changes keep `docs/04_DESIGN.md` in the **same commit** (T3); run `sp:doc-evolve`
-  sync-check when unsure.
+- Surface changes update their owning design satellite (T3); feature changes use the feature tool (T4).
 - **One writer per working tree.** Two agent sessions in one checkout overwrite each other silently
   — the symptom reads as a model regression. Parallel agent work uses git worktree isolation (one
   branch + one tree per agent).

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

@@ -1,9 +1,9 @@
 ---
 name: Architecture Decision Records
 doc: 00_ADR
-owns: WHY — which cross-cutting decision was made, and the one-line reason
+owns: WHY — lasting architectural choices, context and tradeoffs
 authority: authoritative
-version: 1.0.0
+version: 1.1.0
 owner: _(project owner)_
 updated_at: {{init-date}}
 read_before: any structural change
@@ -13,30 +13,20 @@ sync: [T1, T2]
 
 # Architecture Decision Records
 
-## ADR-001 — Adopt this doc structure
+Architectural choices only; admission and editorial rules: constitution §6.1.
+Record context, the chosen alternative, material tradeoffs/consequences and a detail link.
+Feature approvals, task updates and test receipts stay in their owning records.
+Preserve every issued ADR number, title and decision history.
 
-**Status:** Accepted · **Date:** {{init-date}}
+<!-- No decision is pre-accepted by scaffolding. Add a real founding decision when made.
 
-**Decision.** Adopt the Spur doc structure (`00`–`05` + `99` constitution).
+## ADR-NNN: <Architectural choice>
 
-**Why.** Separates WHY (`00`) from WHAT (`01`) from HOW (`03`/`04`) — one fact, one home.
+**Status:** Accepted | Accepted (design) · **Date:** YYYY-MM-DD
 
-**Detail:** `docs/99_PROJECT_CONSTITUTION.md` §4.1.
+**Decision.** <Lasting boundary or invariant selected among meaningful alternatives.>
 
-<!--
-Add new ADRs here. Entry shape (per 99 §6.1):
+**Why / tradeoff.** <Context, strongest reason, and material cost or consequence.>
 
-## 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.
--->
+**Detail:** <Owning architecture/design reference.>
+-->

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

@@ -3,7 +3,7 @@ name: Product Requirements Document
 doc: 01_PRD
 owns: WHAT — product vision, users, scope (in / out / deferred)
 authority: authoritative-on-scope
-version: 1.0.0
+version: 1.1.0
 owner: _(project owner)_
 updated_at: {{init-date}}
 read_before: adding a command or feature
@@ -39,4 +39,7 @@ _(One sentence: what this product is and who it is for.)_
 
 ### Out of scope
 
-- _(explicitly excluded capability — prevents scope creep)_
+- _(explicitly excluded capability — prevents scope creep)_
+
+<!-- Capability scope only. Delivery state belongs in feature records, sequencing in 02,
+and implementation in 03/04. Do not duplicate command catalogs or task updates. -->

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

@@ -3,28 +3,24 @@ name: Roadmap
 doc: 02_ROADMAP
 owns: WHEN — phases, current vs deferred, sequencing
 authority: derived
-version: 1.0.0
+version: 1.1.0
 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]
+sync: [T5, T6]
 ---
 
 # Roadmap
 
-## Phases
+Phase goals, order, dependencies and exits only. Detailed feature state belongs in the
+feature tool's index; task progress belongs in task records (constitution §6.3).
 
-| 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)_ |
+## Phase 0 — Foundation
 
-**Status legend:** ✅ done · 🔶 partial · ⏳ planned · 💤 deferred
+_(Goal and dependencies, based on actual project scope.)_
 
-<!--
-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.
--->
+- [ ] _(Coarse deliverable; use its real name and link to the feature.)_
+
+**Exit:** _(Observable conditions required to complete this phase.)_

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

@@ -3,7 +3,7 @@ name: Architecture
 doc: 03_ARCHITECTURE
 owns: HOW — module boundaries, data flow, runtime model, invariants
 authority: derived
-version: 1.0.0
+version: 1.1.0
 derived_from: [00_ADR, 01_PRD]
 owner: _(project owner)_
 updated_at: {{init-date}}
@@ -30,5 +30,5 @@ _(Describe the primary data path: input → processing → output. Name the seam
 
 <!--
 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.
+titled "(accepted design — ADR-NNN; not yet built)". Keep command/schema detail in 04 satellites and task delivery receipts in task records.
 -->

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

@@ -1,9 +1,9 @@
 ---
 name: Design
 doc: 04_DESIGN
-owns: SURFACE — concrete shapes: every CLI command, flag, config key, env var, table, DTO; index over docs/design/
+owns: SURFACE — index of non-UI CLI, API, config, schema and boundary contracts
 authority: derived
-version: 1.0.0
+version: 1.1.0
 derived_from: [00_ADR, 01_PRD]
 owner: _(project owner)_
 updated_at: {{init-date}}
@@ -14,38 +14,19 @@ sync: [T3, T9]
 
 # Design
 
-> **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).
+Non-UI contract index (constitution §6.5). Keep signatures, schemas, defaults, errors
+and boundary behavior in the owning `docs/design/<slug>.md` satellite.
 
 ## UI/UX boundary & DESIGN.md
 
-Repository-root `DESIGN.md` owns all UI/UX design documentation (industry standard visual language, color tokens, typography, component specs, accessibility, and responsive patterns). Read and update it for UI work; keep `docs/04_DESIGN.md` focused on non-UI surface design by default. If `DESIGN.md` is absent, ignore it and follow the project's established UI conventions.
+Root `DESIGN.md`, when present, owns UI/UX visual and interaction design.
+Architecture mechanisms belong in `03_ARCHITECTURE.md`.
 
-By contrast, `docs/04_DESIGN.md` is our SSOT of non-UI surface design by default — covering CLI command signatures, flags, config schemas, DTOs, tables, and system boundaries.
+## Surface map
 
-When collaborating with the design team:
-- **UI/UX & Visual Design:** Refer to and update repository-root `DESIGN.md`.
-- **Non-UI Surface & API/Schema DTOs:** Refer to and update `docs/04_DESIGN.md` (and `docs/design/<slug>.md` satellites).
+| Area | Contract reference |
+| --- | --- |
+| _(Existing CLI/API/config/schema area)_ | _(Link to its owning satellite when created)_ |
 
-## 1. CLI commands
-
-```
-_(command) <positional> [--flag <value>] [--json]
-```
-
-| 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.
--->
+Update a satellite when its contract changes; update this index only when its pointers change.
+Do not create a satellite merely to hold task receipts or duplicate an existing contract.

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

@@ -3,7 +3,7 @@ name: Features
 doc: 05_FEATURES
 owns: STATUS — feature decomposition + state; index over docs/features/
 authority: derived
-version: 1.0.0
+version: 1.1.0
 derived_from: [00_ADR, 01_PRD]
 owner: _(project owner)_
 updated_at: {{init-date}}
@@ -14,21 +14,9 @@ sync: [T4, T9]
 
 # Features
 
-> **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).
+Entry to feature decomposition, acceptance criteria and lifecycle state (constitution §6.6).
+Use the configured feature tool to create records and generate its index.
+Once generated, link that index here. Do not maintain a second status table or invent seed features.
 
-## Status legend
-
-✅ done · 🔶 partial · ⏳ planned · 💤 deferred
-
-## Feature tree
-
-| 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.
--->
+<!-- Feature records and generated index regions are tool-owned. Never raw-edit them.
+Verify lifecycle claims against current task/implementation evidence before relying on them. -->