safeword 0.6.9 → 0.7.1

package/templates/SAFEWORD.md

@@ -69,6 +69,7 @@ Training data is stale. Follow this sequence:
 | Trigger                                                    | Template                                           |
 | ---------------------------------------------------------- | -------------------------------------------------- |
 | User asks for user story OR planning new feature scope     | @./.safeword/templates/user-stories-template.md    |
+| Bug, improvement, refactor, or internal task               | @./.safeword/templates/task-spec-template.md       |
 | Need test definitions for a feature OR acceptance criteria | @./.safeword/templates/test-definitions-feature.md |
 | Feature spans 3+ components OR needs technical spec        | @./.safeword/templates/design-doc-template.md      |
 | Making decision with long-term impact OR trade-offs        | @./.safeword/templates/architecture-template.md    |
@@ -80,12 +81,20 @@ Training data is stale. Follow this sequence:
 
 **Location:** `.safeword/planning/` at project root
 
-| Type             | Path                                   |
-| ---------------- | -------------------------------------- |
-| User stories     | `.safeword/planning/user-stories/`     |
-| Test definitions | `.safeword/planning/test-definitions/` |
-| Design docs      | `.safeword/planning/design/`           |
-| Issues           | `.safeword/planning/issues/`           |
+| Type             | Path                                   | Contents                          |
+| ---------------- | -------------------------------------- | --------------------------------- |
+| Specs            | `.safeword/planning/specs/`            | `feature-*.md` and `task-*.md`    |
+| Test definitions | `.safeword/planning/test-definitions/` | `feature-*.md` (L2 features only) |
+| Design docs      | `.safeword/planning/design/`           | Complex features (3+ components)  |
+| Issues           | `.safeword/planning/issues/`           | Issue tracking                    |
+
+**Artifact Levels:**
+
+| Level  | Artifacts                                            | Test Location       |
+| ------ | ---------------------------------------------------- | ------------------- |
+| **L2** | Feature Spec + Test Definitions (+ Design Doc if 3+) | `test-definitions/` |
+| **L1** | Task Spec                                            | Inline in spec      |
+| **L0** | Task Spec (minimal)                                  | Existing tests      |
 
 **Archive:** Move completed docs to `archive/` subfolder within each.
 
@@ -136,22 +145,31 @@ status: in_progress
 
 ## Feature Development
 
-**Follow this order:**
+**Triage first - answer IN ORDER, stop at first match:**
+
+| Question                                 | Level          | Artifacts                    |
+| ---------------------------------------- | -------------- | ---------------------------- |
+| User-facing feature with business value? | **L2 Feature** | Spec + Test Defs (+ Design)  |
+| Bug, improvement, internal, or refactor? | **L1 Task**    | Spec with inline tests       |
+| Typo, config, or trivial change?         | **L0 Micro**   | Minimal spec, existing tests |
+
+**Then follow this order:**
 
 1. **Check/create ticket** if context-loss risk exists (see decision tree above)
-2. **Read user stories** (`.safeword/planning/user-stories/`)
-3. **Read test definitions** (`.safeword/planning/test-definitions/`)
-4. **Read design doc** if complex (>3 components OR 2+ user stories)
+2. **Read/create spec** (`.safeword/planning/specs/`)
+3. **Read/create test definitions** (L2 only: `.safeword/planning/test-definitions/`)
+4. **Read/create design doc** if complex (3+ components)
 5. **TDD: RED → GREEN → REFACTOR**
 6. **Update ticket** with progress, ask user to confirm completion
 
 **Edge cases:**
 
-| Situation                           | Action                            |
-| ----------------------------------- | --------------------------------- |
-| User stories exist, test defs don't | Create test defs first            |
-| Test defs exist, user stories don't | Ask if user stories needed        |
-| Neither exist                       | Create both before implementation |
+| Situation                 | Action                  |
+| ------------------------- | ----------------------- |
+| Spec exists, no test defs | Create test defs (L2)   |
+| Test defs exist, no spec  | Create spec first       |
+| Neither exist             | Create spec, then tests |
+| L0/L1 task                | Inline tests in spec    |
 
 ---
 
