safeword 0.2.3 → 0.2.4

package/.safeword/templates/ci/architecture-check.yml

@@ -0,0 +1,79 @@
+# Architecture Check CI Workflow
+#
+# Runs on pull requests to enforce architectural boundaries.
+#
+# Steps:
+# 1. Type check (tsc --noEmit)
+# 2. ESLint (includes eslint-plugin-boundaries)
+# 3. LLM architecture review (optional, non-blocking)
+#
+# Usage:
+# 1. Copy to .github/workflows/architecture-check.yml
+# 2. Set ANTHROPIC_API_KEY secret (optional, for LLM review)
+# 3. Adjust paths and triggers as needed
+
+name: Architecture Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'src/**'
+      - 'package.json'
+      - 'tsconfig.json'
+      - 'eslint.config.mjs'
+
+jobs:
+  architecture-check:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Step 1: Type check
+      - name: TypeScript Check
+        run: npx tsc --noEmit
+        continue-on-error: false
+
+      # Step 2: ESLint (includes boundary rules)
+      - name: ESLint
+        run: npm run lint
+        continue-on-error: false
+
+      # Step 3: LLM Architecture Review (optional)
+      # Only runs if ANTHROPIC_API_KEY is set
+      # Non-blocking by default (continue-on-error: true)
+      - name: Architecture Review (LLM)
+        if: ${{ secrets.ANTHROPIC_API_KEY != '' }}
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          # Get changed files in this PR
+          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(js|ts|tsx|jsx)$' || true)
+          
+          if [ -n "$CHANGED_FILES" ]; then
+            echo "Reviewing changed files:"
+            echo "$CHANGED_FILES"
+            echo ""
+            
+            # Run architecture review if script exists
+            if [ -f ".safeword/scripts/arch-review.sh" ]; then
+              echo "$CHANGED_FILES" | xargs bash .safeword/scripts/arch-review.sh || true
+            else
+              echo "arch-review.sh not found, skipping LLM review"
+            fi
+          else
+            echo "No JS/TS files changed"
+          fi
+        continue-on-error: true  # Non-blocking (advisory only)
+

package/.safeword/templates/design-doc-template.md

