diff --git a/specs/features/_template/FEAT-XXX-name.md b/specs/features/_template/FEAT-XXX-name.md new file mode 100644 index 0000000..b23432d --- /dev/null +++ b/specs/features/_template/FEAT-XXX-name.md @@ -0,0 +1,31 @@ +# FEAT-XXX — + +## Goal + +<1–2 sentences describing what this feature/bugfix achieves for the user> + +## Non-goals + +- + +## User-visible Behavior + +- +- + +## Edge Cases + +- +- +- +- + +## Acceptance Criteria + +- [ ] +- [ ] +- [ ] + +## Notes / Open Questions (optional) + +- diff --git a/specs/guidelines/CONTEXT.md b/specs/guidelines/CONTEXT.md index a9b941a..72414eb 100644 --- a/specs/guidelines/CONTEXT.md +++ b/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 diff --git a/specs/guidelines/INVARIANTS.md b/specs/guidelines/INVARIANTS.md index f467a40..599305d 100644 --- a/specs/guidelines/INVARIANTS.md +++ b/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. diff --git a/specs/guidelines/QUALITY_BAR.md b/specs/guidelines/QUALITY_BAR.md index 546b7b9..ca05269 100644 --- a/specs/guidelines/QUALITY_BAR.md +++ b/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. diff --git a/work/_template/decisions.md b/work/_template/decisions.md new file mode 100644 index 0000000..a0b5e1b --- /dev/null +++ b/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. diff --git a/work/_template/task_plan.md b/work/_template/task_plan.md new file mode 100644 index 0000000..e52d351 --- /dev/null +++ b/work/_template/task_plan.md @@ -0,0 +1,27 @@ +# Task Plan — FEAT-XXX + +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 + + + +## 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 diff --git a/work/_template/test_matrix.md b/work/_template/test_matrix.md new file mode 100644 index 0000000..022c273 --- /dev/null +++ b/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.