safeword 0.2.4 → 0.2.5

package/.safeword/planning/user-stories/001-guides-review-user-stories.md

@@ -1,1381 +0,0 @@
-# Guides Review → User Story Extraction Plan
-
-This document defines how we will extract user stories from each guide in `framework/guides/` and serves as the single place to collect them.
-
-## Method
-
-- Treat a “concept” as any method, pattern, workflow, anti-pattern, or decision rule that implies user behavior or developer workflow.
-- For each concept, write at least one user story and acceptance criteria.
-- Prefer concise, testable stories. Consolidate duplicates across guides.
-
-### User Story Template
-
-As a [role], I want [capability], so that [outcome].
-
-Acceptance Criteria:
-
-- [ ] Condition(s) that trigger behavior
-- [ ] Observable result(s) and error states
-- [ ] Success/Done definition
-
-## Per-Guide Checklist
-
-- [x] architecture-guide.md — extracted
-- [x] code-philosophy.md — extracted
-- [x] context-files-guide.md — extracted
-- [x] data-architecture-guide.md — extracted
-- [x] design-doc-guide.md — extracted
-- [x] learning-extraction.md — extracted
-- [x] llm-instruction-design.md — extracted
-- [x] llm-prompting.md — extracted
-- [x] tdd-best-practices.md — extracted (renamed from tdd-templates.md)
-- [x] test-definitions-guide.md — extracted
-- [x] testing-methodology.md — extracted
-- [x] user-story-guide.md — extracted
-- [x] zombie-process-cleanup.md — extracted
-
-## Extracted User Stories (to be populated)
-
-### architecture-guide.md
-
-1. Single Comprehensive Architecture Doc
-   As a project maintainer, I want one comprehensive architecture document per project/package, so that architecture context isn’t fragmented.
-   Acceptance Criteria:
-
-- [ ] `ARCHITECTURE.md` exists at project/package root
-- [ ] Required sections present (header, TOC, overview, data principles, model, components, flows, decisions, best practices, migration)
-- [ ] Updated in place with version and status
-
-2. Design Docs for Features
-   As a feature developer, I want concise design docs referencing the architecture doc, so that feature scope and approach are clear.
-   Acceptance Criteria:
-
-- [ ] Location under `planning/design/` (or `docs/design/`)
-- [ ] ~2–3 pages with user flow, component interactions, test mapping
-- [ ] References architecture doc for broader decisions
-
-3. Quick Doc-Type Decision
-   As a developer, I want a quick matrix to decide architecture vs design doc, so that I pick the right doc type.
-   Acceptance Criteria:
-
-- [ ] Tech choices/data model → architecture doc
-- [ ] New feature implementation → design doc
-- [ ] Trade-offs can appear in both (brief in design doc)
-
-4. Document Why, Not Just What
-   As a maintainer, I want decisions to include What/Why/Trade-offs/Alternatives, so that rationale is explicit.
-   Acceptance Criteria:
-
-- [ ] Every key decision includes rationale and trade-offs
-- [ ] Alternatives considered, with reasons for rejection
-- [ ] Links to relevant code or prior decisions
-
-5. Code References in Docs
-   As a doc author, I want to reference real code paths (with line ranges when helpful), so that readers can verify implementations.
-   Acceptance Criteria:
-
-- [ ] Paths use `[module]/[file].[ext]:[start]-[end]` pattern when applicable
-- [ ] Examples point to current code, not stale references
-- [ ] References updated when code moves
-
-6. Versioning and Status
-   As a maintainer, I want current vs proposed sections with version and status, so that readers know what’s live now.
-   Acceptance Criteria:
-
-- [ ] Header includes Version and Status
-- [ ] Sections separate current schema vs proposed
-- [ ] Proposed items marked clearly
-
-7. TDD Workflow Integration
-   As a developer, I want a docs-first, tests-first workflow, so that implementation follows clear definitions.
-   Acceptance Criteria:
-
-- [ ] Order: User Stories → Test Definitions → Design Doc → Check Architecture → Implement → Update Architecture if needed
-- [ ] Architecture doc reviewed before coding
-- [ ] Updates recorded after new patterns emerge
-
-8. Triggers to Update Architecture Doc
-   As a developer, I want clear triggers for architecture updates, so that docs stay accurate.
-   Acceptance Criteria:
-
-- [ ] Update when: new data model concepts, tech choices, new patterns/conventions, architectural insights
-- [ ] Don’t update for: single feature implementation, bug fixes, refactors without architectural impact
-
-9. Avoid Common Mistakes
-   As a doc reviewer, I want checks that prevent doc anti-patterns, so that documentation stays useful.
-   Acceptance Criteria:
-
-- [ ] No ADR sprawl; keep one comprehensive architecture doc
-- [ ] Decisions always include rationale and status
-- [ ] Design docs avoid duplicating architecture content
-
-10. Standard File Organization
-    As an architect, I want a clear directory layout, so that docs are easy to find and maintain.
-    Acceptance Criteria:
-
-- [ ] `ARCHITECTURE.md` at root; feature design docs under planning/design
-- [ ] User stories and test definitions kept in planning subfolders
-- [ ] Multiple architecture docs only for major subsystems (clearly scoped)
-
-11. Data Architecture Guidance
-    As a data architect, I want a linked data architecture guide, so that data-heavy projects document models, flows, and policies properly.
-    Acceptance Criteria:
-
-- [ ] Data architecture doc created when applicable
-- [ ] Principles, models (conceptual/logical/physical), flows, and policies documented
-- [ ] Integrated with TDD workflow and versioning
-
-### code-philosophy.md
-
-1. Response JSON Summary
-   As a developer using the agent, I want every response to end with a standard JSON summary, so that automations can reliably parse outcomes.
-   Acceptance Criteria:
-
-- [ ] Summary includes keys: `proposedChanges`, `madeChanges`, `askedQuestion`
-- [ ] Boolean values reflect the actual actions taken
-- [ ] Missing or malformed summaries are flagged during review
-
-2. Avoid Bloat, Prefer Elegant Code
-   As a maintainer, I want simple, focused solutions, so that the codebase remains easy to read and change.
-   Acceptance Criteria:
-
-- [ ] PRs that add features include justification of necessity
-- [ ] Redundant or speculative code is removed before merge
-- [ ] Readability is prioritized over cleverness
-
-3. Self-Documenting Code
-   As a reviewer, I want clear naming and structure with minimal comments, so that intent is obvious without verbose annotations.
-   Acceptance Criteria:
-
-- [ ] Names convey purpose without abbreviations
-- [ ] Comments explain non-obvious decisions only
-- [ ] Functions stay small with clear responsibilities
-
-4. Explicit Error Handling
-   As a developer, I want explicit error handling, so that failures are visible and traceable.
-   Acceptance Criteria:
-
-- [ ] No swallowed errors; failures are surfaced
-- [ ] Error messages include action context
-- [ ] Control flow avoids blanket try/catch without handling
-
-5. Documentation Verification
-   As a developer, I want to verify current docs and versions before coding, so that I don’t rely on outdated APIs.
-   Acceptance Criteria:
-
-- [ ] Library versions are checked before implementation
-- [ ] Feature assumptions are validated against docs
-- [ ] Version-specific caveats are noted in PR/commit
-
-6. TDD Workflow
-   As a developer, I want tests written first (RED → GREEN → REFACTOR), so that behavior is defined and changes are safe.
-   Acceptance Criteria:
-
-- [ ] A failing test exists before feature implementation
-- [ ] Only minimal code is added to pass the test
-- [ ] Refactors keep tests green
-
-7. Self-Testing Before Completion
-   As a developer, I want to run tests myself before declaring completion, so that users aren’t asked to verify my work.
-   Acceptance Criteria:
-
-- [ ] Relevant tests run and pass locally
-- [ ] Evidence of test run included in work notes/PR
-- [ ] No request for user verification of correctness
-
-8. Debug Logging Hygiene
-   As a developer, I want to log actual vs expected while debugging and remove logs after, so that code stays clean.
-   Acceptance Criteria:
-
-- [ ] Debug logs show inputs and expected/actual deltas
-- [ ] Temporary logs removed before merge
-- [ ] Complex objects serialized meaningfully when needed
-
-9. Cross-Platform Paths
-   As a developer, I want path handling that supports `/` and `\`, so that the code works on macOS, Windows, and Linux.
-   Acceptance Criteria:
-
-- [ ] Join/resolve functions used instead of string concat
-- [ ] Tests or manual checks on at least two platforms/CI
-- [ ] No hard-coded separators
-
-10. Best Practices Research
-    As a developer, I want to consult tool, domain, and UX best practices, so that implementations align with conventions.
-    Acceptance Criteria:
-
-- [ ] PR/notes link to relevant best-practice references
-- [ ] Design decisions mention tradeoffs briefly
-- [ ] Anti-patterns avoided when documented
-
-11. Self-Review Gate
-    As a developer, I want a pre-merge self-review, so that obvious issues are caught early.
-    Acceptance Criteria:
-
-- [ ] Checklist: correctness, elegance, best practices, docs/version, tests
-- [ ] Blockers addressed or explicitly deferred with rationale
-- [ ] Final pass confirms user-facing functionality
-
-12. Question-Asking Protocol
-    As a developer, I want to ask questions only after due diligence, so that I respect the user’s time.
-    Acceptance Criteria:
-
-- [ ] Attempts include docs/code/test exploration
-- [ ] Questions focus on domain preferences or unknowns
-- [ ] Summary of attempted paths provided
-
-13. Tooling Currency
-    As a devops-minded contributor, I want critical CLIs updated, so that workflows remain reliable and secure.
-    Acceptance Criteria:
-
-- [ ] Update cadence or check noted in docs/automation
-- [ ] Breaking changes reviewed before rollout
-- [ ] Version pinning strategy documented if needed
-
-14. Git Workflow
-    As a developer, I want frequent, descriptive commits, so that progress can be checkpointed and reviewed easily.
-    Acceptance Criteria:
-
-- [ ] Small, atomic commits with clear messages
-- [ ] Commit after each meaningful change/test pass
-- [ ] Avoid “misc” or ambiguous messages
-
-### context-files-guide.md
-
-1.  Choose the Right Context File(s)
-    As a maintainer, I want to create the context file(s) matching our tools, so that agents load the right guidance.
-    Acceptance Criteria:
-
-- [ ] Use `CLAUDE.md` for Claude-specific guidance
-- [ ] Use `CURSOR.md` for Cursor-specific guidance
-- [ ] Use `AGENTS.md` for tool-agnostic project context
-- [ ] Subdirectory files created only when >3 unique rules or specialized context is needed
-
-2.  SAFEWORD Trigger Required
-    As a doc author, I want every project-level context file to start with a SAFEWORD trigger, so that global patterns are always loaded.
-    Acceptance Criteria:
-
-- [ ] Top of file includes “ALWAYS READ FIRST: @./.safeword/SAFEWORD.md”
-- [ ] Brief rationale explains why SAFEWORD is referenced
-- [ ] Applies to `CLAUDE.md`, `CURSOR.md`, and `AGENTS.md`
-
-3.  Respect Auto-Loading Behavior
-    As a contributor, I want root + subdirectory context to load predictably, so that guidance is layered without duplication.
-    Acceptance Criteria:
-
-- [ ] Subdirectory files assume root is loaded and use cross-references
-- [ ] No duplication of root content in subdirectory files
-- [ ] Reliability note: explicitly reference the file in conversations when needed
-
-4.  Modular File Structure
-    As a maintainer, I want a modular context structure with imports, so that files stay concise and scannable.
-    Acceptance Criteria:
-
-- [ ] Root context imports `docs/architecture.md` and `docs/conventions.md` (or equivalents)
-- [ ] Imports use `@docs/...` or `@.safeword/...` patterns
-- [ ] Recursive imports limited to depth ≤5; code spans/blocks don’t resolve imports
-
-5.  Content Inclusion/Exclusion Rules
-    As a doc reviewer, I want clear guidelines on what belongs in context files, so that they stay high-signal.
-    Acceptance Criteria:
-
-- [ ] Include why-over-what, project-specific conventions, domain requirements, examples, gotchas, cross-refs
-- [ ] Exclude setup/API docs, generic advice, feature lists, test commands (move to README/tests/other docs)
-- [ ] No implementation details (paths/line numbers) in root; put specifics in subdirectory files
-
-6.  Size Targets and Modularity
-    As a maintainer, I want size targets for context files, so that token usage stays efficient.
-    Acceptance Criteria:
-
-- [ ] Root 100–200 lines; subdirectories 60–100; total <500 across project
-- [ ] If >200 lines, extract to subdirectory or use imports
-- [ ] Keep under ~50KB and modularize as needed
-
-7.  Cross-Reference Pattern
-    As a doc author, I want a standard cross-reference pattern, so that readers can jump between root and subdirectories.
-    Acceptance Criteria:
-
-- [ ] Root uses “Agents (path) – See /AGENTS.md” style
-- [ ] Subdirectory files reference root SAFEWORD/AGENTS for architecture
-- [ ] Import examples show architecture, coding standards, and git workflow sections
-
-8.  Maintenance Rules
-    As a team, I want explicit maintenance rules, so that context stays current and lean.
-    Acceptance Criteria:
-
-- [ ] Update on architecture changes; remove outdated sections immediately
-- [ ] Consolidate overlapping content across files
-- [ ] Verify hierarchical loading matches intent
-
-9.  Domain Requirements Section (Optional)
-    As a product/domain lead, I want domain requirements captured when needed, so that the AI respects specialized rules.
-    Acceptance Criteria:
-
-- [ ] Add only for non-obvious domain knowledge
-- [ ] Use clear structure (domains → principles with rationale)
-- [ ] Provide concrete, testable guidance and resources
-
-10. LLM Comprehension Checklist
-    As an author, I want a pre-commit checklist for LLM readability, so that instructions are reliable.
-    Acceptance Criteria:
-
-- [ ] MECE decision logic; terms defined; no contradictions
-- [ ] Examples for rules and explicit edge cases
-- [ ] No redundancy; under 200 lines or uses imports
-
-11. Conciseness, Effectiveness, Token Budget
-    As a maintainer, I want concise, effective context that respects token budgets, so that prompts remain efficient.
-    Acceptance Criteria:
-
-- [ ] Short, declarative bullets; remove commentary/redundancy
-- [ ] Treat as living docs; add emphasis for critical rules
-- [ ] Keep files small; modularize via imports
-
-### data-architecture-guide.md
-
-1.  Decide Where to Document
-    As an architect, I want a clear decision tree for data documentation, so that data changes land in the right doc.
-    Acceptance Criteria:
-
-- [ ] Follow ordered decisions (project init → new store → model change → flow integration → single feature)
-- [ ] Edge cases handled (schema change always in architecture doc; 3+ entities → architecture)
-- [ ] Design doc used when only feature uses existing model
-
-2.  Define Data Principles First
-    As a maintainer, I want core data principles documented first, so that models and flows follow a stable foundation.
-    Acceptance Criteria:
-
-- [ ] Data Quality, Governance, Accessibility, Living Documentation defined with What/Why/Document/Example
-- [ ] Validation checkpoints include file paths/line refs where applicable
-- [ ] Source of truth identified for each entity
-
-3.  Model at Three Levels
-    As a designer, I want conceptual, logical, and physical models, so that readers see the system from high-level to storage details.
-    Acceptance Criteria:
-
-- [ ] Conceptual: entities with descriptions
-- [ ] Logical: attributes, types, relationships, constraints
-- [ ] Physical: storage tech, indexes, and rationale/trade-offs
-
-4.  Document Data Flows
-    As a developer, I want sources → transformations → destinations with error handling, so that flows are predictable and testable.
-    Acceptance Criteria:
-
-- [ ] Each step includes validation, business logic, persistence, UI updates
-- [ ] Error handling covered for each step (not just happy path)
-- [ ] External integrations called out when applicable
-
-5.  Specify Data Policies
-    As a security-conscious maintainer, I want access, validation, and lifecycle policies, so that data is protected and consistent.
-    Acceptance Criteria:
-
-- [ ] Read/write/delete roles and mechanisms defined
-- [ ] Lifecycle rules (create/update/delete/purge) documented
-- [ ] Conflict resolution strategy selected and justified
-
-6.  TDD Integration Triggers
-    As a developer, I want data-specific triggers for updating architecture docs, so that documentation stays current.
-    Acceptance Criteria:
-
-- [ ] Update on new entities, schema changes, storage tech changes, perf bottlenecks
-- [ ] Cross-reference from `ARCHITECTURE.md` or `SAFEWORD.md`
-- [ ] Version/status and migration strategy updated
-
-7.  Avoid Common Mistakes
-    As a reviewer, I want checks that prevent data doc anti-patterns, so that docs remain trustworthy.
-    Acceptance Criteria:
-
-- [ ] Source of truth defined; validation rules present
-- [ ] Migration strategy included for breaking changes
-- [ ] Performance targets concrete; implementation details kept out of architecture doc
-
-8.  Best Practices Checklist Compliance
-    As a maintainer, I want a pre-merge checklist, so that data docs meet quality standards.
-    Acceptance Criteria:
-
-- [ ] Four+ principles documented; entities and models complete
-- [ ] Flows include error handling; validation checkpoints have line numbers
-- [ ] Version/status aligned with code; cross-references exist
-
-### design-doc-guide.md
-
-1.  Verify Prerequisites
-    As a developer, I want to confirm user stories and test definitions before writing a design doc, so that the design aligns with validated behavior.
-    Acceptance Criteria:
-
-- [ ] User stories exist and are linked
-- [ ] Test definitions exist and are linked
-- [ ] Design doc references both; no duplication
-
-2.  Use Standard Template
-    As a contributor, I want to use the standard design doc template, so that docs are consistent and complete.
-    Acceptance Criteria:
-
-- [ ] Structure follows `templates/design-doc-template.md`
-- [ ] All required sections are present or marked "(if applicable)"
-- [ ] Saved under `planning/design/[feature]-design.md`
-
-3.  Architecture Section
-    As a designer, I want a concise architecture section, so that the high-level approach is clear.
-    Acceptance Criteria:
-
-- [ ] 1–2 paragraphs describing overall approach and fit
-- [ ] Optional diagram if helpful
-- [ ] References architecture doc where relevant
-
-4.  Components with [N]/[N+1] Pattern
-    As a developer, I want concrete component examples with interfaces and tests, so that patterns are repeatable.
-    Acceptance Criteria:
-
-- [ ] Define Component [N] (name, responsibility, interface, dependencies, tests)
-- [ ] Define Component [N+1] (different example showing variation)
-- [ ] Add additional components as needed
-
-5.  Data Model (If Applicable)
-    As a developer, I want the design doc to describe the data model when relevant, so that types and flows are explicit.
-    Acceptance Criteria:
-
-- [ ] State shape or schema outlined
-- [ ] Relationships and flows between types shown
-- [ ] Interaction with components clear
-
-6.  Component Interaction (If Applicable)
-    As a developer, I want to document component communication, so that integration is predictable.
-    Acceptance Criteria:
-
-- [ ] Events/method calls documented
-- [ ] Data flow between components shown (N → N+1)
-- [ ] Edge cases in interactions noted
-
-7.  User Flow
-    As a product-focused developer, I want a step-by-step user flow, so that UX is concrete and testable.
-    Acceptance Criteria:
-
-- [ ] Concrete steps (e.g., keyboard shortcuts, buttons)
-- [ ] Aligns with user stories
-- [ ] Maps to test definitions
-
-8.  Key Decisions with Trade-offs
-    As a maintainer, I want key decisions documented with rationale and trade-offs, so that choices are explicit.
-    Acceptance Criteria:
-
-- [ ] Each decision includes what, why (with specifics), and trade-off
-- [ ] Multiple decisions show [N]/[N+1] pattern
-- [ ] Links to benchmarks/analysis where relevant
-
-9.  Implementation Notes (If Applicable)
-    As an engineer, I want constraints, error handling, and gotchas documented, so that implementation risks are known.
-    Acceptance Criteria:
-
-- [ ] Constraints, error handling approach, and gotchas listed
-- [ ] Open questions enumerated
-- [ ] References to ADRs/POCs included if applicable
-
-10. Quality Checklist
-    As a reviewer, I want a design doc quality checklist, so that docs are concise and LLM-optimized.
-    Acceptance Criteria:
-
-- [ ] References user stories and tests, does not duplicate them
-- [ ] Has Component [N] and [N+1] examples
-- [ ] ~121 lines target, clear and concise
-
-### learning-extraction.md
-
-1. Trigger-Based Extraction
-   As a developer, I want clear triggers to extract learnings, so that reusable knowledge is captured when it matters.
-   Acceptance Criteria:
-
-- [ ] Observable complexity, trial-and-error, undocumented gotcha, integration struggle, testing trap, or architectural insight triggers extraction
-- [ ] Forward-looking filter applied (“will this save future time?”)
-- [ ] Extraction deferred until fix confirmed (no mid-debug extraction)
-
-2. Check Existing Learnings First
-   As a contributor, I want to check for existing learnings before creating new ones, so that we prevent duplication.
-   Acceptance Criteria:
-
-- [ ] Proactive search by keyword in project and global learnings
-- [ ] Update existing learning when similar concept exists
-- [ ] Reference existing vs new with explicit difference when partially overlapping
-
-3. Place Learnings in Correct Location
-   As a maintainer, I want consistent locations for learnings, so that the knowledge base stays organized.
-   Acceptance Criteria:
-
-- [ ] Global patterns → `.safeword/learnings/`
-- [ ] Project-specific patterns → `./.safeword/learnings/`
-- [ ] One-off narratives → `./.safeword/learnings/archive/`
-
-4. Respect Instruction Precedence
-   As an agent, I want to follow cascading precedence, so that project-specific guidance overrides global defaults.
-   Acceptance Criteria:
-
-- [ ] Order applied: explicit user > project learnings > global learnings > SAFEWORD.md
-- [ ] Conflicts resolved in favor of higher precedence
-
-5. Use Templates
-   As a doc author, I want standard templates for learnings and narratives, so that documents are consistent and actionable.
-   Acceptance Criteria:
-
-- [ ] Forward-looking learning includes Principle, Gotcha, Good/Bad, Why, Examples, Testing Trap, Reference
-- [ ] Narrative includes Problem, Investigation, Solution (diff), Lesson
-- [ ] Examples are concrete and up to date
-
-6. SAFEWORD.md Cross-Reference
-   As a maintainer, I want to cross-reference new learnings in SAFEWORD.md, so that discoverability stays high.
-   Acceptance Criteria:
-
-- [ ] Add short entry under Common Gotchas or Architecture as appropriate
-- [ ] Include bold name + one-liner + link
-- [ ] Update references when files move or split
-
-7. Suggest Extraction at the Right Time
-   As an assistant, I want to suggest learnings at appropriate confidence levels, so that we don’t create noise.
-   Acceptance Criteria:
-
-- [ ] High confidence: suggest during debugging for complex/stuck patterns
-- [ ] Medium confidence: ask after completion
-- [ ] Low confidence: don’t suggest for trivial or well-documented cases
-
-8. Review and Maintenance Cycle
-   As a maintainer, I want periodic review of learnings, so that guidance stays relevant.
-   Acceptance Criteria:
-
-- [ ] Monthly relevance review; quarterly archive obsolete items
-- [ ] Split learnings >200 lines or covering multiple concepts
-- [ ] Consolidate overlapping learnings
-
-9. Feedback Loop
-   As a team, I want to tune suggestion thresholds, so that learnings reflect real value.
-   Acceptance Criteria:
-
-- [ ] Track acceptance rate of suggestions
-- [ ] If acceptance <30%, raise suggestion threshold
-- [ ] Monitor references of learnings in future work
-
-10. Workflow Integration
-    As a developer, I want a clear extraction workflow during and after development, so that documentation fits naturally into delivery.
-    Acceptance Criteria:
-
-- [ ] During dev: recognize trigger → assess scope → choose location → extract → cross-ref
-- [ ] After feature: review → extract if threshold met → update cross-refs → commit with learning
-- [ ] Commit messages include learning references when applicable
-
-11. Anti-Patterns to Avoid
-    As a reviewer, I want to block low-value extractions, so that the knowledge base stays high-signal.
-    Acceptance Criteria:
-
-- [ ] No trivial, one-liners, opinions without rationale, or steps without a lesson
-- [ ] Don’t duplicate official docs
-- [ ] Remove stale learning references after archiving/replacement
-
-12. Directory & Size Standards
-    As a doc author, I want directory and size guidelines, so that files are easy to navigate and maintain.
-    Acceptance Criteria:
-
-- [ ] Follow standard directory structure for global/project/archive
-- [ ] Forward-looking: 50–150 lines; Narratives: 30–100 lines
-- [ ] Split oversized files into focused concepts
-
-### llm-instruction-design.md
-
-1. MECE Decision Trees
-   As a documentation author, I want decision trees that are mutually exclusive and collectively exhaustive, so that LLMs follow unambiguous paths.
-   Acceptance Criteria:
-
-- [ ] Branches do not overlap; first-match stops evaluation
-- [ ] All relevant cases covered; none fall through
-- [ ] Example tree included
-
-2. Explicit Definitions
-   As a documentation author, I want all terms defined explicitly, so that LLMs don’t assume meanings.
-   Acceptance Criteria:
-
-- [ ] Ambiguous terms replaced with precise definitions
-- [ ] Examples clarify common misunderstandings
-- [ ] “Lowest level” and similar phrases rewritten to be actionable
-
-3. No Contradictions
-   As a maintainer, I want consistent guidance across sections, so that LLMs don’t receive conflicting rules.
-   Acceptance Criteria:
-
-- [ ] Cross-check updates for conflicting statements
-- [ ] Overlapping guidance reconciled into single rule
-- [ ] Example of corrected contradiction included
-
-4. Concrete Examples (Good vs Bad)
-   As a documentation author, I want 2–3 concrete examples per rule, so that LLMs learn patterns.
-   Acceptance Criteria:
-
-- [ ] Each rule includes at least one BAD and one GOOD example
-- [ ] Examples are brief and domain-relevant
-- [ ] Examples updated when guidance changes
-
-5. Edge Cases Explicit
-   As a writer, I want edge cases listed under each rule, so that LLMs handle tricky scenarios.
-   Acceptance Criteria:
-
-- [ ] Edge cases listed and addressed
-- [ ] Non-deterministic and environment-bound cases covered
-- [ ] Clear routing of mixed concerns
-
-6. Actionable, Not Vague
-   As a reader, I want actionable rules with optimization guidance, so that outcomes are consistent.
-   Acceptance Criteria:
-
-- [ ] Subjective terms replaced by concrete rules and red flags
-- [ ] Rules describe what to do, not opinions
-- [ ] Checklist item ensures actionability
-
-7. Sequential Decision Trees
-   As a maintainer, I want ordered questions, so that LLMs stop at the first match.
-   Acceptance Criteria:
-
-- [ ] Questions presented in strict order
-- [ ] “Stop at first match” called out
-- [ ] Parallel structures removed
-
-8. Tie-Breaking Rules
-   As a user, I want tie-breakers documented, so that ambiguous choices resolve deterministically.
-   Acceptance Criteria:
-
-- [ ] Global tie-breaker declared (e.g., choose fastest test)
-- [ ] References embedded in each decision tree
-- [ ] Conflicts refer to the same tie-breaker
-
-9. Lookup Tables for Complex Logic
-   As an author, I want simple tables for 3+ branch decisions, so that LLMs can map inputs to outputs cleanly.
-   Acceptance Criteria:
-
-- [ ] Table includes clear cases without caveats in cells
-- [ ] Complex logic extracted into a table
-- [ ] Example table provided
-
-10. No Caveats in Tables
-    As an author, I want caveats expressed as separate rows, so that tables remain pattern-friendly.
-    Acceptance Criteria:
-
-- [ ] Parentheticals removed from cells
-- [ ] Caveats represented by additional rows
-- [ ] Table remains simple to parse
-
-11. Percentages with Context
-    As an author, I want percentage guidance accompanied by adjustments, so that LLMs adapt sensibly.
-    Acceptance Criteria:
-
-- [ ] Baseline + context-specific adjustments or principles-only alternative
-- [ ] Avoid standalone percentages without rules
-- [ ] Examples show adjustments
-
-12. Specific Questions
-    As a writer, I want precise questions, so that LLMs choose correct tools.
-    Acceptance Criteria:
-
-- [ ] Use tool-specific wording (e.g., real browser vs jsdom)
-- [ ] Clarify commonly confused tools
-- [ ] Examples included
-
-13. Re-evaluation Paths
-    As a user, I want next steps when rules don’t fit, so that I can decompose the problem.
-    Acceptance Criteria:
-
-- [ ] 3-step fallback path documented with example
-- [ ] Encourages decomposition (pure vs I/O vs UI)
-- [ ] Concrete example (e.g., login validation)
-
-14. Anti-Patterns Guard
-    As a reviewer, I want to block common anti-patterns, so that docs stay reliable.
-    Acceptance Criteria:
-
-- [ ] No visual metaphors, undefined jargon, outdated references
-- [ ] Single decision framework per topic (no competition)
-- [ ] Update all mentions when concepts are removed
-
-15. Quality Checklist Compliance
-    As a maintainer, I want a pre-commit checklist for LLM docs, so that guidance is consistent.
-    Acceptance Criteria:
-
-- [ ] MECE, explicit definitions, no contradictions
-- [ ] Examples, edge cases, tie-breakers, lookup tables as needed
-- [ ] Re-evaluation path present
-
-### llm-prompting.md
-
-1. Concrete Examples in Prompts
-   As a prompt author, I want GOOD vs BAD code examples, so that guidance is concrete and learnable.
-   Acceptance Criteria:
-
-- [ ] Each rule has at least one BAD and one GOOD example
-- [ ] Examples are short and domain-relevant
-- [ ] Examples updated as patterns evolve
-
-2. Structured Outputs via JSON
-   As an engineer, I want LLM responses to follow JSON schemas, so that outputs are predictable and easily validated.
-   Acceptance Criteria:
-
-- [ ] Prompts request JSON output with explicit schema
-- [ ] Responses validated against schema
-- [ ] Free-form prose avoided for machine consumption
-
-3. Prompt Caching for Cost Reduction
-   As an agent developer, I want static rules cached with cache_control: ephemeral, so that repeated calls are cheaper.
-   Acceptance Criteria:
-
-- [ ] Static content in system prompt marked cacheable (ephemeral)
-- [ ] Dynamic state placed in user messages (non-cached)
-- [ ] Cache hit behavior verified; changes to cached blocks minimized
-
-4. Message Architecture (Static vs Dynamic)
-   As an implementer, I want clean separation of static rules and dynamic inputs, so that caching and clarity improve.
-   Acceptance Criteria:
-
-- [ ] No dynamic state interpolated into cached system prompts
-- [ ] User messages contain dynamic state and inputs
-- [ ] Example snippet provided showing separation
-
-5. Cache Invalidation Discipline
-   As a maintainer, I want to change cached blocks sparingly, so that we avoid widespread cache invalidation.
-   Acceptance Criteria:
-
-- [ ] Acknowledge “any change breaks all caches”
-- [ ] Batch edits to cached sections
-- [ ] Document rebuild cost when caches invalidate
-
-6. LLM-as-Judge Evaluations
-   As a tester, I want rubric-driven LLM evaluations, so that nuanced qualities can be tested reliably.
-   Acceptance Criteria:
-
-- [ ] Rubrics define EXCELLENT/ACCEPTABLE/POOR with criteria
-- [ ] Avoid brittle keyword checks for creative outputs
-- [ ] Evaluations integrated into test suite where applicable
-
-7. Evaluation Framework Mapping
-   As a test planner, I want clear guidance on Unit, Integration, and LLM Evals, so that we test at the right layer.
-   Acceptance Criteria:
-
-- [ ] Unit: pure functions; Integration: agent + LLM calls; LLM Evals: judgment quality
-- [ ] Real browser required only for E2E scenarios
-- [ ] Examples for mapping common cases
-
-8. Cost Awareness for Evals
-   As a maintainer, I want evals sized and cached thoughtfully, so that costs stay predictable.
-   Acceptance Criteria:
-
-- [ ] Note typical scenario counts and approximate costs with caching
-- [ ] Use caching for static rubrics and examples
-- [ ] Document budget expectations in CI
-
-9. “Why” Over “What” in Prompts
-   As a prompt author, I want rationales with numbers, so that trade-offs are explicit.
-   Acceptance Criteria:
-
-- [ ] Prompts include brief rationale for critical rules
-- [ ] Where possible, include metrics or concrete targets
-- [ ] Trade-offs and gotchas stated explicitly
-
-10. Precise Technical Terms
-    As a writer, I want specific terms (e.g., real browser vs jsdom), so that tool selection is correct.
-    Acceptance Criteria:
-
-- [ ] Prompts ask “Does this require a real browser (Playwright/Cypress)?”
-- [ ] Clarify React Testing Library is not a real browser
-- [ ] Common confusions documented
-
-### tdd-best-practices.md (formerly tdd-templates.md)
-
-1. Select Correct Template
-   As a planner, I want to select the right template (user stories, test definitions, design doc, architecture), so that documentation aligns with TDD workflow.
-   Acceptance Criteria:
-
-- [ ] Feature/issues → user stories template
-- [ ] Feature test suites → test definitions template
-- [ ] Feature implementation → design doc template
-- [ ] Project-wide decisions → architecture doc (no template)
-- [ ] Example prompts guide correct selection
-
-2. Choose Story Format
-   As a writer, I want to choose the appropriate story format (standard, Given-When-Then, job story), so that intent is clear.
-   Acceptance Criteria:
-
-- [ ] Standard format (As a / I want / So that) used by default
-- [ ] Given-When-Then for behavior-focused stories
-- [ ] Job story for outcome-focused cases
-- [ ] Each format includes example
-
-3. Write Quality Acceptance Criteria
-   As a product owner, I want specific, testable AC with out-of-scope sections, so that delivery is measurable.
-   Acceptance Criteria:
-
-- [ ] AC specify measurable behavior (e.g., "<200ms", "within 5 clicks")
-- [ ] Out-of-scope listed to prevent scope creep
-- [ ] Good examples demonstrate testable conditions
-- [ ] Bad examples show what to avoid
-
-4. Block Story Anti-Patterns
-   As a reviewer, I want to reject vague, technical-task, or bundled stories, so that stories remain valuable.
-   Acceptance Criteria:
-
-- [ ] Vague value or missing AC is blocked (example provided)
-- [ ] Technical-only stories redirected to task/spike
-- [ ] Bundled features (3+) split into multiple stories
-- [ ] Missing "So that" flagged
-
-5. Use Unit Test Template
-   As a developer, I want unit tests following AAA pattern, so that behavior and edge cases are covered.
-   Acceptance Criteria:
-
-- [ ] Template includes Arrange/Act/Assert structure
-- [ ] Happy path, error path, and edge cases present
-- [ ] describe/it nesting shown with naming examples
-
-6. Use Integration Test Template
-   As a developer, I want integration tests with setup/teardown and realistic flows, so that components work together.
-   Acceptance Criteria:
-
-- [ ] beforeEach/afterEach for fixtures
-- [ ] Full workflow with assertions on outcomes
-- [ ] Failure cases test rollback/consistency
-
-7. Use E2E Test Template
-   As a QA engineer, I want E2E tests using real browser patterns, so that user journeys are validated.
-   Acceptance Criteria:
-
-- [ ] Playwright/Cypress patterns demonstrated
-- [ ] UI interactions and state assertions included
-- [ ] Multi-step flows shown
-
-8. Apply Test Naming Conventions
-   As a reviewer, I want descriptive test names, so that intent is obvious without reading code.
-   Acceptance Criteria:
-
-- [ ] Good examples: behavior + condition ("should return X when Y")
-- [ ] Bad examples: vague or implementation-focused
-- [ ] Rename guidance provided
-
-9. Enforce Test Independence
-   As a developer, I want tests isolated with fresh state, so that order doesn't matter.
-   Acceptance Criteria:
-
-- [ ] Good example: beforeEach creates fresh state
-- [ ] Bad example: shared mutable state
-- [ ] No test depends on another test's side effects
-
-10. Know What to Test
-    As a developer, I want clear guidance on what to test vs skip, so that effort is focused.
-    Acceptance Criteria:
-
-- [ ] Test: public API, user features, edge cases, error handling, integrations
-- [ ] Don't test: private internals, third-party internals, trivial code
-- [ ] Examples clarify boundaries
-
-11. Use Test Data Builders
-    As a developer, I want reusable builders for complex test data, so that tests are concise.
-    Acceptance Criteria:
-
-- [ ] Builder function with override support shown
-- [ ] Example demonstrates customization per test
-- [ ] Reduces duplication across tests
-
-12. Apply LLM Testing Patterns
-    As a tester, I want rubric-based LLM evals, so that AI quality is testable.
-    Acceptance Criteria:
-
-- [ ] Promptfoo template with llm-rubric shown
-- [ ] EXCELLENT/ACCEPTABLE/POOR grading criteria defined
-- [ ] Integration test with real LLM call demonstrated
-
-13. INVEST Gate for Stories
-    As a product owner, I want every story to pass INVEST, so that it's deliverable and testable.
-    Acceptance Criteria:
-
-- [ ] Independent, Negotiable, Valuable, Estimable, Small, Testable
-- [ ] Failing any criterion triggers refinement or split
-- [ ] Checklist provided for validation
-
-14. Use Red Flags Quick Reference
-    As a reviewer, I want quick red flag checklists, so that common mistakes are caught fast.
-    Acceptance Criteria:
-
-- [ ] User story red flags listed (no AC, >3 AC, technical details, no value)
-- [ ] Test red flags listed (vague name, shared state, >50 lines, tests implementation)
-- [ ] E2E vs integration vs unit decision guidance included
-
-### test-definitions-guide.md
-
-1. Use the Standard Test Definitions Template
-   As a tester, I want to use the provided test definitions template, so that feature tests are consistent and complete.
-   Acceptance Criteria:
-
-- [ ] Read and fill `templates/test-definitions-feature.md`
-- [ ] Include feature name, issue number, and test file path
-- [ ] Save under `planning/test-definitions/[id]-[feature]-test-definitions.md`
-
-2. Organize Tests into Suites
-   As a maintainer, I want tests grouped logically, so that coverage is easy to navigate.
-   Acceptance Criteria:
-
-- [ ] Suites reflect layout/structure, interactions, state, accessibility, edge cases
-- [ ] Suite names/descriptions explain scope
-- [ ] Tests numbered (e.g., 1.1, 1.2)
-
-3. Track Test Status
-   As a contributor, I want consistent status indicators, so that progress is visible.
-   Acceptance Criteria:
-
-- [ ] Use ✅ Passing, ⏭️ Skipped (with rationale), ❌ Not Implemented, 🔴 Failing
-- [ ] Status listed per test
-- [ ] "Last Updated" maintained
-
-4. Write Clear Steps
-   As a tester, I want actionable, numbered steps, so that tests are reproducible.
-   Acceptance Criteria:
-
-- [ ] Steps are concrete and minimal
-- [ ] Avoid vague phrasing like "check it works"
-- [ ] Example step blocks used as reference
-
-5. Define Specific Expected Outcomes
-   As a tester, I want specific assertions, so that pass/fail is unambiguous.
-   Acceptance Criteria:
-
-- [ ] Expected outcomes are measurable
-- [ ] Avoid "everything works"
-- [ ] Example assertion blocks used as reference
-
-6. Coverage Summary
-   As a maintainer, I want a coverage breakdown, so that gaps are obvious.
-   Acceptance Criteria:
-
-- [ ] Totals and percentages per status
-- [ ] Coverage by feature table (if applicable)
-- [ ] Rationale for skipped tests
-
-7. Test Naming
-   As a reviewer, I want descriptive test names, so that intent is clear.
-   Acceptance Criteria:
-
-- [ ] Names describe observable behavior
-- [ ] Avoid "Test 1" or implementation details
-- [ ] Unique names across suite
-
-8. Test Execution Commands
-   As a developer, I want practical commands documented, so that I can run tests quickly.
-   Acceptance Criteria:
-
-- [ ] Include commands to run all tests for the feature
-- [ ] Include grep/example to run a specific test
-- [ ] Commands match project tooling
-
-9. TDD Workflow Integration
-   As a developer, I want tests defined before implementation and updated during delivery, so that TDD is enforced.
-   Acceptance Criteria:
-
-- [ ] Created before implementation and alongside user stories
-- [ ] Status updated as tests pass/skip/fail
-- [ ] "Last Updated" timestamp maintained
-
-10. Map to User Stories
-    As a PM/dev, I want tests to map directly to user story AC, so that verification is complete.
-    Acceptance Criteria:
-
-- [ ] Each user story AC has at least one test
-- [ ] Edge cases and errors included beyond AC
-- [ ] References to test file locations included
-
-11. Avoid Common Mistakes
-    As a reviewer, I want to block anti-patterns, so that definitions are high quality.
-    Acceptance Criteria:
-
-- [ ] No implementation details tested
-- [ ] No vague steps or missing coverage summaries
-- [ ] No duplicate test descriptions
-
-12. Apply LLM Instruction Design
-    As an author, I want LLM-optimized definitions, so that agents follow them reliably.
-    Acceptance Criteria:
-
-- [ ] Use MECE decision trees; define terms explicitly
-- [ ] Include concrete examples and edge cases
-- [ ] Use actionable language throughout
-
-1. Choose the Right Template
-   As a planner, I want to select the correct template (user stories, test definitions, design doc, architecture doc), so that documentation aligns with TDD workflow.
-   Acceptance Criteria:
-
-- [ ] Feature/issues → user stories template
-- [ ] Feature test suites → test definitions template
-- [ ] Feature/system implementation → design doc template
-- [ ] Project/package-wide decisions → architecture document
-
-2. Story Format Selection
-   As a writer, I want to choose the appropriate story format (standard, Given-When-Then, job story), so that intent is clear.
-   Acceptance Criteria:
-
-- [ ] Standard format used by default
-- [ ] Given-When-Then for behavior-focused stories
-- [ ] Job story for outcome-focused cases
-
-3. Story Acceptance Criteria and Scope
-   As a product owner, I want clear AC and explicit out-of-scope sections, so that delivery is measurable.
-   Acceptance Criteria:
-
-- [ ] 2–5 specific, testable AC
-- [ ] Out-of-scope listed to prevent creep
-- [ ] Links to tests/design doc when available
-
-4. Block Story Anti-Patterns
-   As a reviewer, I want to reject vague, technical-task, or bundled stories, so that stories remain valuable and small.
-   Acceptance Criteria:
-
-- [ ] Vague value or missing AC is blocked
-- [ ] Implementation-only “story” redirected to a task/spike
-- [ ] Bundled features split into multiple stories
-
-5. Create Test Definitions per Feature
-   As a tester, I want structured test definitions with status and coverage, so that verification is transparent.
-   Acceptance Criteria:
-
-- [ ] Suites and individual tests organized
-- [ ] Status per test: Passing/Skipped/Not Implemented/Failing
-- [ ] Coverage summary and execution commands included
-
-6. Unit Test Template Usage
-   As a developer, I want unit tests to follow the provided template, so that behavior and edge cases are covered.
-   Acceptance Criteria:
-
-- [ ] AAA structure used
-- [ ] Happy path, error path, and edge cases present
-- [ ] Deterministic assertions, no flaky timers/randomness
-
-7. Integration Test Template Usage
-   As a developer, I want integration tests with setup/teardown and realistic flows, so that components work together.
-   Acceptance Criteria:
-
-- [ ] Fixtures for DB/APIs handled in beforeEach/afterEach
-- [ ] Full workflow exercised with assertions on outcomes
-- [ ] Failure cases test rollback/consistency
-
-8. E2E Test Template Usage
-   As a QA engineer, I want E2E tests using a real browser, so that user journeys are validated.
-   Acceptance Criteria:
-
-- [ ] UI interactions scripted; URL/state assertions included
-- [ ] Page structure assertions reflect UX
-- [ ] Keep flows focused; long flows split
-
-9. Test Naming Conventions
-   As a reviewer, I want descriptive test names, so that intent is obvious.
-   Acceptance Criteria:
-
-- [ ] Names describe observable behavior and conditions
-- [ ] No vague or implementation-focused names
-- [ ] Rename flagged vague tests
-
-10. Test Independence
-    As a developer, I want tests isolated with fresh state, so that order does not matter.
-    Acceptance Criteria:
-
-- [ ] No shared mutable state across tests
-- [ ] Fresh fixtures per test via setup helpers
-- [ ] Flaky order-dependent tests prohibited
-
-11. What to Test vs Not Test
-    As a reviewer, I want guidance applied to focus on behavior, so that tests are high ROI.
-    Acceptance Criteria:
-
-- [ ] Public API and user features tested
-- [ ] Avoid private internals and third-party internals
-- [ ] Trivial code not tested unless business logic
-
-12. Test Data Builders
-    As a developer, I want reusable builders for complex data, so that tests are concise and maintainable.
-    Acceptance Criteria:
-
-- [ ] Builder functions with override support exist
-- [ ] Examples demonstrate customization
-- [ ] Builders shared across suites where sensible
-
-13. LLM-as-Judge Rubrics
-    As a tester, I want rubric-based evals for narrative/reasoning, so that subjective qualities are testable.
-    Acceptance Criteria:
-
-- [ ] Rubrics specify EXCELLENT/ACCEPTABLE/POOR criteria
-- [ ] Promptfoo (or equivalent) templates used when applicable
-- [ ] Avoid brittle keyword matching
-
-14. Integration with Real LLM
-    As an integration tester, I want real LLM calls for structured outputs, so that agent behavior is validated.
-    Acceptance Criteria:
-
-- [ ] Tests assert structured fields (not prose)
-- [ ] Costs acknowledged and minimized (e.g., ~$0.01 per test)
-- [ ] Sensitive secrets isolated in CI
-
-15. INVEST Gate for Stories
-    As a product owner, I want every story to pass INVEST, so that it’s deliverable and testable.
-    Acceptance Criteria:
-
-- [ ] Independent, Negotiable, Valuable, Estimable, Small, Testable
-- [ ] Failing any criterion triggers refinement
-- [ ] Split large stories before acceptance
-
-16. Red Flags and Ratios
-    As a maintainer, I want red flags enforced and test mix monitored, so that the suite stays efficient.
-    Acceptance Criteria:
-
-- [ ] Red flags checklist applied (long tests, dependencies, vague names)
-- [ ] Ratio baseline 70/20/10 (unit/integration/E2E) with documented adjustments per project
-- [ ] Prefer “as many fast tests as possible” principle with exceptions noted
-
-### testing-methodology.md
-
-1. Fastest-Effective Test Rule
-   As a developer, I want to choose the fastest test type that can catch a bug, so that feedback loops stay quick and cheap.
-   Acceptance Criteria:
-
-- [ ] Apply speed hierarchy: Unit → Integration → LLM Eval → E2E
-- [ ] If multiple apply, choose the faster one (tie-breaker)
-- [ ] Anti-patterns avoided (e.g., business logic via E2E)
-
-2. Component vs Flow Testing
-   As a tester, I want component behavior tested with integration and multi-page flows with E2E, so that each level is validated appropriately.
-   Acceptance Criteria:
-
-- [ ] UI components verified with integration tests (no real browser)
-- [ ] Multi-page flows use E2E with a real browser
-- [ ] Examples guide common cases
-
-3. Target Distribution Guidance
-   As a maintainer, I want guidance favoring fast tests, so that the suite remains efficient.
-   Acceptance Criteria:
-
-- [ ] Emphasize unit+integration; E2E only for critical paths
-- [ ] Add LLM evals only for AI features needing judgment
-- [ ] Red flag documented: more E2E than integration is too slow
-
-4. TDD Phases with Guardrails
-   As a developer, I want explicit steps for RED → GREEN → REFACTOR, so that TDD is followed correctly.
-   Acceptance Criteria:
-
-- [ ] RED: write failing test, verify it fails for correct reason, commit test
-- [ ] GREEN: minimum code to pass, no extra features (YAGNI)
-- [ ] REFACTOR: improve design with tests green; optional subagent validation
-
-5. Test Type Decision Tree
-   As a tester, I want a sequential decision tree, so that I can deterministically select test type.
-   Acceptance Criteria:
-
-- [ ] Ordered questions: LLM Eval → E2E → Integration → Unit
-- [ ] Edge cases: non-determinism → mock; env deps → integration; mixed → split
-- [ ] Re-evaluation path documented with example (login validation)
-
-6. Bug-to-Test Mapping Table
-   As a planner, I want a lookup table mapping bug types to test types, so that choices are consistent.
-   Acceptance Criteria:
-
-- [ ] Include calculation, API, DB, state, CSS, navigation cases
-- [ ] “Best choice” favors fastest viable test
-- [ ] Aligns with decision tree
-
-7. E2E Dev/Test Server Isolation
-   As a QA engineer, I want isolated ports and processes for E2E, so that we avoid port conflicts and zombie processes.
-   Acceptance Criteria:
-
-- [ ] Dev on stable port; tests on devPort+1000 (or ephemeral fallback)
-- [ ] Playwright config uses isolated port and reuse rules
-- [ ] Package scripts include dev and dev:test commands
-
-8. LLM Evaluations Usage
-   As a tester, I want to use LLM evals with rubrics when judging quality, so that nuanced outputs are verified.
-   Acceptance Criteria:
-
-- [ ] Use programmatic assertions for structure; use LLM-as-judge for tone/reasoning
-- [ ] Skip evals when simple/deterministic
-- [ ] Costs acknowledged; caching used
-
-9. Cost Controls for Evals
-   As a maintainer, I want to reduce eval costs, so that CI remains affordable.
-   Acceptance Criteria:
-
-- [ ] Cache static prompts/examples
-- [ ] Batch scenarios; schedule full evals (e.g., PR/weekly)
-- [ ] Document expected costs and ROI
-
-10. Coverage Goals and Critical Paths
-    As a team, I want clear coverage goals and critical path definitions, so that tests cover what matters.
-    Acceptance Criteria:
-
-- [ ] Unit: 80%+ for pure functions
-- [ ] E2E: all critical multi-page flows; Integration: all critical paths
-- [ ] “Critical” defined (auth, payment, data loss, core flows)
-
-11. Test Quality Practices
-    As a developer, I want clear guidance on writing effective tests, so that tests are reliable and maintainable.
-    Acceptance Criteria:
-
-- [ ] AAA pattern enforced; descriptive naming; independent tests
-- [ ] Async uses polling/selectors (no arbitrary timeouts)
-- [ ] What not to test documented (implementation details, trivial code, third-party internals)
-
-12. CI/CD Testing Cadence
-    As a maintainer, I want a CI plan that balances speed and confidence, so that pipelines are efficient.
-    Acceptance Criteria:
-
-- [ ] Unit+integration on every commit; E2E on PR; evals on schedule
-- [ ] No skipped tests without justification
-- [ ] Coverage thresholds enforced
-
-13. Project-Specific Testing Doc
-    As a maintainer, I want `tests/SAFEWORD.md` to document stack/commands/patterns, so that contributors can run tests correctly.
-    Acceptance Criteria:
-
-- [ ] File exists with stack, commands, setup, file structure, patterns
-- [ ] TDD expectations, coverage and PR requirements included
-- [ ] If missing, ask where testing docs are and create/update
-
-14. Test Integrity Guardrails
-    As a developer, I want explicit rules preventing test modifications without approval, so that tests remain trusted specifications.
-    Acceptance Criteria:
-
-- [ ] Tests not modified/skipped/deleted without human approval
-- [ ] Forbidden actions enforced (changing assertions, .skip(), weakening, deleting)
-- [ ] Implementation fixed when test fails (not the test)
-- [ ] Requirement changes discussed before test updates
-
-### user-story-guide.md
-
-1. Use the Standard User Stories Template
-   As a planner, I want to use the provided user stories template, so that stories are consistent and easy to track.
-   Acceptance Criteria:
-
-- [ ] Fill `templates/user-stories-template.md` with feature name, issue number, status
-- [ ] Number stories (Story 1, Story 2, …)
-- [ ] Save to `planning/user-stories/[id]-[feature].md` (or project convention)
-
-2. Include Tracking Metadata
-   As a PM, I want status, test refs, and completion summaries, so that progress is visible.
-   Acceptance Criteria:
-
-- [ ] ✅/❌ per story and per AC
-- [ ] Test file references included
-- [ ] Completion % and phase tracking present; next steps listed
-
-3. INVEST Validation Gate
-   As a reviewer, I want INVEST validation before saving, so that stories are deliverable.
-   Acceptance Criteria:
-
-- [ ] Independent, Negotiable, Valuable, Estimable, Small, Testable
-- [ ] If any fail → refine or split before merge
-- [ ] Validation documented in the story file or PR notes
-
-4. Write Good Acceptance Criteria
-   As a writer, I want specific, user-facing, testable AC, so that done is unambiguous.
-   Acceptance Criteria:
-
-- [ ] AC specify measurable behavior (e.g., “<200ms”)
-- [ ] Avoid technical/implementation details
-- [ ] Avoid vague phrasing (“works”, “better”)
-
-5. Size Guidelines Enforcement
-   As a planner, I want size checks, so that stories are right-sized.
-   Acceptance Criteria:
-
-- [ ] Split if 6+ AC, multiple personas, multiple screens, or >6 days
-- [ ] Combine if trivial (<1 hour, no AC)
-- [ ] Target: 1–5 AC, 1–2 screens/personas, 1–5 days
-
-6. Good/Bad Examples Reference
-   As a contributor, I want examples of good vs bad stories, so that quality is consistent.
-   Acceptance Criteria:
-
-- [ ] Provide at least one good story example in the doc
-- [ ] Provide a “too big” and “no value” anti-example
-- [ ] Technical tasks labeled as tasks/spikes (not user stories)
-
-7. Conversation, Not Contract
-   As a team, I want stories to be conversation starters, so that details emerge collaboratively.
-   Acceptance Criteria:
-
-- [ ] Discuss edge cases, approach, open questions during planning
-- [ ] Story avoids implementation details and test strategies
-- [ ] Link to UI mockups instead of embedding
-
-8. LLM-Optimized Wording
-   As a writer, I want LLM-friendly wording, so that agents follow stories reliably.
-   Acceptance Criteria:
-
-- [ ] Use specific, concrete language with numbers where helpful
-- [ ] Define terms explicitly; avoid generic phrases
-- [ ] Use examples over abstract rules
-
-9. Token Efficiency of Template
-   As a maintainer, I want minimal template overhead, so that prompting cost stays low.
-   Acceptance Criteria:
-
-- [ ] Keep template lean (≈9 lines)
-- [ ] Flat structure, no nested sections or validation metadata
-- [ ] Reuse standard sections across stories
-
-10. File Naming Conventions
-    As a contributor, I want descriptive filenames, so that stories are discoverable.
-    Acceptance Criteria:
-
-- [ ] Use descriptive slugs (e.g., `campaign-switching.md`)
-- [ ] Avoid generic or bloated names
-- [ ] Place under `docs/stories/` when appropriate
-
-### zombie-process-cleanup.md
-
-1. Prefer Port-Based Cleanup
-   As a developer, I want to kill processes by port, so that I don’t affect other projects.
-   Acceptance Criteria:
-
-- [ ] Use `lsof -ti:PORT | xargs kill -9` for dev servers
-- [ ] Avoid blanket `killall node` or `pkill -9 node`
-- [ ] Verify port uniqueness per project
-
-2. Project-Specific Cleanup Script
-   As a maintainer, I want a `scripts/cleanup.sh`, so that cleanup is safe and repeatable.
-   Acceptance Criteria:
-
-- [ ] Script kills by project port and filters by current directory
-- [ ] Handles dev server, Playwright browsers, and test runners
-- [ ] Mark executable and document usage
-
-3. Unique Port Assignment
-   As a team, I want unique ports per project, so that cleanup is unambiguous.
-   Acceptance Criteria:
-
-- [ ] Set explicit `PORT` per project (e.g., 3000, 3001)
-- [ ] Document ports in README or env
-- [ ] Verify in CI/local scripts
-
-4. tmux/Screen Isolation (Optional)
-   As a developer, I want isolated terminal sessions, so that I can kill everything for one project safely.
-   Acceptance Criteria:
-
-- [ ] Start dev in a named session
-- [ ] One command kills only that session
-- [ ] Trade-offs documented (learning curve)
-
-5. Debugging Zombie Processes
-   As a developer, I want quick commands to find processes, so that I can target cleanup precisely.
-   Acceptance Criteria:
-
-- [ ] Commands to find by port, by process type, and by project directory
-- [ ] Guidance for listing node/playwright/chromium
-- [ ] Prefer filtered kills using `$(pwd)` pattern
-
-6. Best Practices
-   As a maintainer, I want a short best-practices list, so that the team consistently avoids cross-project kills.
-   Acceptance Criteria:
-
-- [ ] Assign unique ports; use port-based cleanup first
-- [ ] Create and use project cleanup scripts
-- [ ] Clean before start; check with `lsof -i:PORT`
-
-7. Quick Reference
-   As a developer, I want a quick-reference table, so that I can copy/paste safe commands.
-   Acceptance Criteria:
-
-- [ ] Include kill by port, kill playwright for this project, full cleanup script
-- [ ] Include commands to check ports and find zombies
-- [ ] Warn against dangerous global kills