safeword 0.2.3 → 0.2.4

package/packages/cli/templates/doc-templates/architecture-template.md

@@ -0,0 +1,136 @@
+# [Project Name] Architecture
+
+**Version:** 1.0  
+**Last Updated:** YYYY-MM-DD  
+**Status:** Design | Production | Proposed | Deprecated
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Layers & Boundaries](#layers--boundaries)
+- [Data Model](#data-model)
+- [Key Decisions](#key-decisions)
+- [Best Practices](#best-practices)
+- [Migration Strategy](#migration-strategy)
+
+---
+
+## Overview
+
+[High-level description of the system architecture, technology choices, and design philosophy.]
+
+### Tech Stack
+
+| Category         | Choice | Rationale |
+| ---------------- | ------ | --------- |
+| Language         |        |           |
+| Framework        |        |           |
+| Database         |        |           |
+| State Management |        |           |
+
+---
+
+## Layers & Boundaries
+
+### 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).
+
+### Boundary Enforcement
+
+Boundaries enforced via `eslint-plugin-boundaries`. See `.safeword/guides/architecture-guide.md` → Enforcement with eslint-plugin-boundaries for setup.
+
+---
+
+## Data Model
+
+### Entities
+
+| Entity | Table/Collection | Description |
+| ------ | ---------------- | ----------- |
+|        |                  |             |
+
+### Relationships
+
+```
+[Entity A] 1──n [Entity B]
+[Entity B] n──n [Entity C]
+```
+
+### Schema Notes
+
+- [Key constraints, indexes, etc.]
+
+---
+
+## Key Decisions
+
+### [Decision Title]
+
+**Status:** Active | Superseded | Deprecated  
+**Date:** YYYY-MM-DD
+
+| Field          | Value                                         |
+| -------------- | --------------------------------------------- |
+| What           | [The decision in 1-2 sentences]               |
+| Why            | [Rationale with specifics - numbers, metrics] |
+| Trade-off      | [What we gave up or accepted]                 |
+| Alternatives   | [Other options considered and why rejected]   |
+| Implementation | [File references: `src/path/file.ts:12-45`]   |
+
+---
+
+## Best Practices
+
+### [Pattern Name]
+
+**What:** [Brief description]  
+**Why:** [Rationale]  
+**Example:** See `src/path/example.ts`
+
+---
+
+## Migration Strategy
+
+### From [Previous State] to [Target State]
+
+**Trigger:** [When to migrate]  
+**Steps:**
+
+1. [Step 1]
+2. [Step 2]
+
+**Rollback:** [How to revert if needed]
+
+---
+
+## Appendix
+
+### References
+
+- [Link to relevant docs]
+- [Link to ADRs if migrating from ADR system]

package/packages/cli/templates/doc-templates/design-doc-template.md

@@ -0,0 +1,134 @@
+# 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/packages/cli/templates/doc-templates/test-definitions-feature.md

@@ -0,0 +1,131 @@
+# 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]
+
+---
+
+## Test Suite [N]: Technical Constraints
+
+_Tests for non-functional requirements from user story Technical Constraints section. Add tests for each applicable category: Performance, Security, Compatibility, Data, Dependencies, Infrastructure. Delete this suite if no constraints apply._
+
+### Test [N.1]: [Constraint name] [✅/⏭️/❌]
+
+**Status**: [✅ Passing / ⏭️ Skipped / ❌ Not Implemented / 🔴 Failing]
+**Category**: [Performance / Security / Compatibility / Data / Dependencies / Infrastructure]
+**Constraint**: [Copy exact constraint from user story, e.g., "API response < 200ms at P95"]
+
+**Steps**:
+
+1. [Setup test conditions]
+2. [Execute operation]
+3. [Measure/verify result]
+
+**Expected**:
+
+- [Measurable outcome matching constraint]
+
+---
+
+## 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/packages/cli/templates/doc-templates/ticket-template.md

@@ -0,0 +1,82 @@
+---
+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/packages/cli/templates/doc-templates/user-stories-template.md

@@ -0,0 +1,92 @@
+# 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]