Add templates for feature specifications, task planning, decision logging, and test matrix documentation

specs/features/_template/FEAT-XXX-name.md

@@ -0,0 +1,31 @@
+# FEAT-XXX — <short name>
+
+## Goal
+
+<1–2 sentences describing what this feature/bugfix achieves for the user>
+
+## Non-goals
+
+- <explicitly list what is out of scope>
+
+## User-visible Behavior
+
+- <what the user sees / can do>
+- <states: loading / success / error where relevant>
+
+## Edge Cases
+
+- <degraded network>
+- <cancellation / retry>
+- <invalid / partial data>
+- <other relevant risks>
+
+## Acceptance Criteria
+
+- [ ] <observable outcome 1>
+- [ ] <observable outcome 2>
+- [ ] <observable outcome 3>
+
+## Notes / Open Questions (optional)
+
+- <anything that needs human decision>

specs/guidelines/CONTEXT.md

@@ -3,7 +3,7 @@
 This document provides **orientation only**.
 It does **not** define rules, behavior, or constraints.
 
-If anything in this file conflicts with files under `specs/00_foundation/`,
+If anything in this file conflicts with files under `specs/guidelines/`,
 this file is wrong.
 
 ---
@@ -14,6 +14,7 @@ Zapstore is a Flutter-based, local-first application store built on top of
 the Nostr protocol and Bitcoin Lightning payments.
 
 It allows users to:
+
 - discover apps published via Nostr,
 - verify and install applications safely,
 - and directly support developers through zaps.
@@ -39,10 +40,12 @@ growth, or engagement metrics.
 This repository is organized into three main packages:
 
 - **zapstore**
+
   - Flutter UI and application orchestration
   - Navigation, presentation, and user interaction
 
 - **purplebase**
+
   - Local-first storage, indexing, and relay synchronization
   - Background work and isolate execution
 

specs/guidelines/INVARIANTS.md

@@ -4,33 +4,43 @@ The following guarantees are non-negotiable.
 If any invariant is violated, the implementation is incorrect.
 
 ## UI Safety
-- The UI thread must never block on network, file I/O, cryptography, or relay operations.
+
 - UI rendering must remain responsive under partial or total network failure.
+- The UI must never block on I/O, cryptography, disk access, or network/relay operations.
+- All background or asynchronous work must be cancellable and lifecycle-safe.
+- Local data must be sufficient to render meaningful UI state; network access must enhance UX, not gate it.
+- No operation may assume continuous network availability.
 
 ## Async Discipline
+
 - No polling or artificial delays (e.g., Future.delayed for timing).
 - Background work must surface results asynchronously and non-blockingly.
 - All async work must be cancellable.
 
 ## Local-First Guarantees
+
 - Cached data must be preferred over network data when available.
 - Installed apps and metadata must be accessible offline.
 - Network failures must degrade gracefully.
 
 ## Security & Verification
+
 - APKs must never be installed unless their hash matches the expected value.
 - Signed Nostr events must be verified before use.
 - NWC secrets must be stored securely and must never be logged or exposed.
 
 ## Data Robustness
+
 - Parsing unknown, missing, or future tags must not crash the app.
 - Partial or invalid data must degrade gracefully.
 
 ## Lifecycle Safety
+
 - Subscriptions must always be cancellable.
 - Isolates and background jobs must not leak resources.
 - Reconnection or retries must not duplicate events or actions.
 
 ## UX Safety
+
 - All user-visible processes must have explicit states (loading, empty, success, error).
 - Silent failures are unacceptable.

specs/guidelines/QUALITY_BAR.md

@@ -1,6 +1,7 @@
 # Zapstore — Quality Bar
 
 ## General Expectations
+
 - Correct behavior matters more than coverage numbers.
 - Happy-path-only implementations are insufficient.
 - Failures must be explicit and observable.
@@ -8,37 +9,91 @@
 ## Layer Expectations
 
 ### models
+
 - Parsing and serialization behavior must be tested.
 - Unknown or future fields must be tolerated.
 
 ### purplebase
+
 - Storage and query behavior must be testable without network access.
 - Subscription, cancellation, and isolate behavior must be validated.
 
 ### zapstore UI
+
 - UI state machines must be explicit and testable.
 - Loading, empty, error, and retry states are mandatory.
 - UI must remain usable under degraded network conditions.
 
 ## Implementation Expectations
+
 - Follow existing patterns in the nearest module.
 - Avoid introducing new architectural layers unless required by a spec.
 - Do not perform broad or stylistic refactors.
 - Prefer clarity and locality over abstraction.
