safeword 0.2.3 → 0.2.4

package/.safeword/planning/005-architecture-enforcement-system.md

@@ -0,0 +1,169 @@
+# Plan: Architecture Enforcement for SAFEWORD
+
+**Created:** 2025-11-27  
+**Status:** Draft
+
+---
+
+## Problem
+
+AI agents write code without respecting architectural boundaries → circular dependencies, god modules (>10 dependents or >500 lines), unsafe refactoring.
+
+## Solution
+
+Codify layers + boundaries in `ARCHITECTURE.md`, enforce via static analysis tools and LLM prompts.
+
+---
+
+## Deliverables
+
+### Phase 1: Documentation
+
+| Deliverable                          | Description                                 |
+| ------------------------------------ | ------------------------------------------- |
+| `templates/architecture-template.md` | Layers/boundaries section template          |
+| Update `architecture-guide.md`       | Add layers/boundaries guidance + edge cases |
+
+**Layers Template (sample):**
+
+```markdown
+## Layers & Boundaries
+
+### Layer Definitions
+
+| Layer  | Directory     | Responsibility              |
+| ------ | ------------- | --------------------------- |
+| app    | `src/app/`    | UI, routing, composition    |
+| domain | `src/domain/` | Business rules, pure logic  |
+| infra  | `src/infra/`  | IO, APIs, DB, external SDKs |
+
+### Allowed Dependencies
+
+| From   | To     | Allowed | Rationale                         |
+| ------ | ------ | ------- | --------------------------------- |
+| app    | domain | ✅      | UI composes business logic        |
+| app    | infra  | ✅      | UI triggers side effects          |
+| domain | app    | ❌      | Domain must be framework-agnostic |
+| domain | infra  | ❌      | Domain contains pure logic only   |
+| infra  | domain | ✅      | Adapters may use domain types     |
+
+Note: This template allows direct app→infra. Alternative: force app→domain→infra for stricter separation (hexagonal/ports-adapters pattern).
+```
+
+**Edge Cases (must document):**
+
+- Project doesn't fit 3-layer model → Document actual layers, same boundary rules apply
+- Feature module needs another feature → Import via public API (`index.ts`) only
+- Shared utilities → Create `shared/` layer, all layers may import
+- Brownfield adoption → Start with warnings-only mode, fix violations incrementally, then enforce
+
+### Phase 2: Boundary Enforcement (ESLint)
+
+| Deliverable                    | Description                                           |
+| ------------------------------ | ----------------------------------------------------- |
+| Add `eslint-plugin-boundaries` | To all ESLint modes in `setup-linting.sh`             |
+| Remove `--biome` mode          | ESLint is the only supported linter (breaking change) |
+| Update `architecture-guide.md` | Boundary rule setup instructions                      |
+
+**Why ESLint-only:**
+
+- IDE integration (errors show in editor immediately)
+- Single config file (no separate tool)
+- Most TypeScript projects use ESLint anyway
+- Simpler maintenance (one path)
+
+**User flow:**
+
+1. Run `setup-linting.sh` → gets ESLint + boundary rules
+2. Create `ARCHITECTURE.md` → define layers
+3. Configure boundary rules in `eslint.config.mjs`
+4. Errors appear in IDE + CI automatically
+
+### Phase 3: LLM Prompts + Pre-commit Hook
+
+| Deliverable                 | Description                                                |
+| --------------------------- | ---------------------------------------------------------- |
+| `framework/prompts/` folder | New folder for LLM inputs (copied to `.safeword/prompts/`) |
+| `prompts/quality-review.md` | Extract existing prompt from `setup-quality.sh`            |
+| `prompts/arch-review.md`    | Semantic architecture review prompt                        |
+| `scripts/arch-review.sh`    | Shell script calling Haiku API for arch review             |
+| Update `setup-safeword.sh`  | Copy `prompts/` folder + add pre-commit hook               |
+| Update `setup-quality.sh`   | Reference `.safeword/prompts/quality-review.md`            |
+
+**`prompts/arch-review.md`:**
+
+```
+Review for architectural issues:
+
+1. **Misplaced logic** - Business rules in wrong layer?
+2. **God module** - Too many responsibilities?
+3. **Leaky abstraction** - Implementation details exposed?
+4. **Tight coupling** - Changes cascade unnecessarily?
+
+Return JSON:
+{
+  "issues": [{ "type": string, "location": string, "fix": string }],
+  "verdict": "clean" | "minor" | "refactor_needed"
+}
+```
+
+**`scripts/arch-review.sh`:**
+
+- Sends changed files + ARCHITECTURE.md + prompt
+- Returns JSON verdict
+- Requires `ANTHROPIC_API_KEY` env var
+
+**Pre-commit hook integration:**
+
+- Git pre-commit hook runs:
+  1. `eslint` on staged files (fast, free, deterministic)
+  2. `arch-review.sh` on staged files (semantic review)
+- Lint errors → blocks commit
+- Arch verdict `refactor_needed` → blocks commit
+- Arch verdict `minor` → warns, allows commit
+
+### Phase 4: CI Integration
+
+| Deliverable                           | Description                      |
+| ------------------------------------- | -------------------------------- |
+| `templates/ci/architecture-check.yml` | GitHub Actions workflow template |
+
+**CI Steps (in order):**
+
+1. `tsc --noEmit` - Type check
+2. `eslint` - Includes boundary rules via eslint-plugin-boundaries
+3. LLM review (optional, non-blocking initially)
+
+### Phase 5: Drift Detection
+
+Deferred. Revisit after Phase 4 validated in production use.
+
+---
+
+## Dependencies
+
+| Phase            | Depends On | Can Parallelize With |
+| ---------------- | ---------- | -------------------- |
+| Phase 1: Docs    | None       | Phase 2, 3           |
+| Phase 2: Tooling | None       | Phase 1, 3           |
+| Phase 3: Prompts | None       | Phase 1, 2           |
+| Phase 4: CI      | Phase 2    | —                    |
+| Phase 5: Drift   | Phase 4    | —                    |
+
+**Recommended start:** Phase 1 + Phase 2 + Phase 3 in parallel, then Phase 4.
+
+---
+
+## Open Questions
+
+1. **Scope:** TypeScript-only, or Python support in Phase 6?
+2. **CI LLM review:** Blocking or advisory-only initially?
+3. **Template flexibility:** Ship opinionated 3-layer, or configurable?
+
+---
+
+## Next Steps
+
+1. ✅ Ticket created: `.safeword/tickets/002-architecture-enforcement.md`
+2. Write user stories for Phase 1
+3. Prototype boundary rules in a test project

