safeword 0.2.4 → 0.2.5

package/.safeword/guides/architecture-guide.md

@@ -1,404 +0,0 @@
-# Architecture & Design Documentation Guide
-
-**See:** `@.safeword/guides/llm-instruction-design.md` for LLM-consumable documentation principles.
-
----
-
-## Document Type Decision Tree (Follow in Order)
-
-Answer **IN ORDER**. Stop at the first "Yes":
-
-1. **Technology or library choice?** → **Architecture Doc**
-2. **New data model or schema change?** → **Architecture Doc**
-3. **Project-wide pattern or convention?** → **Architecture Doc**
-4. **Implementing a specific feature?** → **Design Doc**
-
-**Tie-breaker:** If a feature requires a new tech/schema choice, document the tech/schema in Architecture Doc first, then reference it in Design Doc.
-
-| Term | Definition |
-|------|------------|
-| Technology choice | Selecting a library, framework, database, or tool |
-| Schema change | Adding/modifying entities, tables, relationships, or data types |
-| Project-wide pattern | Convention that applies to 2+ features or multiple developers |
-| Major decision | Affects 2+ components, costs >$100/month, or cannot be easily reversed |
-| Living document | Updated in place (not immutable); changes tracked via version/status |
-| ADR | Architecture Decision Record—legacy pattern of separate files per decision |
-
----
-
-## Quick Decision Matrix
-
-| Scenario | Doc Type | Rationale |
-|----------|----------|-----------|
-| Choosing between technologies | Architecture | Tech choice affects whole project |
-| Data model design | Architecture | Schema is project-wide |
-| Implementing a new feature | Design | Feature-scoped implementation |
-| Recording a trade-off | Architecture | Trade-offs inform future decisions |
-| Project-wide principles | Architecture | Principles apply everywhere |
-| Component breakdown for feature | Design | Implementation detail |
-| Feature needs new schema | Architecture first, then Design | Schema in Arch, feature in Design |
-
----
-
-## Architecture Document
-
-**Use when**: Project-wide decisions, data models, system design
-
-**Characteristics**:
-- One per project/package (in monorepos)
-- Living document (updated in place—not immutable ADRs)
-- Documents WHY behind all major decisions
-- Includes version, status, table of contents
-
-**Location**: Project root (`ARCHITECTURE.md`)
-
-**Edge cases:**
-- Schema change for one feature → Architecture Doc (schema is project-wide)
-- Library for one feature → Architecture Doc if precedent-setting; Design Doc if one-off
-- Performance optimization → Architecture Doc if changes patterns; Design Doc if feature-specific
-
-### Required Sections
-
-- **Header**: Version, Last Updated, Status (Production/Design/Proposed/Deprecated)
-- **Table of Contents**: Section links
-- **Overview**: Technology choices, data model philosophy, high-level architecture
-- **Data Model / Schema**: Tables, types, relationships
-- **Key Decisions**: What, Why, Trade-off, Alternatives Considered
-- **Best Practices**: Domain-specific patterns
-- **Migration Strategy**: How to evolve architecture
-
----
-
-## Design Document
-
-**Use when**: Designing a specific feature implementation
-
-**Characteristics**:
-- Feature-focused (~121 lines)
-- Implementation details (components, data flow, user flow)
-- References architecture doc (don't duplicate)
-
-**Location**: `planning/design/` or `docs/design/`
-
-**Edge cases:**
-- Feature needs new data model → Schema in Architecture Doc first, then reference
-- Feature spans 3+ components → Still Design Doc (component count doesn't change doc type)
-- Feature establishes pattern others follow → Pattern in Architecture Doc, implementation in Design Doc
-
-**See:** `@.safeword/guides/design-doc-guide.md` for detailed guidance
-
----
-
-## Best Practices
-
-### 1. One Architecture Doc Per Project/Package
-
-**✅ GOOD:**
-```
-project/
-├── ARCHITECTURE.md
-└── docs/design/
-    ├── feature-a.md
-    └── feature-b.md
-```
-
-**❌ BAD:** `docs/adr/001-use-typescript.md, 002-adopt-monorepo.md...` (50+ files = fragmented context)
-
-### 2. Living Document (Not Immutable)
-
-Update in place with version/status tracking:
-
-```markdown
-### Decision: State Management
-**Status**: Active (Updated 2025-01-20)
-**What**: Migrated from localStorage to IndexedDB
-**Why**: Hit 5MB limit, needed unlimited storage
-**Migration**: Completed 2025-01-20, users auto-migrated on load
-```
-
-**Edge cases:**
-- Decision reversed → Update original with "Superseded" status
-- Major shift → Bump version (v1 → v2), add migration section
-- Affects multiple subsystems → Update main Architecture Doc, not separate files
-
-### 3. Document WHY, Not Just WHAT
-
-**✅ GOOD:**
-```markdown
-### Principle: Separation of Concerns
-**What**: Static data → immutable storage; Mutable state → persistent storage
-**Why**: Static data saves NKB per instance; updates affect all instances instantly
-**Trade-off**: More complex loading (fetch static + query persistent)
-**Alternatives Considered**: All localStorage (rejected: 5MB limit); All IndexedDB (rejected: overkill for config)
-```
-
-**❌ BAD:** `Database: PostgreSQL, State: Zustand, UI: React` (no rationale)
-
-**Required fields:**
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| What | Always | The decision (1-2 sentences) |
-| Why | Always | Rationale with specifics (numbers, metrics) |
-| Trade-off | Always | What we gave up or accepted |
-| Alternatives | Major decisions | Other options and why rejected |
-| Migration | If breaking | How to evolve from previous state |
-
-**Edge cases:**
-- Obvious choice → Still document; future devs may question
-- Inherited decision → Document as "Inherited: [reason]"
-- Temporary decision → Mark "Temporary" with planned review date
-
-### 4. Include Code References
-
-**✅ GOOD:**
-```markdown
-**Implementation**: See `src/stores/gameStore.ts:12-45`
-**Usage example**: See `src/components/GamePanel.tsx`
-```
-
-**❌ BAD:** "We use Zustand for state management" (no reference to actual code)
-
-- Key patterns → file + line range
-- Simple utilities → file path only (no line numbers)
-- Frequently changing code → file path only (line numbers go stale)
-
-### 5. Version and Track Status
-
-| Status | Meaning |
-|--------|---------|
-| Design | Initial draft, not yet implemented |
-| Production | Live in production |
-| Proposed | Planned extension to production |
-| Deprecated | Being phased out |
-
-**Version bumps:** Major schema changes → v1 → v2; New sections → v1.0 → v1.1; Clarifications → no bump
-
----
-
-## TDD Workflow Integration
-
-**Workflow Order**:
-1. User Stories → What we're building
-2. Test Definitions → How we'll verify
-3. Design Doc → How we'll build it
-4. Check Architecture Doc → New tech/schema needed?
-5. Implement (RED → GREEN → REFACTOR)
-6. Update Architecture Doc if needed
-
-### When to Update Architecture Doc
-
-| Trigger | Example |
-|---------|---------|
-| New data model concept | New "Subscription" entity |
-| Technology choice | "Chose Resend for email" |
-| New pattern/convention | "All forms use react-hook-form" |
-| Architectural insight during implementation | "IndexedDB needed for offline" |
-| Performance bottleneck requiring change | "Migrated to Redis for sessions" |
-
-### When NOT to Update
-
-| Scenario | Where Instead |
-|----------|---------------|
-| Single feature implementation | Design Doc |
-| Bug fix | Code comments if complex |
-| Refactor without pattern change | PR description |
-
-**Edge case:** Bug fix reveals architectural flaw → Document flaw and fix in Architecture Doc.
-
----
-
-## Common Mistakes
-
-### Architecture Doc Anti-Patterns
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| ADR sprawl (001, 002...) | One comprehensive `ARCHITECTURE.md` |
-| No decision rationale | Add What/Why/Trade-off |
-| Missing version/status | Add header with Version and Status |
-| Implementation details | Move to Design Doc or code |
-
-**❌ BAD:** `GET /api/users → Returns users from PostgreSQL` (implementation detail)
-
-**✅ GOOD:** `API Design: RESTful routes with input validation at boundary` (principle)
-
-### Design Doc Anti-Patterns
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Repeating architecture content | Reference Architecture Doc |
-| Skipping user flow | Include step-by-step interaction |
-| Missing test mapping | Link to test definitions |
-| >200 lines | Split or extract to Architecture |
-
----
-
-## Re-evaluation Path (When Unclear)
-
-Answer **IN ORDER**:
-
-1. **Affects 2+ features?** → Architecture Doc (stop)
-2. **Technology/data model choice?** → Architecture Doc (stop)
-3. **Future developers need this for whole project?** → Architecture Doc
-4. **Only for this feature?** → Design Doc
-
-**Tie-breaker:** When still unclear, default to Design Doc. Easier to promote later than to split.
-
-### Worked Example: Adding User Notifications
-
-**Scenario:** Add email notifications when users complete a purchase.
-
-1. **Affects 2+ features?** No, only checkout → Continue
-2. **Tech choice?** Yes, need to choose email service (SendGrid vs SES) → **Architecture Doc**
-
-**Result:**
-- `ARCHITECTURE.md` → "Email Service: SendGrid (Why: deliverability, cost, SDK quality)"
-- `planning/design/checkout-notifications.md` → Feature implementation referencing email decision
-
----
-
-## File Organization
-
-```
-project/
-├── ARCHITECTURE.md              # Single comprehensive doc
-├── .safeword/planning/
-│   ├── user-stories/
-│   ├── test-definitions/
-│   └── design/                  # Feature-specific design docs
-└── src/
-```
-
----
-
-## Layers & Boundaries
-
-**Purpose:** Define architectural layers and enforce dependency rules to prevent circular dependencies, god modules, and leaky abstractions.
-
-### Layer Definitions
-
-| Layer | Directory | Responsibility |
-|-------|-----------|----------------|
-| app | `src/app/` | UI, routing, composition |
-| domain | `src/domain/` | Business rules, pure logic |
-| infra | `src/infra/` | IO, APIs, DB, external SDKs |
-| shared | `src/shared/` | Utilities usable by all layers |
-
-### Allowed Dependencies
-
-| From | To | Allowed | Rationale |
-|------|-----|---------|-----------|
-| app | domain | ✅ | UI composes business logic |
-| app | infra | ✅ | UI triggers side effects |
-| app | shared | ✅ | Utilities available everywhere |
-| domain | app | ❌ | Domain must be framework-agnostic |
-| domain | infra | ❌ | Domain contains pure logic only |
-| domain | shared | ✅ | Utilities available everywhere |
-| infra | domain | ✅ | Adapters may use domain types |
-| infra | app | ❌ | Infra should not depend on UI |
-| infra | shared | ✅ | Utilities available everywhere |
-| shared | * | ❌ | Shared has no dependencies (except external libs) |
-
-**Note:** This template allows direct app→infra. Alternative: force app→domain→infra for stricter separation (hexagonal/ports-adapters pattern).
-
-### Edge Cases
-
-| Scenario | Solution |
-|----------|----------|
-| Project doesn't fit 3-layer model | Document actual layers, same boundary rules apply |
-| Feature module needs another feature | Import via public API (`index.ts`) only |
-| Shared utilities | Create `shared/` layer, all layers may import |
-| Brownfield adoption | Start with warnings-only mode, fix violations incrementally, then enforce |
-| Monorepo with multiple apps | Each app has own layers; shared packages are explicit dependencies |
-
-### Enforcement with eslint-plugin-boundaries
-
-**Setup:**
-
-1. Install: `npm install --save-dev eslint-plugin-boundaries`
-
-2. Add to `eslint.config.mjs`:
-
-```javascript
-import boundaries from 'eslint-plugin-boundaries';
-
-export default defineConfig([
-  // ... other configs ...
-  {
-    name: 'boundaries-config',
-    files: ['**/*.{js,ts,tsx}'],
-    plugins: { boundaries },
-    settings: {
-      'boundaries/include': ['src/**/*'],
-      'boundaries/elements': [
-        { type: 'app', pattern: 'src/app/**/*' },
-        { type: 'domain', pattern: 'src/domain/**/*' },
-        { type: 'infra', pattern: 'src/infra/**/*' },
-        { type: 'shared', pattern: 'src/shared/**/*' },
-      ],
-    },
-    rules: {
-      'boundaries/element-types': ['error', {
-        default: 'disallow',
-        rules: [
-          { from: 'app', allow: ['domain', 'infra', 'shared'] },
-          { from: 'domain', allow: ['shared'] },
-          { from: 'infra', allow: ['domain', 'shared'] },
-          { from: 'shared', allow: [] },
-        ],
-      }],
-      'boundaries/no-unknown-files': 'error',
-    },
-  },
-]);
-```
-
-3. Define layers in `ARCHITECTURE.md` (see template)
-
-4. Errors appear in IDE + CI automatically
-
-**Common Issues:**
-
-| Issue | Fix |
-|-------|-----|
-| "Unknown file" errors | Ensure all source files are in defined layers |
-| False positives on tests | Exclude test files: `'boundaries/include': ['src/**/*', '!**/*.test.*']` |
-| External library imports flagged | External deps are allowed by default; check `boundaries/ignore` setting |
-
----
-
-## Data Architecture
-
-**For data-heavy projects**, see `@.safeword/guides/data-architecture-guide.md` for:
-- Core principles (data quality, governance, accessibility)
-- What to document (conceptual/logical/physical models, flows, policies)
-- Integration with TDD workflow
-
----
-
-## Quality Checklist
-
-**Architecture Doc:**
-- [ ] Sequential decision tree or clear structure
-- [ ] All decisions have What/Why/Trade-off
-- [ ] Version and Status in header
-- [ ] Code references for key patterns
-- [ ] No implementation details
-
-**Design Doc:**
-- [ ] References Architecture Doc (no duplication)
-- [ ] User flow step-by-step
-- [ ] Test mapping links
-- [ ] ~121 lines target
-
----
-
-## Key Takeaway
-
-**One comprehensive architecture document per project** > many scattered ADR files:
-
-✅ Full context in one place
-✅ Living document (update in place)
-✅ LLMs consume entire architecture at once
-✅ Sequential decision trees prevent ambiguity

package/.safeword/guides/code-philosophy.md

@@ -1,174 +0,0 @@
-# Code Philosophy & Practices
-
-**Note:** This file provides instructions for LLM-based coding agents. For comprehensive framework on writing clear, actionable LLM-consumable instructions, see `@.safeword/guides/llm-instruction-design.md`.
-
----
-
-## Communication Style
-- Be concise, clear, direct, technical, friendly, and educational
-- Show reasoning when it adds value, otherwise just deliver results
-- No emojis unless explicitly requested
-
-## Response Format
-At the end of EVERY response, include a JSON summary with this exact structure:
-```json
-{"proposedChanges": boolean, "madeChanges": boolean, "askedQuestion": boolean}
-```
-
-Where (all fields describe **this response only**, not cumulative):
-- `proposedChanges`: `true` if you suggested/proposed changes to specific files **in this response**
-- `madeChanges`: `true` if you **modified files in this response** using Write/Edit tools
-- `askedQuestion`: `true` if you asked the user a question and need their response before proceeding
-
-Examples:
-- Discussed approach only: `{"proposedChanges": false, "madeChanges": false, "askedQuestion": false}`
-- Proposed edits but waiting for approval: `{"proposedChanges": true, "madeChanges": false, "askedQuestion": false}`
-- Made edits directly: `{"proposedChanges": false, "madeChanges": true, "askedQuestion": false}`
-- Proposed AND made edits: `{"proposedChanges": true, "madeChanges": true, "askedQuestion": false}`
-- Asked user a question: `{"proposedChanges": false, "madeChanges": false, "askedQuestion": true}`
-- **Quality review response** (no new changes): `{"proposedChanges": false, "madeChanges": false, "askedQuestion": false}`
-
-## Code Philosophy
-- **Elegant code and architecture** - Prioritize developer experience
-- **AVOID BLOAT** - Simple, focused solutions over complex ones
-- **Self-documenting code** - Minimal inline comments, clear naming and structure
-- **Explicit error handling** - NEVER suppress or swallow errors silently
-
-**Error handling examples:**
-| ❌ Bad | ✅ Good |
-|--------|---------|
-| `catch (e) {}` (swallowed) | `catch (e) { throw new Error(\`Failed to read ${filePath}: ${e.message}\`) }` |
-| `catch (e) { console.log(e) }` | `catch (e) { logger.error('Payment failed', { userId, amount, error: e }) }` |
-| Generic "Something went wrong" | "Failed to save user profile: database connection timeout" |
-
-**Naming examples:**
-| ❌ Bad | ✅ Good |
-|--------|---------|
-| `calcTot` | `calculateTotalWithTax` |
-| `d`, `tmp`, `data` | `userProfile`, `pendingOrders` |
-| `handleClick` | `submitPaymentForm` |
-| `process()` | `validateAndSaveUser()` |
-
-**When to comment:**
-- ✅ Non-obvious business logic ("Tax exempt for orders >$500 per policy X")
-- ✅ Workarounds ("Safari requires this delay due to bug #123")
-- ❌ Obvious code (`// increment counter` before `i++`)
-- ❌ Restating the function name
-
-**Bloat examples (avoid these):**
-| ❌ Bloat | ✅ Instead |
-|----------|-----------|
-| Utility class for one function | Single function |
-| Factory pattern for simple object | Direct construction |
-| Abstract base class with one implementation | Concrete class |
-| Config file for 2 options | Hardcode or simple params |
-| "Future-proofing" unused code paths | Delete, add when needed |
-
-**When to push back:** If a feature request would add >50 lines for a "nice to have", ask: "Is this essential now, or can we add it later?"
-
-## Documentation Verification (CRITICAL)
-- **Always look up current documentation** for libraries, tools, and frameworks
-- Do NOT assume API compatibility - verify the actual version being used
-- Check docs unless they're already loaded in the context window
-- **NEVER assume features exist** - Training data is at least 1 year old; when uncertain, verify first
-
-**How to verify:**
-1. Check `package.json` (or equivalent) for installed version
-2. Use Context7 MCP or official docs for current API
-3. If uncertain, ask user: "Which version of X are you using?"
-
-## Testing Philosophy
-
-**Test what matters** - Focus on user experience and delivered features, not implementation details.
-
-**Test-Driven Development (TDD):**
-- Write tests BEFORE implementing features (RED → GREEN → REFACTOR)
-- Tests define expected behavior, code makes them pass
-- Refactor with confidence knowing tests catch regressions
-
-**Always test what you build** - Run tests yourself before completion. Don't ask the user to verify.
-
-**NEVER modify or skip tests without approval:**
-- ❌ Changing test expectations to match broken code
-- ❌ Adding `.skip()` or `.todo()` to make failures go away
-- ❌ Deleting tests you can't get passing
-- ✅ If a test fails, fix the implementation—not the test
-- ✅ If a test seems wrong or requirements changed, explain why and ask before changing it
-
-**Workflow:** See `@.safeword/guides/testing-methodology.md` for comprehensive TDD workflow (RED → GREEN → REFACTOR phases)
-
-## Debugging & Troubleshooting
-
-**Debug Logging:**
-- When debugging, log **actual vs expected** values (not just pass/fail)
-- Use JSON.stringify() for complex objects to see structure
-- Remove debug logging after fixing (keep production code clean)
-
-```javascript
-// ❌ Bad: console.log('here')
-// ✅ Good: console.log('validateUser', { expected: 'admin', actual: user.role })
-```
-
-**Cross-Platform Development:**
-- Test on all target platforms early (macOS, Windows, Linux)
-- Never assume Unix-style paths (`/`) - handle both `/` and `\`
-- Be aware of runtime environment (browser vs Node.js, client vs server)
-
-```javascript
-// ❌ Bad: dir + '/' + filename
-// ✅ Good: path.join(dir, filename)
-```
-
-## Best Practices (Always Apply)
-Before implementing, research and apply:
-- **Tool-specific best practices** - Use libraries/frameworks as intended
-- **Domain best practices** - Follow conventions for the type of app (CLI, web editor, API, etc.)
-- **UX best practices** - Prioritize user experience in design decisions
-
-**How to research:** Use Context7 MCP or official docs. Check for established patterns before inventing your own.
-
-## Self-Review Checklist
-Before completing any work, verify:
-- ✓ Is it correct? Will it actually work?
-- ✓ Is it elegant? Does it avoid bloat?
-- ✓ Does it follow best practices?
-- ✓ Are you using the right docs/versions?
-- ✓ Have you tested the user-facing functionality?
-
-**Blockers:** If something can't be fixed now, note it explicitly: "Deferred: [issue] because [reason]"
-
-## Asking Questions
-- **Be proactive and self-sufficient** - Don't be lazy
-- Only ask questions when you genuinely can't find the answer through:
-  - Online documentation and research
-  - Reading the codebase
-  - Running tests or experiments
-- Ask non-obvious questions that require user domain knowledge or preferences
-- **When asking, show what you tried:** "I checked X and Y but couldn't determine Z. What's your preference?"
-
-## Tools & CLIs
-
-**Keep these updated** (check before starting new projects):
-- GitHub CLI (`gh`)
-- AWS CLI
-- Railway CLI
-- PostHog CLI
-
-**Update workflow:**
-1. Check current version: `gh --version`, `aws --version`, etc.
-2. Check for updates: `brew upgrade gh` or tool-specific update command
-3. Review changelog for breaking changes before major version updates
-4. If breaking changes affect your workflow, pin to current version until migration planned
-
-**When to pin versions:** If a tool is used in CI/automation, pin to specific version in scripts to avoid surprise breakages.
-
-## Git Workflow
-- Commit whenever work is completed
-- Commit often to checkpoint progress
-- Use descriptive commit messages
-- Make atomic commits (one logical change per commit)
-
-```
-# ❌ Bad: "misc fixes"
-# ✅ Good: "fix: login button not responding to clicks"
-```