safeword 0.6.9 → 0.7.1

package/templates/guides/tdd-best-practices.md

@@ -82,7 +82,7 @@ Patterns and examples for user stories and test definitions following TDD best p
 
 ### Standard Format (Recommended)
 
-```
+````text
 As a [role/persona]
 I want [capability/feature]
 So that [business value/benefit]
@@ -94,44 +94,44 @@ Acceptance Criteria:
 
 Out of Scope:
 - [What this story explicitly does NOT include]
-```
+```text
 
 ### Given-When-Then Format (Behavior-Focused)
 
-```
+```text
 Given [initial context/state]
 When [action/event occurs]
 Then [expected outcome]
 
 And [additional context/outcome]
 But [exception/edge case]
-```
+```text
 
 **Filled example:**
 
-```
+```text
 Given I am an authenticated API user
 When I POST to /api/campaigns with valid JSON
 Then I receive a 201 Created response with campaign ID
 And the campaign appears in my GET /api/campaigns list
 But invalid JSON returns 400 with descriptive error messages
-```
+```text
 
 ### Job Story Format (Outcome-Focused)
 
-```
+```text
 When [situation/context]
 I want to [motivation/job-to-be-done]
 So I can [expected outcome]
-```
+```text
 
 **Filled example:**
 
-```
+```text
 When I'm debugging a failing test
 I want to see the exact LLM prompt and response
 So I can identify whether the issue is prompt engineering or code logic
-```
+```text
 
 ---
 
@@ -141,7 +141,7 @@ So I can identify whether the issue is prompt engineering or code logic
 
 **Web App Feature:**
 
-```
+```text
 As a user with multiple campaigns
 I want to switch between campaigns without reloading the page
 So that I can quickly compare game states
@@ -155,21 +155,21 @@ Acceptance Criteria:
 Out of Scope:
 - Campaign merging/deletion (separate story)
 - Multi-campaign view (future epic)
-```
+```text
 
 **API Feature:**
 
-```
+```text
 Given I am an authenticated API user
 When I POST to /api/campaigns with valid JSON
 Then I receive a 201 Created response with campaign ID
 And the campaign appears in my GET /api/campaigns list
 But invalid JSON returns 400 with descriptive error messages
-```
+```text
 
 **CLI Feature:**
 
-```
+```text
 When I'm debugging a failing test
 I want to see the exact LLM prompt and response
 So I can identify whether the issue is prompt engineering or code logic
@@ -179,11 +179,11 @@ Acceptance Criteria:
 - Response JSON is pretty-printed with syntax highlighting
 - Token count and cost are displayed
 - Works with all agent types (rules, narrative, character)
-```
+```text
 
 **With Technical Constraints:**
 
-```
+```text
 As a user with multiple campaigns
 I want to switch between campaigns without reloading the page
 So that I can quickly compare game states
@@ -203,17 +203,17 @@ Compatibility:
 
 Data:
 - [ ] Campaign data persists across browser sessions
-```
+```text
 
 ### ❌ BAD Examples (Anti-Patterns)
 
 **Too Vague:**
 
-```
+```text
 As a user
 I want the app to work better
 So that I'm happy
-```
+```text
 
 - ❌ No specific role
 - ❌ "Work better" is not measurable
@@ -221,11 +221,11 @@ So that I'm happy
 
 **Too Technical (Implementation Details):**
 
-```
+```text
 As a developer
 I want to refactor the CharacterStore to use Immer
 So that state mutations are prevented
-```
+```text
 
 - ❌ This is a technical task, not a user story
 - ❌ Users don't care about Immer
@@ -233,21 +233,21 @@ So that state mutations are prevented
 
 **Missing "So That" (No Value):**
 
-```
+```text
 As a GM
 I want to roll dice
-```
+```text
 
 - ❌ No business value stated
 - ❌ Why does the GM need this?
 
 **Multiple Features in One Story:**
 
-```
+```text
 As a player
 I want to create characters, manage inventory, and track relationships
 So that I can play the game
-```
+```text
 
 - ❌ 3+ separate features bundled together
 - ❌ Cannot be completed in one sprint
@@ -291,7 +291,7 @@ describe('[Unit/Module Name]', () => {
     });
   });
 });
-```
+```text
 
 ### Integration Test Template
 
@@ -342,7 +342,7 @@ describe('[Feature Name] Integration', () => {
     expect(await getInventory('sword')).toBe(1); // Not decremented
   });
 });
-```
+```text
 
 ### E2E Test Template (Playwright/Cypress)
 
@@ -368,7 +368,7 @@ test.describe('[User Journey Name]', () => {
     await expect(page).toHaveURL(/\/characters\/create/);
   });
 });
-```
+```text
 
 ---
 
@@ -383,7 +383,7 @@ it('should return risky position when outnumbered 3-to-1');
 it('should cache LLM responses for 5 minutes to reduce costs');
 it('should preserve armor state after reducing harm from L2 to L1');
 it('should throw ValidationError when dice pool is negative');
-```
+```text
 
 **❌ BAD - Vague or Implementation-Focused:**
 
@@ -392,7 +392,7 @@ it('works correctly'); // What does "correctly" mean?
 it('tests the function'); // Obvious, not descriptive
 it('should call setState'); // Implementation detail
 it('scenario 1'); // No context
-```
+```text
 
 **How to rename:**
 
@@ -418,7 +418,7 @@ it('should calculate critical success on 6', () => {
   expect(outcome).toBe('critical');
   expect(outcome.highestDie).toBe(6);
 });
-```
+```text
 
 ### Test Independence
 
@@ -436,7 +436,7 @@ it('test A', () => {
 it('test B', () => {
   /* uses separate gameState */
 });
-```
+```text
 
 **❌ BAD - Shared State:**
 
@@ -448,7 +448,7 @@ it('test A', () => {
 it('test B', () => {
   expect(sharedState.foo).toBe('bar');
 }); // Depends on test A!
-```
+```text
 
 ### What to Test
 
@@ -480,7 +480,7 @@ export function getFormattedTimestamp(event) {
   return _formatDateInternal(event.createdAt);
 }
 // Test getFormattedTimestamp, not _formatDateInternal
-```
+```text
 
 ### Test Data Builders
 
@@ -504,7 +504,7 @@ it('should increase stress when resisting', () => {
   const character = buildCharacter({ stress: 3 });
   // Test uses character with stress=3
 });
-```
+```text
 
 ---
 
@@ -547,7 +547,7 @@ tests:
           EXCELLENT: Asks open-ended questions, invites player creativity
           ACCEPTABLE: Acknowledges player action, minimal collaboration
           POOR: Dictates outcomes without player input
-```
+```text
 
 ### Integration Test with Real LLM
 
@@ -570,7 +570,7 @@ describe('Rules Agent Integration', () => {
     expect(response.consequences).toContain('severe harm');
   });
 });
-```
+```text
 
 ---
 
@@ -613,3 +613,4 @@ Before writing a story, verify it passes all six criteria:
 - **Unit:** Single function/module logic (fast, cheap, low-level confidence)
 
 **Ratio guidance:** 70% unit, 20% integration, 10% E2E (adjust based on project)
+````

package/templates/guides/test-definitions-guide.md

@@ -61,21 +61,21 @@ Use these consistently:
 
 **✅ GOOD - Clear, actionable steps:**
 
-```
+````text
 **Steps**:
 1. Toggle AI pane visible
 2. Get bounding box for AI pane
 3. Get bounding box for Editor pane
 4. Compare X coordinates
