safeword 0.2.4 → 0.2.5

package/.safeword/planning/design/013c-config-isolation-strategy.md

@@ -1,242 +0,0 @@
-# Config Isolation Strategy
-
-**Parent:** [013-cli-self-contained-templates.md](./013-cli-self-contained-templates.md)
-**Date:** 2025-11-29
-
-Safeword maximizes autonomy by keeping its configs separate from user customizations. This prevents merge conflicts on upgrades and gives users confidence to modify their own files.
-
----
-
-## Principle: Separate Ownership
-
-| Config Type | User Owns | Safeword Owns | Strategy |
-|-------------|-----------|---------------|----------|
-| ESLint | `eslint.config.js` | `.safeword/eslint.config.js` | User imports safeword |
-| Prettier | `prettier.config.js` | `.safeword/prettier.config.js` | User spreads safeword |
-| Markdownlint | N/A | `.safeword/.markdownlint.jsonc` | Safeword owns entirely |
-| Claude hooks | `.claude/settings.json` | Hooks marked `_safeword: true` | Marker-based merge |
-| package.json | `scripts` section | N/A | Add if missing, never overwrite |
-| Pre-commit | `.husky/pre-commit` | `.safeword/git/git-pre-commit.sh` | User calls safeword script |
-| lint-staged | N/A | `.safeword/lint-staged.config.js` | Safeword owns entirely |
-
----
-
-## ESLint: `extends` Pattern (ESLint 9.x 2025)
-
-Per [ESLint's defineConfig docs](https://eslint.org/blog/2025/03/flat-config-extends-define-config-global-ignores/), use the new `extends` key:
-
-```javascript
-// eslint.config.js (USER OWNS - stable, minimal)
-import { defineConfig } from 'eslint/config';
-import safeword from './.safeword/eslint.config.js';
-
-export default defineConfig([
-  { extends: [safeword] },
-  // === YOUR CUSTOMIZATIONS BELOW ===
-  // { rules: { 'no-console': 'warn' } },
-]);
-```
-
-```javascript
-// .safeword/eslint.config.js (SAFEWORD OWNS - regenerated on upgrade)
-// ⚠️ AUTO-GENERATED BY SAFEWORD - DO NOT EDIT
-// Customize in your root eslint.config.js instead
-
-import js from '@eslint/js';
-import sonarjs from 'eslint-plugin-sonarjs';
-import sdl from '@microsoft/eslint-plugin-sdl';
-// ... auto-detected plugins
-
-export default [
-  js.configs.recommended,
-  sonarjs.configs.recommended,
-  ...sdl.configs.recommended,
-  // ... framework configs based on detection
-];
-```
-
----
-
-## Prettier: Spread Pattern
-
-Per [Prettier sharing docs](https://prettier.io/docs/sharing-configurations), use JS config with spread:
-
-```javascript
-// prettier.config.js (USER OWNS)
-import safeword from './.safeword/prettier.config.js';
-
-export default {
-  ...safeword,
-  // Your overrides:
-  printWidth: 100,
-};
-```
-
-```javascript
-// .safeword/prettier.config.js (SAFEWORD OWNS)
-// ⚠️ AUTO-GENERATED BY SAFEWORD - DO NOT EDIT
-export default {
-  semi: true,
-  singleQuote: true,
-  tabWidth: 2,
-  trailingComma: 'es5',
-};
-```
-
----
-
-## Claude Hooks: Marker-Based Merge
-
-Safeword marks its hooks with `"_safeword": true` for clean upgrades:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      { "_safeword": true, "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.safeword/hooks/session-verify-agents.sh" }] },
-      { "_safeword": true, "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.safeword/hooks/session-version.sh" }] },
-      { "hooks": [{ "type": "command", "command": "./my-custom-hook.sh" }] }
-    ]
-  }
-}
-```
-
-**Upgrade logic:**
-1. Find all hooks with `"_safeword": true`
-2. Remove them
-3. Insert new safeword hooks at start of each array
-4. User hooks (without marker) are preserved
-
----
-
-## Package.json Scripts: Add If Missing
-
-```typescript
-function addScriptsIfMissing(pkg: PackageJson): PackageJson {
-  const scripts = pkg.scripts || {};
-
-  // Only add if not present - never overwrite
-  if (!scripts.lint) scripts.lint = 'eslint .';
-  if (!scripts.format) scripts.format = 'prettier --write .';
-  if (!scripts['format:check']) scripts['format:check'] = 'prettier --check .';
-
-  return { ...pkg, scripts };
-}
-```
-
----
-
-## Pre-commit: Delegation Pattern
-
-```bash
-# .husky/pre-commit (USER OWNS)
-#!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
-
-# Safeword's pre-commit checks
-./.safeword/git/git-pre-commit.sh
-
-# Your additional hooks below:
-# npm run my-custom-check
-```
-
-```bash
-# .safeword/git/git-pre-commit.sh (SAFEWORD OWNS)
-#!/bin/bash
-npx lint-staged --config .safeword/lint-staged.config.js
-```
-
----
-
-## Plugin Ownership Matrix
-
-Some plugins require user-specific config and belong in user's file:
-
-| Plugin | In Safeword Config? | Reason |
-|--------|---------------------|--------|
-| sonarjs | Yes | Zero-config, works out of box |
-| sdl | Yes | Zero-config, works out of box |
-| react | Yes | Auto-detected, zero-config |
-| react-hooks | Yes | Auto-detected, zero-config |
-| next | Yes | Auto-detected, zero-config |
-| vitest | Yes | Auto-detected, sensible file patterns |
-| playwright | Yes | Auto-detected, sensible file patterns |
-| drizzle | Yes | Auto-detected, zero-config |
-| boundaries | Yes | Auto-detected (3+ dirs), `warn` severity, separate config file |
-
----
-
-## Boundaries: Auto-Generated with Override Option
-
-Boundaries config is auto-generated in `.safeword/eslint-boundaries.config.js` when 3+ architecture dirs are detected. Users can override in their `eslint.config.js`:
-
-```javascript
-// eslint.config.js (USER OWNS)
-import { defineConfig } from 'eslint/config';
-import safeword from './.safeword/eslint.config.js';
-
-export default defineConfig([
-  { extends: [safeword] },
-
-  // Override auto-generated boundaries with stricter rules
-  {
-    rules: {
-      'boundaries/element-types': ['error', {  // Upgrade to error
-        default: 'disallow',
-        rules: [
-          // Custom architecture rules
-        ],
-      }],
-    },
-  },
-]);
-```
-
-**To disable boundaries entirely:**
-```javascript
-export default defineConfig([
-  { extends: [safeword] },
-  { rules: { 'boundaries/element-types': 'off' } },
-]);
-```
-
----
-
-## First-Time Setup Templates
-
-When user has no config, safeword creates minimal files:
-
-**eslint.config.js:**
-```javascript
-// eslint.config.js - Created by safeword
-import { defineConfig } from 'eslint/config';
-import safeword from './.safeword/eslint.config.js';
-
-export default defineConfig([
-  // Safeword's config (auto-maintained on upgrade)
-  { extends: [safeword] },
-
-  // === YOUR CUSTOMIZATIONS BELOW ===
-
-  // Override rules:
-  // { rules: { 'no-console': 'warn' } },
-
-  // Override boundaries severity (auto-generated uses 'warn'):
-  // { rules: { 'boundaries/element-types': 'error' } },
-
-  // Disable boundaries entirely:
-  // { rules: { 'boundaries/element-types': 'off' } },
-]);
-```
-
-**prettier.config.js:**
-```javascript
-// prettier.config.js - Created by safeword
-import safeword from './.safeword/prettier.config.js';
-
-export default {
-  ...safeword,
-  // Your overrides:
-  // printWidth: 100,
-};
-```

package/.safeword/planning/design/code-philosophy-improvements.md

@@ -1,60 +0,0 @@
-# Code Philosophy Guide Improvements
-
-**Target file:** `framework/guides/code-philosophy.md`
-**Status:** v3 - No changes needed
-
----
-
-## Final Assessment
-
-After three rounds of critique, **the document is already good**. All proposed changes were either redundant or unnecessary.
-
-| Original Proposal       | Final Verdict     | Why                                                          |
-| ----------------------- | ----------------- | ------------------------------------------------------------ |
-| 1. Bloat definition     | ❌ NOT NEEDED     | Lines 58-66 define via 5 examples (Principle 4: show > tell) |
-| 2. Regex edge case      | ❌ NOT NEEDED     | Too specific for philosophy doc                              |
-| 3. Tie-breaker          | ❌ ALREADY EXISTS | Line 67: "Is this essential now, or can we add it later?"    |
-| 4. Self-test rule       | ❌ ALREADY EXISTS | Line 89: "Run tests yourself before completion"              |
-| 5. Best Practices vague | ❌ NOT NEEDED     | Line 121 IS concrete: "Use Context7 MCP or official docs"    |
-| 6. "If stuck" line      | ❌ ALREADY EXISTS | Line 140: "What's your preference?"                          |
-
----
-
-## Principle Compliance Check
-
-| Principle                    | Status  | Evidence                                   |
-| ---------------------------- | ------- | ------------------------------------------ |
-| 1. MECE                      | N/A     | Philosophy doc, no decision trees needed   |
-| 2. Explicit definitions      | ✅      | Examples define terms (lines 37-66)        |
-| 3. No contradictions         | ✅      | Consistent throughout                      |
-| 4. Concrete examples         | ✅      | 20+ good/bad examples in tables            |
-| 5. Edge cases                | Partial | Appropriate for philosophy doc scope       |
-| 6. Actionable                | ✅      | Lines 75-78, 121, 140                      |
-| 7. Sequential decision trees | N/A     | Not a decision doc                         |
-| 8. Tie-breakers              | ✅      | Line 67                                    |
-| 9. Lookup tables             | N/A     | Not needed                                 |
-| 10. No caveats in tables     | ✅      | Tables are clean                           |
-| 11. Percentages              | N/A     | None used                                  |
-| 12. Specificity              | ✅      | Specific tool names, concrete examples     |
-| 13. Re-evaluation paths      | ✅      | Lines 131 (blockers) and 140 (preferences) |
-
----
-
-## Conclusion
-
-**No changes to apply.** The document already adheres to llm-instruction-design.md principles.
-
-Looking for problems to fix when none exist = bloat.
-
----
-
-## Lesson Learned
-
-I initially proposed 6 changes, then 2, now 0. Each review revealed existing content I'd missed:
-
-- Line 67 has a tie-breaker
-- Line 89 has self-test rule
-- Line 121 has concrete research method
-- Line 140 has re-evaluation path
-
-The document is well-written. Don't add bloat.