@@ -207,6 +225,25 @@ Commit after: GREEN phase, before/after refactoring, when switching tasks.
 
 ---
 
+## Code Fence Languages (MD040)
+
+When markdown lint reports MD040 (missing language), choose:
+
+| Content Type             | Language Hint                |
+| ------------------------ | ---------------------------- |
+| TypeScript/JavaScript    | `typescript` or `javascript` |
+| Shell commands           | `bash`                       |
+| JSON, YAML, TOML configs | `json`, `yaml`, `toml`       |
+| SQL queries              | `sql`                        |
+| Directory trees          | `plaintext`                  |
+| Templates, pseudocode    | `text`                       |
+| Command output, logs     | `text`                       |
+| Truly ambiguous          | `text`                       |
+
+**Why this matters:** Language hints help LLMs understand code context. Use real languages for real code, `text` for everything else.
+
+---
+
 ## Learning Extraction
 
 **Suggest extraction when ANY apply:**

package/templates/commands/architecture.md

@@ -20,7 +20,7 @@ When the user invokes this command:
 
 ## Example Usage
 
-```
+```text
 /architecture
 ```
 

package/templates/commands/lint.md

@@ -27,6 +27,7 @@ npm run lint:md 2>&1 || true
 ## Summary
 
 After running, report:
+
 1. Any ESLint errors that couldn't be auto-fixed
 2. Any formatting issues
 3. Type errors (if TypeScript)

package/templates/commands/quality-review.md

@@ -23,7 +23,7 @@ When the user invokes this command:
 
 ## Example Usage
 
-```
+```text
 /quality-review
 ```
 

package/templates/cursor/rules/safeword-core.mdc

@@ -0,0 +1,5 @@
+---
+alwaysApply: true
+---
+
+@.safeword/SAFEWORD.md

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

@@ -76,7 +76,7 @@ Boundaries enforced via `eslint-plugin-boundaries`. See `.safeword/guides/archit
 
 ### Relationships
 
-```
+```text
 [Entity A] 1──n [Entity B]
 [Entity B] n──n [Entity C]
 ```

package/templates/doc-templates/task-spec-template.md