-```
+```text
 
 **❌ BAD - Vague or incomplete:**
 
-```
+```text
 **Steps**:
 1. Check panes
 2. Verify order
-```
+```text
 
 ---
 
@@ -83,20 +83,20 @@ Use these consistently:
 
 **✅ GOOD - Specific, testable assertions:**
 
-```
+```text
 **Expected**:
 - AI pane X coordinate < Editor pane X coordinate
 - Explorer pane X coordinate > Editor pane X coordinate
 - All coordinates are positive numbers
-```
+```text
 
 **❌ BAD - Vague expectations:**
 
-```
+```text
 **Expected**:
 - Panes are in correct order
 - Everything works
-```
+```text
 
 ---
 
@@ -131,13 +131,13 @@ Use these consistently:
 
 **Example:**
 
-```
+```text
 **Total**: 20 tests
 **Passing**: 9 tests (45%)
 **Skipped**: 4 tests (20%)
 **Not Implemented**: 7 tests (35%)
 **Failing**: 0 tests
-```
+```text
 
 ---
 
@@ -169,7 +169,7 @@ npm run test:e2e -- tests/feature-name.spec.ts
 
 # Run specific test
 npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
-```
+```text
 
 ---
 
@@ -246,7 +246,7 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 - P95 response time < 200ms
 - No requests timeout
 - No 5xx errors under load
-```
+```text
 
 **❌ BAD - Vague, untestable:**
 
@@ -255,7 +255,7 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 
 **Steps**: Check if fast
 **Expected**: Good performance
-```
+```text
 
 ### When to Skip Constraint Tests
 
@@ -291,7 +291,7 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 - After first toggle: AI pane visible
 - After second toggle: AI pane hidden
 - Toggle action triggers state change in uiStore
-```
+```text
 
 ---
 
@@ -332,3 +332,4 @@ npm run test:e2e -- tests/feature-name.spec.ts --grep "specific test name"
 - Concrete examples over abstract rules
 - Edge cases must be explicit
 - Actionable over vague language
+````