package/.safeword/planning/006-reactive-fix-prevention-research.md

@@ -0,0 +1,135 @@
+# Research: Reactive Fix Prevention
+
+**Created:** 2025-11-27  
+**Status:** Complete  
+**Ticket:** 003-reactive-fix-prevention
+
+---
+
+## Problem Statement
+
+AI coding agents fall into "error-fix-error" loops:
+
+1. See error → attempt fix
+2. Fix creates new error → attempt another fix
+3. Repeat until codebase is tangled
+
+This pattern ignores:
+
+- Root cause analysis
+- Architectural boundaries
+- Broader system implications
+
+## Research Sources
+
+### 1. MASAI Framework (arxiv.org/abs/2406.11638)
+
+**Key finding:** Modular sub-agents with well-defined objectives outperform monolithic agents.
+
+**Relevance:** Instead of one agent that does everything, specialized agents (planner, implementer, reviewer) prevent reactive thrashing.
+
+**Application:** Force planning phase before implementation phase.
+
+### 2. ProSEA Framework (arxiv.org/abs/2510.07423)
+
+**Key finding:** Manager Agent orchestrates Expert Agents. Failed attempts report back with "structured feedback" including constraints discovered.
+
+**Relevance:** When a fix fails, the agent should learn WHY and carry that constraint forward—not just try another random fix.
+
+**Application:** After any fix attempt, agent must document what was learned before retrying.
+
+### 3. Factored Agents (arxiv.org/abs/2503.22931)
+
+**Key finding:** Separating in-context learning (planning) from memorization (execution) improves accuracy.
+
+**Relevance:** Agents that plan separately from executing make better architectural decisions.
+
+**Application:** Explicit "planning mode" before "execution mode."
+
+### 4. DEV.to Article (vuong_ngo)
+
+**Key finding:** "AI Keeps Breaking Your Architectural Patterns. Documentation Won't Fix It."
+
+**Relevance:** Long AGENTS.md files are insufficient. Agents need:
+
+- Active validation mechanisms
+- Enforcement gates
+- Context retrieval at decision points
+
+**Application:** Pre-commit hooks, session-level triggers, mandatory context loading.
+
+---
+
+## Synthesis
+
+| Problem               | Root Cause                   | Solution                                                |
+| --------------------- | ---------------------------- | ------------------------------------------------------- |
+| Reactive fixing       | No planning phase            | Mandatory "understand first" before any fix             |
+| Ignoring architecture | Docs loaded once, forgotten  | Force ARCHITECTURE.md reload at decision points         |
+| Cascading fixes       | No threshold/circuit breaker | "3+ fixes = STOP" rule (exists in systematic-debugging) |
+| Multi-file changes    | No blast radius awareness    | Approval gate for >3 file changes                       |
+
+---
+
+## Recommended Additions to SAFEWORD
+
+### 1. Before ANY Error Fix (Mandatory)
+
+```markdown
+## Before ANY Error Fix (CRITICAL)
+
+BEFORE attempting to fix any error:
+
+1. **Load Context** - Read relevant ARCHITECTURE.md sections
+2. **Ask "Why Here?"** - Is this error a symptom of a deeper issue?
+3. **Check Pattern** - Does the fix match existing patterns, or introduce a new one?
+4. **Consider Blast Radius** - What else touches this code?
+
+If you've made 2+ fix attempts → STOP. Use systematic-debugging skill.
+If fix would change >3 files → STOP. Get approval first.
+```
+
+### 2. Red Flags (Stop and Think)
+
+```markdown
+## Red Flags (Stop and Think)
+
+If you catch yourself:
+
+- Fixing an error you just created
+- Changing the same file 3+ times in one session
+- Adding workarounds instead of understanding root cause
+- "Just trying" something without hypothesis
+- Fixing in multiple layers for "one" issue
+
+→ STOP. Read ARCHITECTURE.md. Use systematic-debugging.
+```
+
+### 3. Validation Triggers
+
+| Trigger                 | Action                         |
+| ----------------------- | ------------------------------ |
+| 2+ fix attempts         | Stop, use systematic-debugging |
+| 3+ changes to same file | Stop, investigate root cause   |
+| 5+ files changed        | Run architecture review        |
+| Fix touches 3+ layers   | Get explicit approval          |
+
+---
+
+## Integration Points
+
+| Existing Asset              | How to Integrate                      |
+| --------------------------- | ------------------------------------- |
+| SAFEWORD.md                 | Add "Before ANY Error Fix" section    |
+| code-philosophy.md          | Add "Reactive Fix Prevention" section |
+| systematic-debugging skill  | Add architecture context loading step |
+| arch-review.sh (ticket 002) | Use as validation gate                |
+
+---
+
+## Next Steps
+
+1. ✅ User stories created (`.safeword/planning/user-stories/003-reactive-fix-prevention.md`)
+2. Draft SAFEWORD.md additions (Stories 1-4)
+3. Update systematic-debugging skill with architecture context loading
+4. Session-level change counting (deferred—out of scope for ticket 003)