@@ -0,0 +1,151 @@
+# Task: [Name]
+
+**Guide**: `@./.safeword/guides/development-workflow.md`
+**Template**: `@./.safeword/templates/task-spec-template.md`
+
+---
+
+## Standard Task (L1)
+
+Use for: bugs, improvements, internal work, refactors.
+
+```markdown
+# Task: [Name]
+
+**Type:** Bug | Improvement | Internal | Refactor
+
+**Scope:** [1-2 sentences describing what this task accomplishes]
+
+**Out of Scope:** [Explicit boundaries - what this task does NOT include]
+
+**Done When:**
+
+- [ ] [Observable outcome 1]
+- [ ] [Observable outcome 2]
+
+**Tests:**
+
+- [ ] [Test scenario 1 - what behavior to verify]
+- [ ] [Test scenario 2 - edge case or secondary behavior]
+```
+
+**Location:** `.safeword/planning/specs/task-[name].md`
+
+---
+
+## Micro Task (L0)
+
+Use for: typos, config changes, trivial fixes. Still scoped to prevent creep.
+
+```markdown
+# Task: [Name]
+
+**Type:** Micro
+
+**Scope:** [One sentence - exactly what is changing]
+
+**Out of Scope:** [Boundaries - prevents "while I'm here" expansion]
+
+**Done When:**
+
+- [ ] [Single observable outcome]
+
+**Tests:**
+
+- [ ] Existing tests pass (no new test needed)
+```
+
+**Location:** `.safeword/planning/specs/task-[name].md`
+
+---
+
+## Examples
+
+### L1: Bug Fix
+
+```markdown
+# Task: Fix login timeout after 30 minutes
+
+**Type:** Bug
+
+**Scope:** Session refresh logic in auth middleware. User stays logged in if active.
+
+**Out of Scope:** Session duration settings, auth flow changes, UI modifications.
+
+**Done When:**
+
+- [ ] User stays logged in if active within session window
+- [ ] Session refreshes on API calls
+
+**Tests:**
+
+- [ ] Unit: session refresh extends expiry timestamp
+- [ ] Unit: inactive session expires correctly after timeout
+```
+
+### L1: Improvement
+
+```markdown
+# Task: Add retry logic to API client
+
+**Type:** Improvement
+
+**Scope:** Add exponential backoff retry for failed API requests in http client.
+
+**Out of Scope:** Circuit breaker, rate limiting, request queuing, UI loading states.
+
+**Done When:**
+
+- [ ] Failed requests retry up to 3 times with exponential backoff
+- [ ] Permanent failures (4xx) do not retry
+
+**Tests:**
+
+- [ ] Unit: retries on 5xx errors with backoff
+- [ ] Unit: does not retry on 4xx errors
+- [ ] Unit: gives up after max retries
+```
+
+### L0: Micro
+
+```markdown
+# Task: Fix typo in auth error message
+
+**Type:** Micro
+
+**Scope:** Typo in login error ("authetication" → "authentication").
+
+**Out of Scope:** Error handling logic, other error messages, refactoring.
+
+**Done When:**
+
+- [ ] Typo fixed in error message string
+
+**Tests:**
+
+- [ ] Existing auth tests pass
+```
+
+---
+
+## Why L0 Needs Scope
+
+Even trivial tasks need boundaries. Without explicit "Out of Scope":
+
+- "Fix typo" becomes "improve all error messages"
+- "Update config" becomes "refactor config system"
+- "Rename variable" becomes "rename all related functions"
+
+The spec takes 30 seconds to write and prevents hours of scope creep.
+
+---
+
+## Relationship to Feature Specs
+
+| Type                  | Use When                                | Artifacts                            |
+| --------------------- | --------------------------------------- | ------------------------------------ |
+| **Feature Spec (L2)** | User-facing feature with business value | Feature spec + test definitions file |
+| **Task Spec (L1)**    | Bug, improvement, internal, refactor    | Task spec with inline tests          |
+| **Task Spec (L0)**    | Typo, config, trivial                   | Minimal task spec, existing tests    |
+
+For L2 features, use: `@./.safeword/templates/user-stories-template.md`

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

@@ -30,7 +30,7 @@ last_modified: YYYY-MM-DDTHH:MM:SSZ
 
 **Examples:**
 
-```
+```text
 - 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)
@@ -62,9 +62,7 @@ last_modified: YYYY-MM-DDTHH:MM:SSZ
 
 **In scope:**
 
--
-
-**Out of scope:**
+- **Out of scope:**
 
 -
 

package/templates/guides/architecture-guide.md

@@ -99,7 +99,7 @@ Answer **IN ORDER**. Stop at the first "Yes":
 
 **✅ GOOD:**
 
-```
+```plaintext
 project/
 ├── ARCHITECTURE.md
 └── docs/design/
@@ -273,7 +273,7 @@ Answer **IN ORDER**:
 
 ## File Organization
 
-```
+```plaintext
 project/
 ├── ARCHITECTURE.md              # Single comprehensive doc
 ├── .safeword/planning/

package/templates/guides/code-philosophy.md

@@ -192,7 +192,7 @@ Before completing any work, verify:
 - Use descriptive commit messages
 - Make atomic commits (one logical change per commit)
 
-```
+```text
 # ❌ Bad: "misc fixes"
 # ✅ Good: "fix: login button not responding to clicks"
 ```

package/templates/guides/context-files-guide.md

@@ -61,7 +61,7 @@ Read it BEFORE working on any task in this project.
 
 **Example:**
 
-```
+```text
 Working in: /project/src/feature/
 Loaded context:
   ✓ /project/CLAUDE.md (Claude-specific guidance)
@@ -96,7 +96,7 @@ See root AGENTS.md for TDD workflow. This file covers test-specific patterns.
 
 ## File Structure Pattern
 
-```
+```plaintext
 project/
 ├─ SAFEWORD.md                  # Project context (references guides)
 ├─ CLAUDE.md                    # Claude-specific context
@@ -106,7 +106,7 @@ project/
 
 **Modular Approach (Recommended):**
 
-```
+```plaintext
 project/
 ├─ AGENTS.md / CLAUDE.md        # 50 lines: imports + structure
 ├─ docs/architecture.md         # 100 lines: architecture decisions

package/templates/guides/design-doc-guide.md

@@ -137,14 +137,14 @@
 
 **Creating design doc:**
 
-```
+```text
 User: "Create design doc for three-pane layout"
 You: [Read user stories and test definitions, then create design doc]
 ```
 
 **Updating design doc:**
 