package/templates/hooks/cursor/after-file-edit.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# Safeword: Cursor adapter for afterFileEdit
+# Auto-lints changed files, only outputs unfixable errors
+# Sets marker file for stop hook to trigger quality review
+
+# Require jq for JSON parsing
+command -v jq &> /dev/null || exit 0
+
+input=$(cat)
+
+# Get workspace root and file path from Cursor's JSON format
+workspace=$(echo "$input" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+file=$(echo "$input" | jq -r '.file_path // empty' 2>/dev/null)
+conv_id=$(echo "$input" | jq -r '.conversation_id // "default"' 2>/dev/null)
+
+# Exit silently if no file
+[ -z "$file" ] || [ ! -f "$file" ] && exit 0
+
+# Change to workspace directory
+[ -n "$workspace" ] && cd "$workspace" || true
+
+# Check for .safeword directory
+if [ ! -d ".safeword" ]; then
+  exit 0
+fi
+
+# Set marker file for stop hook to know edits were made
+touch "/tmp/safeword-cursor-edited-${conv_id}"
+
+# Determine linter based on file extension
+case "$file" in
+  # JS/TS and framework files - ESLint first (fix code), then Prettier (format)
+  *.js|*.jsx|*.ts|*.tsx|*.mjs|*.mts|*.cjs|*.cts|*.vue|*.svelte|*.astro)
+    if ! errors=$(npx eslint --fix "$file" 2>&1); then
+      [ -n "$errors" ] && echo "$errors"
+    fi
+    npx prettier --write "$file" 2>/dev/null
+    ;;
+
+  # Markdown - markdownlint first, then Prettier
+  *.md)
+    if ! errors=$(npx markdownlint-cli2 --fix "$file" 2>&1); then
+      [ -n "$errors" ] && echo "$errors"
+    fi
+    npx prettier --write "$file" 2>/dev/null
+    ;;
+
+  # Other supported formats - prettier only
+  *.json|*.css|*.scss|*.html|*.yaml|*.yml|*.graphql)
+    npx prettier --write "$file" 2>/dev/null
+    ;;
+
+  # Shell scripts - shellcheck (if available), then Prettier (if plugin installed)
+  *.sh)
+    if [ -f node_modules/.bin/shellcheck ] || command -v shellcheck &> /dev/null; then
+      if ! errors=$(npx shellcheck "$file" 2>&1); then
+        [ -n "$errors" ] && echo "$errors"
+      fi
+    fi
+    if [ -d node_modules/prettier-plugin-sh ]; then
+      npx prettier --write "$file" 2>/dev/null
+    fi
+    ;;
+esac
+
+exit 0

package/templates/hooks/cursor/stop.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Safeword: Cursor adapter for stop hook
+# Checks for marker file from afterFileEdit to determine if files were modified
+# Uses followup_message to inject quality review prompt into conversation
+
+# Require jq for JSON parsing
+command -v jq &> /dev/null || { echo '{}'; exit 0; }
+
+input=$(cat)
+
+# Get workspace root
+workspace=$(echo "$input" | jq -r '.workspace_roots[0] // empty' 2>/dev/null)
+[ -n "$workspace" ] && cd "$workspace" || true
+
+# Check for .safeword directory
+if [ ! -d ".safeword" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Check status - only proceed on completed (not aborted/error)
+status=$(echo "$input" | jq -r '.status // empty' 2>/dev/null)
+if [ "$status" != "completed" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Get loop_count to prevent infinite review loops
+# When review is triggered, agent runs again with loop_count >= 1
+loop_count=$(echo "$input" | jq -r '.loop_count // 0' 2>/dev/null)
+
+if [ "$loop_count" -ge 1 ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Check if any file edits occurred in this session by looking for recent .safeword marker
+# This is a heuristic: if afterFileEdit ran recently, work was done
+marker_file="/tmp/safeword-cursor-edited-$(echo "$input" | jq -r '.conversation_id // "default"' 2>/dev/null)"
+
+if [ -f "$marker_file" ]; then
+  rm -f "$marker_file"  # Clean up marker
+  cat << 'EOF'
+{
+  "followup_message": "SAFEWORD Quality Review:\n\nDouble check and critique your work again just in case.\nAssume you've never seen it before.\n\n- Is it correct?\n- Is it elegant?\n- Does it follow latest docs/best practices?\n- Ask me any non-obvious questions.\n- Avoid bloat."
+}
+EOF
+else
+  echo '{}'
+fi

package/templates/hooks/post-tool-lint.sh

@@ -18,21 +18,23 @@ file=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.notebook_path
 [ -z "$file" ] || [ ! -f "$file" ] && exit 0
 
 # Change to project directory
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 # Determine linter based on file extension
 case "$file" in
   # JS/TS and framework files - ESLint first (fix code), then Prettier (format)
   *.js|*.jsx|*.ts|*.tsx|*.mjs|*.mts|*.cjs|*.cts|*.vue|*.svelte|*.astro)
-    errors=$(npx eslint --fix "$file" 2>&1)
-    [ $? -ne 0 ] && [ -n "$errors" ] && echo "$errors"
+    if ! errors=$(npx eslint --fix "$file" 2>&1); then
+      [ -n "$errors" ] && echo "$errors"
+    fi
     npx prettier --write "$file" 2>/dev/null
     ;;
 
   # Markdown - markdownlint first, then Prettier
   *.md)
-    errors=$(npx markdownlint-cli2 --fix "$file" 2>&1)
-    [ $? -ne 0 ] && [ -n "$errors" ] && echo "$errors"
+    if ! errors=$(npx markdownlint-cli2 --fix "$file" 2>&1); then
+      [ -n "$errors" ] && echo "$errors"
+    fi
     npx prettier --write "$file" 2>/dev/null
     ;;
 
@@ -40,6 +42,18 @@ case "$file" in
   *.json|*.css|*.scss|*.html|*.yaml|*.yml|*.graphql)
     npx prettier --write "$file" 2>/dev/null
     ;;