package/.safeword/planning/011-cli-ux-vision.md

@@ -0,0 +1,330 @@
+# CLI UX Vision: Safeword
+
+**Status:** 🟢 Complete
+
+---
+
+## Philosophy
+
+- **Natural language** — Commands read like sentences
+- **Progressive discovery** — Capabilities via `--help`
+- **No modes** — Stateless commands
+- **npx-first** — Always latest
+- **Dual-audience** — Human + LLM readable
+
+---
+
+## Decisions
+
+| Decision             | Choice                                         |
+| -------------------- | ---------------------------------------------- |
+| Package              | `safeword`                                     |
+| Setup cmd            | `setup` (not `init`)                           |
+| Bare cmd             | Show help                                      |
+| Errors               | Medium verbosity                               |
+| Versions             | Coupled (project = CLI)                        |
+| Downgrade            | Refuse                                         |
+| Hooks                | `$CLAUDE_PROJECT_DIR/.safeword/hooks/`         |
+| Skills               | Copy to `.claude/skills/safeword-*/`           |
+| Git hooks            | Marker-based append/remove                     |
+| Linting              | Full install + configure                       |
+| Linting failure      | Core failure, exit 1                           |
+| Existing config      | Error: "Run `safeword upgrade`"                |
+| Root file            | AGENTS.md only, **prepend** link               |
+| AGENTS.md check      | SessionStart hook verifies, re-adds if missing |
+| Offline check        | Graceful degradation                           |
+| Non-git              | Prompt (auto-skip with `--yes`)                |
+| Monorepo             | Root only                                      |
+| User edits           | Overwritten on upgrade                         |
+| Same-version upgrade | Force reinstall                                |
+| Partial fail         | Exit 0 + warnings                              |
+| Non-interactive      | Auto-TTY + `--yes`                             |
+| Skill conflict       | Overwrite silently                             |
+| Diff output          | Summary + `--verbose`                          |
+| Reset AGENTS.md      | Search exact string, remove                    |
+| Reset confirm        | Prompt (auto-confirm with `--yes`)             |
+| package.json         | Add lint/format scripts                        |
+
+---
+
+## Commands (v1)
+
+| Command            | Purpose                              |
+| ------------------ | ------------------------------------ |
+| `safeword`         | Show help                            |
+| `safeword setup`   | Initialize (full setup with linting) |
+| `safeword check`   | Health + versions                    |
+| `safeword upgrade` | Update project (always reinstalls)   |
+| `safeword diff`    | Preview changes                      |
+| `safeword reset`   | Remove (prompts for confirm)         |
+
+**Global Flags:**
+
+- `--version` — Show CLI version
+- `--help` — Show help
+
+**Command Flags:**
+
+- `--yes` — Accept defaults (no prompts)
+- `--verbose` — Detailed output (for `diff`)
+- `--offline` — Skip version check (for `check`)
+
+**Deferred:** `doctor` (v1.x)
+
+---
+
+## File Structure
+
+```
+.safeword/
+  SAFEWORD.md              # Core patterns
+  version                  # "1.2.0"
+  README.md                # "Managed by CLI"
+  hooks/
+  skills/
+  guides/
+  scripts/
+  prompts/
+  templates/
+
+.claude/
+  settings.json
+  skills/safeword-*/
+
+.git/hooks/
+  pre-commit               # If git repo
+
+AGENTS.md                  # With link prepended at top
+```
+
+---
+
+## Setup Flow
+
+1. Check for existing `.safeword/`
+   - If exists → Error: "Already configured. Run `safeword upgrade` to update."
+2. Detect project type (Next.js, React, TS, etc.)
+3. Copy templates to `.safeword/`
+4. Register hooks in `.claude/settings.json`
+   - Includes SessionStart hook to verify AGENTS.md
+5. Copy skills to `.claude/skills/safeword-*/`
+6. Install + configure linting
+   - Add `lint` and `format` scripts to package.json
+   - If fails → Exit 1 (core failure)
+7. Check for `.git/`
+   - TTY: Prompt — Initialize git?
+   - No TTY or `--yes`: Auto-skip with warning
+8. Prepend link to `AGENTS.md` (create if missing)
+9. Print summary
+
+---
+
+## Upgrade Flow
+
+1. Check `.safeword/version` exists
+   - If missing → Error: "Not configured. Run `safeword setup`."
+2. Compare versions (for display only)
+3. Overwrite all `.safeword/` files with CLI's templates
+4. Update `.claude/skills/safeword-*/`
+5. Update hooks if needed
+6. Update `.safeword/version`
+7. Print summary of changes
+
+**Note:** Always reinstalls, even if same version.
+
+---
+
+## Commands on Unconfigured Project
+
+| Command   | Behavior                                              |
+| --------- | ----------------------------------------------------- |
+| `check`   | Show "Not configured. Run `safeword setup`." (exit 0) |
+| `diff`    | Error: "Not configured." (exit 1)                     |
+| `reset`   | "Nothing to remove." (exit 0)                         |
+| `upgrade` | Error: "Not configured." (exit 1)                     |
+
+---
+
+## Non-Interactive Behavior
+
+**Auto-TTY detection:**
+
+- Terminal (TTY) → Show prompts
+- CI/pipe (no TTY) → Use defaults automatically
+
+**`--yes` flag:**
+
+- Force defaults even in terminal
+- Defaults: skip git init, auto-confirm reset
+
+---
+
+## Hooks
+
+**Claude Code:**
+
+- Append to `.claude/settings.json` arrays
+- Reference via `$CLAUDE_PROJECT_DIR/.safeword/hooks/`
+- Remove by path pattern
+
+**SessionStart hook** (new):
+
+- Checks if AGENTS.md still has safeword link
+- If missing, re-adds and alerts user
+
+**Git pre-commit:**
+
+- Marker-based: `SAFEWORD_ARCH_CHECK_START/END`
+- Append or create
+- Remove only between markers
+
+---
+
+## Skills
+
+- Source: `.safeword/skills/X/SKILL.md`
+- Destination: `.claude/skills/safeword-X/SKILL.md`
+- Overwrite silently (we own this namespace)
+
+---
+
+## Root File Strategy
+
+**Setup:**
+
+1. Create `.safeword/SAFEWORD.md`
+2. **Prepend** to `AGENTS.md` (create if missing):
+   ```markdown
+   **⚠️ ALWAYS READ FIRST: @./.safeword/SAFEWORD.md**
+   ```
+3. Check if link already exists (avoid duplicates)
+
+**SessionStart Hook:**
+
+- Verifies link still in AGENTS.md
+- If removed, re-adds and shows warning
+
+**Reset:**
+
+- Search for exact string in `AGENTS.md`
+- Remove the line
+
+**Note:** Only handles AGENTS.md, not CLAUDE.md. Prepend for LLM primacy effect.
+
+---
+
+## package.json Updates
+
+Setup adds these scripts:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  }
+}
+```
+
+Also adds devDependencies for ESLint/Prettier.
+
+---
+
+## Reset Flow
+
+1. Check `.safeword/` exists
+   - If missing → "Nothing to remove." (exit 0)
+2. Prompt: "This will remove safeword. Continue? [y/N]"
+   - With `--yes`: auto-confirm
+3. Remove `.safeword/`
+4. Remove safeword hooks from `.claude/settings.json`
+5. Remove safeword skills from `.claude/skills/`
+6. Remove git hook markers from `.git/hooks/pre-commit`
+7. Remove link from `AGENTS.md`
+8. Print summary
+
+**What reset leaves intact (by design):**
+
+- `lint`/`format` scripts in package.json
+- ESLint/Prettier devDependencies
+- `eslint.config.mjs`, `.prettierrc`
+
+**Rationale:** Linting config is useful independently. User may have customized. Standard CLI behavior is to leave configuration artifacts.
+
+---
+
+## Diff Command
+
+**Default:** Summary only
+
+```
+Changes from v1.0.0 → v1.2.0:
+
+Modified: 3 files
+  .safeword/SAFEWORD.md
+  .safeword/guides/testing-methodology.md
+  .safeword/hooks/auto-quality-review.sh
+
+Added: 1 file
+  .safeword/guides/zombie-process-cleanup.md
+```
+
+**With `--verbose`:** Full unified diff
+
+---
+
+## Version Check
+
+**Online (default):**
+
+```
+Safeword CLI: v1.2.0 (latest)
+Project config: v1.0.0 (v1.2.0 available)
+```
+
+**Offline/timeout:**
+
+```
+Safeword CLI: v1.2.0
+Project config: v1.0.0
+
+Note: Couldn't check for updates (offline?)
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning                             |
+| ---- | ----------------------------------- |
+| 0    | Success (may have warnings)         |
+| 1    | Failure (core functionality failed) |
+
+**Core failures (exit 1):**
+
+- Can't write to `.safeword/`
+- Linting install fails
+- Can't register hooks
+- `diff`/`upgrade` on unconfigured
+
+**Warnings (exit 0):**
+
+- Git hooks skipped (no git)
+- Version check failed (offline)
+- `reset` on unconfigured
+
+---
+
+## Output Design
+
+- Labeled values: `Project: v1.0.0`
+- Explicit status: `(v1.2.0 available)`
+- Symbols: `✓` `✗` `⚠`
+- Action blocks: `To fix: safeword setup`
+
+---
+
+## Related
+
+- [Ticket #005](../tickets/005-cli-implementation.md)
+- [Implementation Plan](../../docs/001-cli-implementation-plan.md)