safeword 0.2.2 → 0.2.4

package/.safeword/planning/user-stories/003-reactive-fix-prevention.md

@@ -0,0 +1,132 @@
+# User Stories: Reactive Fix Prevention
+
+**Guide**: `@./.safeword/guides/user-story-guide.md` - Best practices, INVEST criteria, and examples
+**Template**: `@./.safeword/templates/user-stories-template.md`
+
+**Feature**: Prevent AI agents from falling into reactive "error-fix-error" loops
+
+**Related Issue**: Ticket #003
+**Status**: ❌ Not Started (0/5 stories complete)
+
+---
+
+## Story 1: Mandatory Architecture Context Loading
+
+**As a** developer using an AI coding agent
+**I want** the agent to load ARCHITECTURE.md before attempting any fix
+**So that** fixes respect the system's layers and boundaries
+
+**Acceptance Criteria**:
+
+- [ ] Agent reads ARCHITECTURE.md (if exists) before proposing any error fix
+- [ ] Agent identifies which layer the error occurs in
+- [ ] Agent notes which layers the fix might affect
+- [ ] If no ARCHITECTURE.md exists, agent proceeds with extra caution on multi-file changes
+
+**Implementation Status**: ❌ Not Started
+**Tests**: N/A (guidance-only, no automated tests)
+
+**Notes**: Add to SAFEWORD.md "Before ANY Error Fix" section
+
+---
+
+## Story 2: Reactive Fix Detection
+
+**As a** developer using an AI coding agent
+**I want** the agent to STOP after 2 failed fix attempts and use systematic-debugging
+**So that** the agent doesn't continue guessing and creating new problems
+
+**Acceptance Criteria**:
+
+- [ ] After 1st failed fix, agent notes "2nd attempt—consider systematic-debugging"
+- [ ] After 2nd failed fix, agent MUST stop and invoke systematic-debugging skill
+- [ ] Agent completes Phase 1 (Root Cause Investigation) before any further fixes
+- [ ] Agent documents findings before proceeding
+
+**Implementation Status**: ❌ Not Started
+**Tests**: N/A (guidance-only)
+
+**Notes**: Aligns with existing systematic-debugging "3+ fixes" rule—this makes it stricter (2 fixes)
+
+---
+
+## Story 3: Blast Radius Awareness
+
+**As a** developer using an AI coding agent
+**I want** the agent to pause and ask before changes affecting 4+ files
+**So that** sweeping changes don't violate architectural boundaries
+
+**Acceptance Criteria**:
+
+- [ ] Before modifying 4+ files, agent stops and summarizes proposed changes
+- [ ] Agent explains why this many files need changing
+- [ ] Agent asks: "This affects N files across [layers]. Proceed?"
+- [ ] If approved, agent makes atomic commits after each file
+
+**Implementation Status**: ❌ Not Started
+**Tests**: N/A (guidance-only)
+
+---
+
+## Story 4: Fix Cascade Detection
+
+**As a** developer using an AI coding agent
+**I want** the agent to recognize when fixes are cascading across files
+**So that** architectural problems are caught early instead of chased endlessly
+
+**Acceptance Criteria**:
+
+- [ ] When fix A reveals problem B in different file, agent notes the cascade
+- [ ] When fix B reveals problem C in yet another file, agent MUST stop
+- [ ] Agent documents: "Fixes cascading across files—possible architectural issue"
+- [ ] Agent discusses with user before continuing
+
+**Implementation Status**: ❌ Not Started
+**Tests**: N/A (guidance-only)
+
+**Notes**: This is the core "error-fix-error" pattern we're trying to break
+
+---
+
+## Story 5: Workaround Flagging
+
+**As a** developer using an AI coding agent
+**I want** workarounds to be explicitly flagged
+**So that** workarounds are conscious decisions, not hidden debt
+
+**Acceptance Criteria**:
+
+- [ ] When adding code that works around a problem (catch-ignore, special case, duplication, setTimeout), agent flags it
+- [ ] Agent adds comment: `// WORKAROUND: [reason] - TODO: [proper fix]`
+- [ ] Agent tells user: "Adding workaround for [X]. Proper fix would be [Y]."
+- [ ] Agent asks if workaround is acceptable
+
+**Implementation Status**: ❌ Not Started
+**Tests**: N/A (guidance-only)
+
+---
+
+## Summary
+
+**Completed**: 0/5 stories (0%)
+**Remaining**: 5/5 stories (100%)
+
+### Phase 1: Core Prevention ❌
+
+- Story 2: Reactive Fix Detection (P0)
+- Story 4: Fix Cascade Detection (P0)
+
+### Phase 2: Context & Awareness ❌
+
+- Story 1: Architecture Context Loading (P1)
+- Story 3: Blast Radius Awareness (P1)
+
+### Phase 3: Debt Visibility ❌
+
+- Story 5: Workaround Flagging (P2)
+
+**Next Steps**:
+
+1. Draft "Before ANY Error Fix" section for SAFEWORD.md
+2. Draft "Red Flags (Stop and Think)" section for SAFEWORD.md
+3. Update systematic-debugging skill with architecture context loading