+- Prefer extending or reusing existing abstractions over introducing new ones.
+- Code must be structured for human review first, not for AI generation convenience.
 
 ## Testing Expectations
+
 - Tests must validate behavior, not implementation details.
 - Failure, cancellation, and degraded-network paths must be covered.
 - Tests that only assert the happy path are insufficient.
 
 ## Anti-Patterns
+
 - Silent failures
 - Blocking the UI thread
 - Artificial delays or polling
 - Large refactors unrelated to the task
 
-## Editing Policy (Human-Owned)
-- These files are human-owned and change slowly.
-- Keep them small, focused, and easy to reason about.
-- Prefer explicit constraints over prose.
-- Create new markdown files only when unavoidable.
+## Working With AI (Human Guidelines)
+
+This project uses a spec-first workflow to collaborate safely with AI.
+
+### Documentation Discipline
+
+- Markdown files must remain small, focused, and human-readable.
+- Prefer extending or refining existing documents over creating new ones.
+- New markdown files should be introduced only when unavoidable.
+- The goal is to do more with less, not to document everything.
+
+### What Humans Own
+
+- Foundation specs under `specs/guidelines/`
+- Feature specs under `specs/features/`
+- Decisions to change behavior or architecture
+
+### What AI Owns
+
+- Execution plans under `work/**/task_plan.md`
+- Decision logs and test matrices under `work/**/`
+
+### When a Work Packet Is Required
+
+- New features
+- UX changes
+- Async, lifecycle, or background work
+- Security or verification changes
+- Any non-trivial or risky change
+
+### Spec-First Rule
+
+- Behavior changes require updating the spec first.
+- During implementation, specs are read-only.
+- If a spec is unclear or incorrect, AI must stop and report a "Spec Issue".
+
+### Task Plan Usage
+
+- Humans create the initial task_plan with a rough checklist.
+- AI refines the plan, executes tasks, and marks progress.
+- Every code change must map to an item in the task_plan.
+
+### Task Completeness
+
+For non-trivial work, changes are not considered complete unless:
+
+- task_plan.md reflects the actual work performed
+- test_matrix.md demonstrates behavioral coverage
+- no significant code exists outside the task plan
+
+This workflow exists to prevent AI drift, accidental refactors, and UX regressions.

work/_template/decisions.md

@@ -0,0 +1,33 @@
+# Decisions
+
+This file records **non-obvious decisions** made during implementation.
+
+Only write here when:
+
+- a tradeoff was made
+- multiple options existed
+- a decision affects future work
+
+Do not log:
+
+- routine steps
+- mechanical changes
+- obvious refactors
+
+---
+
+## Decision Log
+
+### YYYY-MM-DD — Short title
+
+**Context**  
+Brief description of the situation.
+
+**Decision**  
+What was chosen.
+
+**Rationale**  
+Why this option was selected.
+
+**Consequences**  
+Expected impact or follow-up considerations.

work/_template/task_plan.md

@@ -0,0 +1,27 @@
+# Task Plan — FEAT-XXX <short name>
+
+This file is the working memory for this change.
+
+Rules:
+
+- Every code change must map to a task below.
+- Tasks must be checked when completed.
+- If the spec is unclear or incorrect, stop and report a Spec Issue.
+
+## Goal
+
+<One sentence: what this task accomplishes>
+
+## Constraints
+
+- Follow the feature spec
+- Do not modify foundation specs
+- Respect invariants and quality bar
+
+## Tasks
+
+- [ ] Understand current behavior
+- [ ] Implement required changes
+- [ ] Handle failure and edge cases
+- [ ] Update tests
+- [ ] Validate against test matrix

work/_template/test_matrix.md

@@ -0,0 +1,35 @@
+# Test Matrix
+
+This file describes **how behavior is validated** for this change.
+
+Focus on:
+
+- observable behavior
+- edge cases
+- failure modes
+
+Do not list:
+
+- trivial happy paths only
+- tests that merely mirror the implementation
+
+---
+
+## Scope
+
+Briefly describe what behavior this change introduces or modifies.
+
+---
+
+## Behavioral Coverage
+
+| Scenario | Expected Behavior | Test Type | Location |
+| -------- | ----------------- | --------- | -------- |
+|          |                   |           |          |
+
+---
+
+## Notes
+
+- Prefer fewer, high-signal tests over broad but shallow coverage.
+- If a scenario is intentionally untested, state why.