-```
+```text
 User: "Update design doc to add error handling section"
 You: [Read existing design doc, add Implementation Notes section with error handling]
 ```

package/templates/guides/development-workflow.md

@@ -46,7 +46,7 @@ Tests are the specification. When a test fails, the implementation is wrong—no
 
 ### Test Speed Hierarchy (Fast → Slow)
 
-```
+```text
 Unit (milliseconds)      ← Pure functions, no I/O
   ↓
 Integration (seconds)    ← Multiple modules, database, API calls
@@ -186,7 +186,7 @@ function calculateTotal(amount: number, taxRate: number): number {
 
 Answer these questions in order to choose the test type. Questions are mutually exclusive - stop at the first match. If multiple seem to apply, use the tie-breaking rule (line 19): choose the faster one.
 
-```
+```text
 1. Does this test AI-generated content quality (tone, reasoning, creativity)?
    └─ YES → LLM Evaluation
       Examples: Narrative quality, prompt effectiveness, conversational naturalness

package/templates/guides/learning-extraction.md

@@ -103,7 +103,7 @@ ls ./.safeword/learnings/*keyword*.md
 
 **Found existing learning** → Read and apply it:
 
-```
+```text
 "I found an existing learning about [concept] at [path]. Let me read it and apply to your case..."
 [Read the file]
 "Based on the learning, here's how to handle this: [specific guidance from learning]"
@@ -113,7 +113,7 @@ ls ./.safeword/learnings/*keyword*.md
 
 **Similar but different** → Reference and note difference:
 
-```
+```text
 "This is similar to the [existing learning] at [path], but differs in [specific way].
 The existing learning covers [X], but your case involves [Y]."
 ```
@@ -122,7 +122,7 @@ The existing learning covers [X], but your case involves [Y]."
 
 **Scenario 1: Found relevant learning**
 
-```
+```text
 User: "I'm getting an async state update error with React hooks"
 → Check: ls .safeword/learnings/*react*.md *hooks*.md *async*.md
 → Found: react-hooks-async.md
@@ -133,7 +133,7 @@ User: "I'm getting an async state update error with React hooks"
 
 **Scenario 2: No existing learning**
 
-```
+```text
 User: "IndexedDB quota is behaving strangely in Safari"
 → Check: ls .safeword/learnings/*indexeddb*.md *safari*.md *quota*.md
 → Not found
@@ -142,7 +142,7 @@ User: "IndexedDB quota is behaving strangely in Safari"
 
 **Scenario 3: Update existing learning**
 
-```
+```text
 User: Debugging for 6 cycles, discovers new IndexedDB quirk
 → Suggest extraction
 → Check: ls .safeword/learnings/*indexeddb*.md
@@ -162,7 +162,7 @@ User: Debugging for 6 cycles, discovers new IndexedDB quirk
 
 ## Decision Tree
 
-```
+```text
 Just learned something valuable
 │
 ├─ Forward-looking? (useful on FUTURE work, not just this bug)
@@ -260,7 +260,7 @@ Actual: [What happened]
 
 [One-sentence takeaway]
 
-````
+````text
 
 ---
 
@@ -481,7 +481,7 @@ Project-specific gotchas in `.safeword/learnings/`:
 
 ## Directory Structure
 
-```
+```plaintext
 # Global learnings (all projects)
 .safeword/learnings/
 ├── react-state-async.md
@@ -506,7 +506,7 @@ Project-specific gotchas in `.safeword/learnings/`:
 
 **When to Split**:
 
-```
+```text
 # TOO BIG (250 lines covering 3 separate concepts)
 .safeword/learnings/electron-gotchas.md