package/.safeword/planning/user-stories/004-technical-constraints.md

@@ -0,0 +1,86 @@
+# User Stories: Technical Constraints in TDD (Ticket #004)
+
+**Guide**: `@./.safeword/guides/user-story-guide.md`
+**Template**: `@./.safeword/templates/user-stories-template.md`
+
+**Feature**: Add Technical Constraints section to user stories to capture NFRs before test definitions
+
+**Related Issue**: #004
+**Status**: ✅ Complete (3/3 stories complete)
+
+---
+
+## Technical Constraints
+
+_N/A — Documentation-only change, no runtime behavior._
+
+---
+
+## Story 1: Capture Technical Constraints in User Stories
+
+**As a** developer using TDD workflow
+**I want to** document technical constraints (performance, security, compatibility) alongside user stories
+**So that** test definitions are informed by NFRs from the start
+
+**Acceptance Criteria**:
+
+- [✅] User stories template has Technical Constraints section
+- [✅] Section includes categories: Performance, Security, Compatibility, Data, Dependencies, Infrastructure
+- [✅] Each constraint is a checkbox for tracking
+- [✅] Template notes "delete sections that don't apply"
+
+**Implementation Status**: ✅ Complete
+**Tests**: N/A (documentation change)
+
+**Notes**: Chose to add constraints to user stories (Option A) vs separate doc (Option B) for simplicity.
+
+---
+
+## Story 2: Guide Users on Filling Out Constraints
+
+**As a** developer creating user stories
+**I want to** understand what makes a good technical constraint
+**So that** I write specific, testable constraints (not vague requirements)
+
+**Acceptance Criteria**:
+
+- [✅] User story guide has "Technical Constraints Section" with guidance
+- [✅] Categories table explains what each category captures
+- [✅] Good/bad examples show specific vs vague constraints
+- [✅] Decision rule clarifies when to include/skip constraints
+
+**Implementation Status**: ✅ Complete
+**Tests**: N/A (documentation change)
+
+---
+
+## Story 3: Integrate Constraints into TDD Workflow
+
+**As an** AI coding agent following SAFEWORD.md
+**I want to** see constraints mentioned in the TDD workflow
+**So that** I don't skip them when creating user stories
+
+**Acceptance Criteria**:
+
+- [✅] SAFEWORD.md workflow step 1 mentions "Technical Constraints"
+- [✅] Creating user stories trigger includes "fill in constraints"
+- [✅] Edge cases include "user stories missing Technical Constraints"
+- [✅] TDD best practices has example with constraints
+
+**Implementation Status**: ✅ Complete
+**Tests**: N/A (documentation change)
+
+---
+
+## Summary
+
+**Completed**: 3/3 stories (100%)
+**Remaining**: 0/3 stories (0%)
+
+### Phase 1: Core Implementation ✅
+
+- Story 1: Template update
+- Story 2: Guide update
+- Story 3: Workflow integration
+
+**Next Steps**: User confirmation, then sync framework/SAFEWORD.md to .safeword/SAFEWORD.md

