safeword 0.2.2 → 0.2.4

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

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

@@ -0,0 +1,60 @@
+# 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.