+
+  # Shell scripts - shellcheck (if available), then Prettier (if plugin installed)
+  *.sh)
+    if [ -f node_modules/.bin/shellcheck ] || command -v shellcheck &> /dev/null; then
+      if ! errors=$(npx shellcheck "$file" 2>&1); then
+        [ -n "$errors" ] && echo "$errors"
+      fi
+    fi
+    if [ -d node_modules/prettier-plugin-sh ]; then
+      npx prettier --write "$file" 2>/dev/null
+    fi
+    ;;
 esac
 
 exit 0

package/templates/hooks/prompt-questions.sh

@@ -3,7 +3,7 @@
 # Reminds Claude to ask 1-5 clarifying questions for ambiguous tasks
 
 # Change to project directory if set
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 if [ ! -d ".safeword" ]; then
   exit 0

package/templates/hooks/session-lint-check.sh

@@ -3,7 +3,7 @@
 # Warns if ESLint or Prettier configs are missing or out of sync
 
 # Change to project directory if set
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 if [ ! -d ".safeword" ]; then
   exit 0

package/templates/hooks/session-verify-agents.sh

@@ -5,7 +5,7 @@
 LINK='**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**'
 
 # Change to project directory if set
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 if [ ! -d ".safeword" ]; then
   # Not a safeword project, skip silently

package/templates/hooks/session-version.sh

@@ -3,7 +3,7 @@
 # Shows current safeword version and confirms hooks are active
 
 # Change to project directory if set
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 if [ ! -d ".safeword" ]; then
   exit 0

package/templates/hooks/stop-quality.sh

@@ -5,7 +5,7 @@
 # Looks for {"proposedChanges": ..., "madeChanges": ...} JSON blob
 
 # Change to project directory if set
-[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR"
+[ -n "$CLAUDE_PROJECT_DIR" ] && cd "$CLAUDE_PROJECT_DIR" || true
 
 # Check for .safeword directory
 if [ ! -d ".safeword" ]; then

package/templates/markdownlint-cli2.jsonc

@@ -1,25 +1,24 @@
 {
   // Safeword markdownlint configuration
-  "default": true,
+  // Philosophy: Only enforce rules that affect rendering or LLM comprehension
+  // Cosmetic/stylistic rules disabled - LLMs don't care about line length or bullet style
+  "config": {
+    "default": false,
 
-  // Allow inline HTML (needed for some markdown features)
-  "MD033": false,
+    // RENDERING-CRITICAL (broken markdown if violated)
+    "MD011": true, // Reversed link syntax [text](url) not (text)[url]
+    "MD018": true, // Space required after # in headings
+    "MD037": true, // No spaces inside emphasis markers **like this**
+    "MD038": true, // No spaces inside code spans `like this`
+    "MD042": true, // No empty links [text]()
+    "MD056": true, // Table column count must be consistent
 
-  // Allow multiple headings with same content
-  "MD024": {
-    "siblings_only": true
+    // LLM-IMPORTANT (structure clarity for tokenization)
+    "MD001": true, // Heading levels increment by one (h1 -> h2, not h1 -> h3)
+    "MD022": true, // Blank lines around headings
+    "MD031": true, // Blank lines around fenced code blocks
+    "MD032": true, // Blank lines around lists
+    "MD040": true, // Code fence language specified (helps LLM understand code context)
+    "MD058": true, // Blank lines around tables
   },
-
-  // Line length - be lenient
-  "MD013": {
-    "line_length": 120,
-    "code_blocks": false,
-    "tables": false
-  },
-
-  // Allow trailing punctuation in headings
-  "MD026": false,
-
-  // Allow emphasis as heading
-  "MD036": false
 }