package/.safeword/planning/user-stories/005-cli-implementation.md

@@ -0,0 +1,311 @@
+# User Stories: Safeword CLI (Issue #1)
+
+**Guide**: `@./.safeword/guides/user-story-guide.md` - Best practices, INVEST criteria, and examples
+**Template**: `@./.safeword/templates/user-stories-template.md`
+
+**Feature**: TypeScript CLI (`safeword`) that replaces bash scripts with elite developer experience for setup, verification, and team onboarding.
+
+**Related Issue**: #1 (GitHub)
+**Status**: ❌ Not Started (0/12 stories complete)
+
+---
+
+## Technical Constraints
+
+### Performance
+- [ ] CLI startup time < 500ms (no heavy imports at top level)
+- [ ] Setup completes < 30s on average project
+- [ ] Version check timeout: 3s max before graceful fallback
+
+### Compatibility
+- [ ] Node.js 18+ (LTS)
+- [ ] macOS, Linux, Windows (WSL2)
+- [ ] Works with pnpm, npm, yarn, bun
+- [ ] Git optional (graceful degradation)
+
+### Dependencies
+- [ ] Minimal runtime dependencies (prefer Node built-ins)
+- [ ] Must integrate with existing `.claude/settings.json` structure
+- [ ] Must preserve existing Claude Code hooks (append, don't replace)
+- [ ] Must preserve existing git pre-commit hooks (marker-based)
+
+### Infrastructure
+- [ ] Published to npm as `safeword`
+- [ ] Executable via `npx safeword`
+- [ ] No global install required
+
+### Exit Codes
+- [ ] Exit 0 = success (warnings acceptable)
+- [ ] Exit 1 = core failure (linting fails, can't write files, unconfigured for diff/upgrade)
+
+---
+
+## Story 1: Version and Help
+
+**As a** developer discovering safeword
+**I want to** see version and help information
+**So that** I can learn what commands are available
+
+**Acceptance Criteria**:
+- [ ] `npx safeword --version` shows CLI version (e.g., "1.2.0")
+- [ ] `npx safeword --help` shows help with all commands and flags
+- [ ] `npx safeword` (bare command) shows help
+- [ ] Help includes: setup, check, upgrade, diff, reset commands
+- [ ] Help includes: --version, --help, --yes, --verbose, --offline flags
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 2: First-Time Setup - Core Files
+
+**As a** developer setting up a new project
+**I want to** run `npx safeword setup` to install core files
+**So that** I get safeword templates, guides, and configuration
+
+**Acceptance Criteria**:
+- [ ] Creates `.safeword/` directory with all templates
+- [ ] Creates `.safeword/version` file with CLI version
+- [ ] Prepends link to `AGENTS.md`: `**⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**`
+- [ ] Creates `AGENTS.md` if it doesn't exist
+- [ ] Checks for duplicate link before prepending (no duplicates)
+- [ ] Prints summary of files created
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 3: First-Time Setup - Hooks and Skills
+
+**As a** developer setting up a new project
+**I want to** setup to register Claude Code hooks and skills
+**So that** I get automated linting, quality review, and AGENTS.md protection
+
+**Acceptance Criteria**:
+- [ ] Registers hooks in `.claude/settings.json` (SessionStart, PostToolUse, Stop, etc.)
+- [ ] Copies skills to `.claude/skills/safeword-*/`
+- [ ] Preserves any existing hooks in `.claude/settings.json` (appends, doesn't replace)
+- [ ] Includes SessionStart hook for AGENTS.md verification
+- [ ] Exit 1 if hook registration fails
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 4: First-Time Setup - Linting
+
+**As a** developer setting up a new project
+**I want to** setup to configure linting automatically
+**So that** I get ESLint + Prettier working without manual configuration
+
+**Acceptance Criteria**:
+- [ ] Detects project type (Next.js, React, TypeScript, etc.) from package.json
+- [ ] Installs ESLint + Prettier as devDependencies
+- [ ] Creates `eslint.config.mjs` configured for detected project type
+- [ ] Creates `.prettierrc` with standard config
+- [ ] Adds `"lint": "eslint ."` script to package.json
+- [ ] Adds `"format": "prettier --write ."` script to package.json
+- [ ] Exit 1 if linting setup fails (core failure)
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 5: Setup Blocks on Existing Config
+
+**As a** developer who already has safeword configured
+**I want to** see a clear error when running `setup` again
+**So that** I don't accidentally overwrite my configuration
+
+**Acceptance Criteria**:
+- [ ] Running `npx safeword setup` when `.safeword/` exists shows error
+- [ ] Error message: "Already configured. Run `safeword upgrade` to update."
+- [ ] Exit code is 1
+- [ ] No files are modified
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 6: Non-Interactive Setup
+
+**As a** developer running setup in CI or scripts
+**I want to** setup to work without prompts
+**So that** I can automate project initialization
+
+**Acceptance Criteria**:
+- [ ] No TTY detected → uses defaults automatically (no prompts)
+- [ ] `--yes` flag → forces defaults even in terminal
+- [ ] Default for git prompt: skip init, show warning
+- [ ] Setup completes without user interaction
+- [ ] Warning shown when git skipped: "Skipped git initialization (no TTY detected)"
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 7: Git Repository Handling
+
+**As a** developer in a non-git directory
+**I want to** be prompted about git initialization
+**So that** I can choose whether to initialize git for hook support
+
+**Acceptance Criteria**:
+- [ ] No `.git/` detected + TTY → prompts "Initialize git repository? [y/N]"
+- [ ] User says yes → runs `git init`, then installs git hooks
+- [ ] User says no → continues setup, warns "Git hooks skipped (no repository)"
+- [ ] With `--yes` or no TTY → auto-skips git init with warning
+- [ ] With `.git/` present → installs git hooks, no prompt
+- [ ] Git hooks use marker-based append (`SAFEWORD_ARCH_CHECK_START/END`)
+- [ ] Preserves existing content in `.git/hooks/pre-commit`
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 8: Health Check
+
+**As a** developer maintaining a project
+**I want to** run `npx safeword check` to see project health
+**So that** I can verify configuration and check for updates
+
+**Acceptance Criteria**:
+- [ ] Shows CLI version: "Safeword CLI: v1.2.0"
+- [ ] Shows project config version: "Project config: v1.0.0"
+- [ ] Shows if update available: "(v1.2.0 available)"
+- [ ] Verifies `.safeword/` structure is intact
+- [ ] Exit code 0 on success
+- [ ] On unconfigured project: "Not configured. Run `safeword setup`." (exit 0)
+- [ ] Version check timeout after 3s → graceful fallback
+- [ ] On timeout: "Couldn't check for updates (offline?)"
+- [ ] `--offline` flag → skips version check entirely
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 9: Upgrade Configuration
+
+**As a** developer with an older safeword version
+**I want to** run `npx safeword upgrade` to update my configuration
+**So that** I get the latest templates, guides, and hooks
+
+**Acceptance Criteria**:
+- [ ] Overwrites all `.safeword/` files with CLI's bundled templates
+- [ ] Updates `.claude/skills/safeword-*/` with latest skills
+- [ ] Updates hooks in `.claude/settings.json` if changed
+- [ ] Preserves non-safeword hooks in `.claude/settings.json`
+- [ ] Updates `.safeword/version` file to CLI version
+- [ ] Prints summary: files added, modified, unchanged
+- [ ] Same-version upgrade → reinstalls anyway (for repairs)
+- [ ] Refuses to downgrade: "CLI v1.0.0 is older than project v1.2.0. Update CLI first."
+- [ ] On unconfigured project: "Not configured. Run `safeword setup`." (exit 1)
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+**Notes**: User customizations in `.safeword/` are overwritten by design. Documented behavior.
+
+---
+
+## Story 10: Preview Changes Before Upgrade
+
+**As a** developer considering an upgrade
+**I want to** run `npx safeword diff` to preview what would change
+**So that** I can review changes before committing to upgrade
+
+**Acceptance Criteria**:
+- [ ] Default output shows summary: count of files added, modified, removed
+- [ ] Lists each file by category (Added, Modified, Unchanged)
+- [ ] Shows version transition: "Changes from v1.0.0 → v1.2.0"
+- [ ] `--verbose` flag shows full unified diff for each modified file
+- [ ] Exit code 0 on success
+- [ ] On unconfigured project: "Not configured." (exit 1)
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+---
+
+## Story 11: Remove Configuration
+
+**As a** developer who wants to remove safeword
+**I want to** run `npx safeword reset` to cleanly uninstall
+**So that** I can remove safeword without leaving hook artifacts
+
+**Acceptance Criteria**:
+- [ ] Prompts for confirmation: "This will remove safeword configuration. Continue? [y/N]"
+- [ ] `--yes` flag → auto-confirms without prompt
+- [ ] No TTY → auto-confirms (like `--yes`)
+- [ ] Removes `.safeword/` directory
+- [ ] Removes safeword hooks from `.claude/settings.json` (preserves other hooks)
+- [ ] Removes `.claude/skills/safeword-*/` directories
+- [ ] Removes git hook markers from `.git/hooks/pre-commit` (preserves other content)
+- [ ] Removes safeword link line from `AGENTS.md` (preserves other content)
+- [ ] On unconfigured project: "Nothing to remove." (exit 0)
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+**Notes**:
+- Linting artifacts intentionally preserved: `eslint.config.mjs`, `.prettierrc`, `lint`/`format` scripts, ESLint/Prettier devDependencies
+- Rationale: Linting is useful independently, user may have customized, standard CLI behavior
+- Summary should note: "Linting configuration preserved (remove manually if desired)"
+
+---
+
+## Story 12: AGENTS.md Self-Healing
+
+**As a** developer who accidentally removed the AGENTS.md link
+**I want to** safeword to detect and fix this automatically
+**So that** the LLM always reads SAFEWORD.md first
+
+**Acceptance Criteria**:
+- [ ] SessionStart hook checks if AGENTS.md contains safeword link
+- [ ] If link missing → re-adds link to top of AGENTS.md
+- [ ] If link missing → shows warning: "Restored AGENTS.md link (was removed)"
+- [ ] If AGENTS.md file deleted → recreates file with link only
+- [ ] Checks for duplicate before adding (no duplicates)
+- [ ] Hook exits cleanly (doesn't block Claude Code startup)
+
+**Implementation Status**: ❌ Not Started
+**Tests**: TBD
+
+**Notes**: Ensures LLM primacy—SAFEWORD.md must be read first for consistent behavior.
+
+---
+
+## Summary
+
+**Completed**: 0/12 stories (0%)
+**Remaining**: 12/12 stories (100%)
+
+### Phase 1: Foundation ❌
+- Story 1: Version and Help
+
+### Phase 2: Setup Flow ❌
+- Story 2: First-Time Setup - Core Files
+- Story 3: First-Time Setup - Hooks and Skills
+- Story 4: First-Time Setup - Linting
+- Story 5: Setup Blocks on Existing Config
+- Story 6: Non-Interactive Setup
+- Story 7: Git Repository Handling
+
+### Phase 3: Lifecycle Commands ❌
+- Story 8: Health Check
+- Story 9: Upgrade Configuration
+- Story 10: Preview Changes Before Upgrade
+
+### Phase 4: Cleanup & Maintenance ❌
+- Story 11: Remove Configuration
+- Story 12: AGENTS.md Self-Healing
+
+**Next Steps**: Create test definitions, then implement Phase 1 (foundation)

package/.safeword/planning/user-stories/cli-self-contained-templates.md

@@ -0,0 +1,172 @@
+# User Stories: CLI Self-Contained Templates
+
+**Guide**: `@./.safeword/guides/user-story-guide.md`
+**Template**: `@./.safeword/templates/user-stories-template.md`
+
+**Feature**: Bundle all templates into CLI package so `npx safeword` works without external dependencies
+
+**Related Issue**: N/A (internal)
+**Status**: 🟡 In Progress (5/6 stories implemented, Story 1 partial)
+
+---
+
+## Technical Constraints
+
+### Performance
+- [ ] `safeword setup` completes in < 5s on SSD
+- [ ] `safeword upgrade` completes in < 3s (no network calls)
+
+### Security
+- [ ] Hook scripts use `jq` for JSON output (no shell injection via echo)
+- [ ] No secrets in bundled templates
+
+### Compatibility
+- [ ] Node.js 18+ (ESM-only)
+- [ ] Works on macOS, Linux, Windows (Git Bash)
+- [ ] Package managers: npm, yarn, pnpm, bun
+
+### Dependencies
+- [ ] Must use existing Claude Code hook format (nested `hooks` array)
+- [ ] Must preserve user's existing `.claude/settings.json` hooks
+- [ ] ESLint 9.x flat config with `defineConfig()` and `extends`
+
+### Infrastructure
+- [ ] CLI package < 500KB (excluding node_modules)
+- [ ] Templates bundled as files (not string constants)
+- [ ] `jq` required on system for hooks (`safeword check` warns if missing)
+
+---
+
+## Story 1: Setup Installs Complete Templates
+
+**As a** developer running `safeword setup`
+**I want** all safeword templates installed to my project
+**So that** I have the full methodology without manual copying
+
+**Acceptance Criteria**:
+- [ ] `.safeword/SAFEWORD.md` is the full ~31KB file (not a stub)
+- [ ] `.safeword/guides/` contains 13 methodology guides
+- [ ] `.safeword/doc-templates/` contains 5 document templates
+- [ ] `.safeword/prompts/` contains 2 review prompts
+- [ ] Empty directories created: `.safeword/planning/user-stories/`, `.safeword/planning/design/`, `.safeword/tickets/completed/`, `.safeword/learnings/`
+- [ ] `AGENTS.md` created (if missing) with link to `.safeword/SAFEWORD.md`; existing AGENTS.md untouched
+- [ ] Running setup again overwrites safeword-owned files, preserves user content in `learnings/`
+
+**Implementation Status**: 🟡 Partial (stub installed, full templates not bundled)
+**Tests**: `packages/cli/tests/commands/setup-templates.test.ts`
+
+---
+
+## Story 2: Setup Installs Hook System
+
+**As a** developer running `safeword setup`
+**I want** Claude Code hooks installed and registered
+**So that** quality automation works immediately
+
+**Acceptance Criteria**:
+- [ ] `.safeword/hooks/` contains 7 hook scripts with `{event}-{action}.sh` naming
+- [ ] `.safeword/lib/` contains 2 shared scripts with `_lib-` prefix
+- [ ] `.safeword/git/git-pre-commit.sh` exists for git hooks
+- [ ] `.claude/settings.json` has hooks registered with correct nested format
+- [ ] Hooks marked with `_safeword: true` for upgrade identification
+- [ ] Existing user hooks in settings.json preserved (merged, not replaced)
+- [ ] `.mcp.json` updated with context7 and playwright servers (merged, not replaced)
+- [ ] Running setup again: safeword hooks replaced, user hooks preserved
+
+**Implementation Status**: ✅ Implemented
+**Tests**: `packages/cli/tests/commands/setup-hooks.test.ts`
+
+---
+
+## Story 3: Setup Installs Skills and Commands
+
+**As a** developer running `safeword setup`
+**I want** Claude Code skills and slash commands installed
+**So that** I can use quality review features
+
+**Acceptance Criteria**:
+- [ ] `.claude/skills/quality-reviewer/SKILL.md` has full content with YAML frontmatter
+- [ ] `.claude/commands/` contains quality-review.md, arch-review.md, lint.md
+- [ ] Skill frontmatter includes `name`, `description`, `allowed-tools`
+
+**Implementation Status**: ✅ Implemented
+**Tests**: `packages/cli/tests/commands/setup-hooks.test.ts`
+
+---
+
+## Story 4: Setup Configures Linting
+
+**As a** developer running `safeword setup`
+**I want** ESLint and Prettier configured automatically
+**So that** code quality is enforced from the start
+
+**Acceptance Criteria**:
+- [ ] `.safeword/eslint.config.js` generated with detected plugins (React, Vitest, etc.)
+- [ ] `.safeword/prettier.config.js` generated with defaults
+- [ ] `.safeword/.markdownlint.jsonc` created for markdown linting
+- [ ] Root `eslint.config.js` created (if none exists) importing safeword config via `extends`
+- [ ] Root `prettier.config.js` created (if none exists) spreading safeword config
+- [ ] Existing lint configs preserved (not overwritten)
+- [ ] ESLint plugins + `markdownlint-cli2` installed to project devDependencies
+- [ ] `package.json` scripts added: `lint`, `lint:md`, `format`, `format:check` (if missing)
+
+**Implementation Status**: ✅ Implemented (configs at root, not .safeword/)
+**Tests**: `packages/cli/tests/commands/setup-linting.test.ts`
+
+---
+
+## Story 5: Upgrade Updates Safeword-Owned Files
+
+**As a** developer running `safeword upgrade`
+**I want** safeword templates updated without losing my customizations
+**So that** I get improvements without merge conflicts
+
+**Acceptance Criteria**:
+- [ ] `.safeword/` contents replaced with latest templates
+- [ ] User's `eslint.config.js` and `prettier.config.js` untouched
+- [ ] Hooks with `_safeword: true` in settings.json replaced; user hooks preserved
+- [ ] `learnings/` directory preserved (user content)
+- [ ] Backup created before upgrade (`.safeword.backup/`)
+- [ ] Backup deleted on success
+
+**Implementation Status**: ✅ Implemented
+**Tests**: `packages/cli/tests/commands/upgrade.test.ts`
+
+---
+
+## Story 6: Reset Removes Safeword Cleanly
+
+**As a** developer running `safeword reset`
+**I want** all safeword artifacts removed from my project
+**So that** I can start fresh or remove safeword completely
+
+**Acceptance Criteria**:
+- [ ] `.safeword/` directory deleted
+- [ ] Hooks with `_safeword: true` removed from `.claude/settings.json`
+- [ ] `.claude/skills/quality-reviewer/` deleted
+- [ ] `.claude/commands/` safeword commands deleted
+- [ ] MCP servers `context7` and `playwright` removed from `.mcp.json`
+- [ ] User's other hooks, skills, commands preserved
+- [ ] User's lint configs untouched
+
+**Implementation Status**: ✅ Implemented
+**Tests**: `packages/cli/tests/commands/reset.test.ts`
+
+---
+
+## Summary
+
+**Completed**: 5/6 stories (83%)
+**Remaining**: Story 1 template bundling
+
+### Core Setup
+- Story 1: Complete templates - 🟡 Partial (stub only)
+- Story 2: Hook system - ✅ Implemented
+- Story 3: Skills and commands - ✅ Implemented
+- Story 4: Linting configuration - ✅ Implemented
+
+### Lifecycle
+- Story 5: Upgrade - ✅ Implemented
+- Story 6: Reset - ✅ Implemented
+
+**Next Step**: Implement Story 1 - bundle full template files into CLI package