@@ -0,0 +1,127 @@
+# Design: [Feature Name]
+
+**Guide**: `@./.safeword/guides/design-doc-guide.md` - Principles, structure guidelines, and avoiding bloat
+**Template**: `@./.safeword/templates/design-doc-template.md`
+
+**Related**: User Stories: `[path]` | Test Definitions: `[path]`
+
+**TDD Note**: This design implements tests from Test Definitions. Reference specific test scenarios (e.g., "Test 3.1: Component X enables keyboard shortcut Y").
+
+## Architecture
+
+[1-2 paragraphs: High-level approach. What are we building and how does it fit together?]
+
+**Diagram** (if applicable):
+[Text diagram or link to visual]
+
+## Components
+
+### Component [N]: [ComponentName]
+
+**What**: [Responsibility in 1 sentence]
+**Where** (if applicable): `[file/path/component.ts]`
+**Interface**:
+```typescript
+// Key types/interfaces
+interface Example {
+  id: string;
+  // ...
+}
+
+// Key methods
+function doSomething(input: Example): Result;
+```
+
+**Dependencies**: [What it uses]
+**Tests**: [Which test scenarios this component enables]
+
+### Component [N+1]: [AnotherComponentName]
+
+**What**: [Different responsibility than Component N]
+**Where** (if applicable): `[different/file/path.ts]`
+**Interface**:
+```typescript
+// Different example
+interface AnotherExample {
+  value: string;
+}
+
+function anotherMethod(input: AnotherExample): Output;
+```
+
+**Dependencies**: [Different dependencies]
+**Tests**: [Different test scenarios this enables]
+
+## Data Model (if applicable)
+
+[Describe state shape, database schema, or data structures. Include relationships between types and how data flows through the system.]
+
+```typescript
+// Core data structures
+interface FeatureState {
+  items: Item[];
+  selectedId: string | null;
+}
+
+interface Item {
+  id: string;
+  name: string;
+  // ...
+}
+```
+
+## Component Interaction (if applicable)
+
+[How components communicate and data flows between them]
+
+**Flow:**
+Component [N] → Component [N+1]
+
+**Events/Calls:**
+- Component [N] triggers [event/method] in Component [N+1]
+- Component [N+1] updates [state/data] consumed by [other components/system]
+
+## User Flow
+
+1. User [action, e.g., clicks "Toggle AI Pane" button, presses Cmd+J]
+2. System [response, e.g., updates state, triggers re-render, calls API]
+3. User sees [outcome, e.g., AI pane appears/disappears, loading spinner, error message]
+
+## Key Decisions
+
+### Decision [N]: [Technical choice]
+
+**What**: [What we're using/doing]
+**Why**: [Rationale with specifics - include metrics, benchmarks, or analysis]
+**Trade-off**: [What we're giving up]
+
+### Decision [N+1]: [Technical choice]
+
+**What**: [Different choice than Decision N]
+**Why**: [Rationale with specifics - include metrics, benchmarks, or analysis]
+**Trade-off**: [Different trade-off]
+
+## Implementation Notes (if applicable)
+
+**Constraints**:
+- [Technical limitation, e.g., "Must support Safari 14+", "No Node.js dependencies"]
+- [Performance requirement, e.g., "< 200ms response time", "Bundle size < 100KB"]
+
+**Error Handling**:
+- [How errors are caught and handled]
+- [User-facing vs internal errors]
+- [Retry/fallback strategies]
+
+**Gotchas**:
+- [Edge case or common mistake]
+- [Thing to watch out for]
+
+**Open Questions**:
+- [ ] [Blocking question]
+- [ ] [Needs research]
+
+## References (if applicable)
+
+- [ADR-XXX: Related decision]
+- [External docs or examples]
+- [Proof of concept]

package/.safeword/templates/test-definitions-feature.md

@@ -0,0 +1,100 @@
+# Test Definitions: [Feature Name] (Issue #[number])
+
+**Guide**: `@./.safeword/guides/test-definitions-guide.md` - Structure, status tracking, and TDD workflow
+**Template**: `@./.safeword/templates/test-definitions-feature.md`
+
+**Feature**: [Brief description of the feature]
+
+**Related Issue**: #[number]
+**Test File**: `[path/to/test.spec.ts]`
+**Total Tests**: [N] ([X] passing, [Y] skipped, [Z] not implemented)
+
+---
+
+## Test Suite [N]: [Suite Name]
+
+[Brief description of what this test suite covers]
+
+### Test [N.1]: [Test name] [✅/⏭️/❌]
+**Status**: [✅ Passing / ⏭️ Skipped / ❌ Not Implemented / 🔴 Failing]
+**Description**: [What this test verifies]
+
+**Steps**:
+1. [Action 1]
+2. [Action 2]
+3. [Action 3]
+
+**Expected**:
+- [Expected outcome 1]
+- [Expected outcome 2]
+- [Expected outcome 3]
+
+---
+
+### Test [N.2]: [Test name] [✅/⏭️/❌]
+**Status**: [✅ Passing / ⏭️ Skipped / ❌ Not Implemented / 🔴 Failing]
+**Description**: [What this test verifies]
+
+**Steps**:
+1. [Action 1]
+2. [Action 2]
+
+**Expected**:
+- [Expected outcome 1]
+- [Expected outcome 2]
+
+---
+
+## Test Suite [N+1]: [Suite Name]
+
+[Brief description of what this test suite covers]
+
+### Test [N+1.1]: [Test name] [✅/⏭️/❌]
+**Status**: [✅ Passing / ⏭️ Skipped / ❌ Not Implemented / 🔴 Failing]
+**Description**: [What this test verifies]
+
+**Steps**:
+1. [Action 1]
+2. [Action 2]
+
+**Expected**:
+- [Expected outcome 1]
+
+---
+
+## Summary
+
+**Total**: [N] tests
+**Passing**: [X] tests ([X]%)
+**Skipped**: [Y] tests ([Y]%)
+**Not Implemented**: [Z] tests ([Z]%)
+**Failing**: [F] tests ([F]%)
+
+### Coverage by Feature
+
+| Feature | Tests | Status |
+|---------|-------|--------|
+| [Feature 1] | [X]/[N] | [✅/❌] [X]% |
+| [Feature 2] | [X]/[N] | [✅/❌] [X]% |
+| [Feature 3] | [X]/[N] | [✅/❌] [X]% |
+
+### Skipped Tests Rationale
+
+1. **Test [N.X]** ([Test name]): [Reason for skipping - e.g., conflicts with design decision, requires manual testing, etc.]
+2. **Test [N.Y]** ([Test name]): [Reason for skipping]
+
+---
+
+## Test Execution
+
+```bash
+# Run all tests for this feature
+[command to run all tests]
+
+# Run specific test
+[command to run specific test with --grep flag]
+```
+
+---
+
+**Last Updated**: [YYYY-MM-DD]

package/.safeword/templates/ticket-template.md

@@ -0,0 +1,74 @@
+---
+id: XXX
+status: in_progress
+created: YYYY-MM-DDTHH:MM:SSZ
+last_modified: YYYY-MM-DDTHH:MM:SSZ
+---
+
+# Title
+
+**Goal:** {One sentence: what are we trying to achieve?}
+
+**Why:** {One sentence: why does this matter?}
+
+## Work Log
+
+**Purpose:** Track what you've tried so you don't repeat dead ends or lose context.
+
+**CRITICAL: Re-read this ticket before each significant action to stay on track.**
+
+**Log immediately after:**
+- Starting work
+- Completing a step
+- Trying an approach (document result: success or failure)
+- Discovering a blocker, tradeoff, or decision point
+- Writing a test (RED) or making it pass (GREEN)
+- Committing code
+
+**Format:** `YYYY-MM-DDTHH:MM:SSZ Action: Description (refs: commit/file/PR)`
+
+**Examples:**
+```
+- 2025-11-24T18:50:00Z Started: Changing button background to red
+- 2025-11-24T18:51:30Z Tried: Added `background: red` to Button.css
+- 2025-11-24T18:52:00Z Found: Button now has white text on red (unreadable)
+- 2025-11-24T18:53:00Z Tried: Changed text color to white
+- 2025-11-24T18:54:15Z Found: Hover state still blue (conflicts)
+- 2025-11-24T18:55:00Z Complete: Updated all button states to red theme (refs: commit 9a3f2c1)
+```
+
+---
+
+{Keep work log in reverse-chronological order. Newest entries at top.}
+{Re-read before each action. Check what you've tried. Stay aligned with Goal.}
+
+---
+
+## Optional Sections (Add When Needed)
+
+### Planning Docs
+{Only for complex features that need user stories, test definitions, design docs}
+
+- .safeword/planning/user-stories/XXX-feature-name.md
+- .safeword/planning/test-definitions/XXX-feature-name.md
+- .safeword/planning/design/XXX-feature-name.md
+
+### Scope
+{Only for complex features with unclear boundaries}
+
+**In scope:**
+- 
+
+**Out of scope:**
+- 
+
+### Acceptance Criteria
+{Only for features or complex bugs where "done" isn't obvious}
+
+- [ ] 
+- [ ] 
+
+### Root Cause
+{Only for bugs that required investigation}
+
+{What caused this issue? Document for future reference.}

package/.safeword/templates/user-stories-template.md

@@ -0,0 +1,82 @@
+# User Stories: [Feature Name] (Issue #[number])
+
+**Guide**: `@./.safeword/guides/user-story-guide.md` - Best practices, INVEST criteria, and examples
+**Template**: `@./.safeword/templates/user-stories-template.md`
+
+**Feature**: [Brief description of the feature]
+
+**Related Issue**: #[number]
+**Status**: [🚧 In Progress / ✅ Complete / ❌ Not Started] ([X/Y] stories complete)
+
+---
+
+## Technical Constraints
+
+_Non-functional requirements that inform test definitions. Delete sections that don't apply._
+
+### Performance
+- [ ] [e.g., Response time < 200ms at P95]
+
+### Security
+- [ ] [e.g., All inputs validated/sanitized]
+
+### Compatibility
+- [ ] [e.g., Chrome 100+, Safari 16+]
+
+### Data
+- [ ] [e.g., GDPR: user data deletable within 72h]
+
+### Dependencies
+- [ ] [e.g., Must use existing AuthService]
+
+### Infrastructure
+- [ ] [e.g., Memory usage < 512MB]
+
+---
+
+## Story [N]: [Story Title]
+
+**As a** [role]
+**I want to** [capability]
+**So that** [value]
+
+**Acceptance Criteria**:
+- [✅/❌] [criterion 1]
+- [✅/❌] [criterion 2]
+- [✅/❌] [criterion 3]
+
+**Implementation Status**: [✅ Complete / 🚧 In Progress / ❌ Not Started]
+**Tests**: [test file path and line numbers]
+
+**Notes**: [Optional: design decisions, scope clarifications, or open questions]
+
+---
+
+## Story [N+1]: [Story Title]
+
+**As a** [role]
+**I want to** [capability]
+**So that** [value]
+
+**Acceptance Criteria**:
+- [✅/❌] [criterion 1]
+- [✅/❌] [criterion 2]
+
+**Implementation Status**: [✅ Complete / 🚧 In Progress / ❌ Not Started]
+**Tests**: [test file path]
+
+---
+
+## Summary
+
+**Completed**: [N]/[M] stories ([X]%)
+**Remaining**: [N]/[M] stories ([X]%)
+
+### [Phase Name]: [Description] [✅/❌]
+- Story N: [Description]
+- Story N+1: [Description]
+
+### [Phase Name]: [Description] [✅/❌]
+- Story N+2: [Description]
+
+**Next Steps**: [What needs to be done next to complete the feature]

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

@@ -0,0 +1,83 @@
+---
+id: 001
+status: in_progress
+created: 2025-11-25T00:00:00Z
+priority: medium
+planning_refs:
+  - .safeword/planning/user-stories/001-guides-review-user-stories.md
+---
+
+# Guides Review and User Story Extraction
+
+## Description
+
+Review every guide under `framework/guides/` and extract actionable user stories for each distinct concept. Centralize all extracted stories in the linked planning doc for follow-up refinement and prioritization.
+
+## Scope
+
+- Files in scope:
+  - `framework/guides/architecture-guide.md`
+  - `framework/guides/code-philosophy.md`
+  - `framework/guides/context-files-guide.md`
+  - `framework/guides/data-architecture-guide.md`
+  - `framework/guides/design-doc-guide.md`
+  - `framework/guides/learning-extraction.md`
+  - `framework/guides/llm-instruction-design.md`
+  - `framework/guides/llm-prompting.md`
+  - `framework/guides/tdd-templates.md`
+  - `framework/guides/test-definitions-guide.md`
+  - `framework/guides/testing-methodology.md`
+  - `framework/guides/user-story-guide.md`
+  - `framework/guides/zombie-process-cleanup.md`
+
+## Checklist (per-guide)
+
+- [x] architecture-guide.md reviewed, stories extracted
+- [x] code-philosophy.md reviewed, stories extracted
+- [x] context-files-guide.md reviewed, stories extracted
+- [x] data-architecture-guide.md reviewed, stories extracted
+- [x] design-doc-guide.md reviewed, stories extracted
+- [x] learning-extraction.md reviewed, stories extracted
+- [x] llm-instruction-design.md reviewed, stories extracted
+- [x] llm-prompting.md reviewed, stories extracted
+- [x] tdd-templates.md reviewed, stories extracted
+- [x] test-definitions-guide.md reviewed, stories extracted
+- [x] testing-methodology.md reviewed, stories extracted
+- [x] user-story-guide.md reviewed, stories extracted
+- [x] zombie-process-cleanup.md reviewed, stories extracted
+
+## Acceptance Criteria
+
+- [ ] All guides reviewed and checklist completed
+- [ ] Extracted user stories recorded in `.safeword/planning/user-stories/001-guides-review-user-stories.md`
+- [ ] Duplicates consolidated; names and phrasing consistent
+- [ ] Summary section added to this ticket linking to key story groups
+
+## Summary of Extracted Story Groups
+
+All extracted user stories are consolidated in:
+
+- `.safeword/planning/user-stories/001-guides-review-user-stories.md`
+
+Covered guides and sections:
+
+- Architecture & Design Documentation Guide
+- Code Philosophy & Practices
+- Project Context Files (AGENTS/CLAUDE/CURSOR)
+- Data Architecture Documentation Guide
+- Design Doc Guide
+- Learning Extraction Process
+- LLM Instruction Design
+- LLM Prompting Best Practices
+- TDD Templates & Best Practices
+- Test Definitions Guide
+- Testing Methodology
+- User Story Guide
+- Zombie Process Cleanup
+
+## Work Log
+
+- Created ticket and linked planning doc.
+- Extracted stories from code-philosophy.md and architecture-guide.md; updated planning doc and checklist.
+- Extracted stories from learning-extraction.md, context-files-guide.md, data-architecture-guide.md, design-doc-guide.md; updated planning doc and checklist.
+- Completed extraction for llm-instruction-design.md, llm-prompting.md, tdd-templates.md, test-definitions-guide.md, testing-methodology.md, user-story-guide.md, zombie-process-cleanup.md.