@northbridge-security/secureai 0.1.13

package/.claude/commands/architect/clean.md

@@ -0,0 +1,978 @@
+---
+description: Analyze code for Clean Architecture violations and propose refactorings
+argument-hint: [scope] [--strict] [--apply] [--compare]
+allowed-tools: Task, Read, Write, Bash
+---
+
+# Clean Architecture Analysis: $ARGUMENTS
+
+**Note**: Clean Architecture and KISS (Keep It Simple, Stupid) principles work together to improve code quality. Clean Architecture ensures proper separation of concerns and testability through interface-based boundaries and dependency injection, while KISS removes unnecessary complexity from the resulting architecture. Use `/architect:clean` to establish clean boundaries, then `/architect:kiss` to simplify implementation. See [KISS Analysis](./kiss.md) for complexity reduction.
+
+## Phase 0: Parse Arguments
+
+Extract from `$ARGUMENTS`:
+
+- **Scope**: Optional with smart defaults
+  - File path (e.g., `src/utils/auth.ts`) → Analyze specific file
+  - Directory path (e.g., `src/`) → Analyze all files in directory
+  - Pattern (e.g., `src/**/*.ts`) → Analyze matching files
+  - `--diff` or empty → Analyze git-changed files only
+- **--strict**: Fail if architecture violations are found
+- **--apply**: Apply suggested refactorings to worktree (requires review)
+- **--compare**: Compare with previous `.clean.local.md` report
+
+**Smart scope resolution:**
+
+```bash
+# If no scope provided or --diff flag
+if [[ -z "$SCOPE" ]] || [[ "$SCOPE" == "--diff" ]]; then
+  MODE="diff"
+  SCOPE=$(git diff --name-only origin/main...HEAD 2>/dev/null | grep -E '\.(ts|js|tsx|jsx)$')
+  echo "🔍 Analyzing git-changed files only"
+fi
+
+# If scope is a single file
+if [[ -f "$SCOPE" ]]; then
+  MODE="file"
+  echo "📄 Analyzing single file: $SCOPE"
+fi
+
+# If scope is a directory
+if [[ -d "$SCOPE" ]]; then
+  MODE="directory"
+  echo "📁 Analyzing directory: $SCOPE"
+fi
+
+# If scope is a pattern
+if [[ "$SCOPE" == *"*"* ]]; then
+  MODE="pattern"
+  echo "🔎 Analyzing pattern: $SCOPE"
+fi
+```
+
+## Phase 1: Launch Clean Architecture Agent
+
+Invoke a specialized Clean Architecture agent to perform analysis.
+
+**Agent invocation:**
+
+```typescript
+// Launch agent via Task tool
+await Task({
+  subagent_type: "general-purpose",
+  description: "Analyze Clean Architecture violations",
+  prompt: `Analyze the following scope for Clean Architecture violations:
+
+Scope: ${scope}
+Mode: ${mode}
+Strict mode: ${strictMode}
+Apply changes: ${applyChanges}
+
+Use Clean Architecture principles from docs/guides/agents.clean.arch.md to identify:
+1. Mixed business logic and system interactions
+2. Missing interfaces for external dependencies
+3. Hardcoded dependencies instead of dependency injection
+4. Missing *.system.ts naming convention for system files
+5. Coverage exclusion issues
+6. Architecture boundary violations
+7. Test coverage gaps from untestable code
+8. Folder organization issues (5+ related files not in module folder)
+
+Create a git worktree for proposed refactorings at: .worktree/clean-${timestamp}
+
+Report findings with:
+- Issue severity (critical, high, medium, low)
+- Specific code locations
+- Proposed refactorings with interface-based DI
+- File organization improvements
+- Worktree diff summary
+
+Return findings in structured format for review.`,
+});
+```
+
+**What the agent will do:**
+
+1. Read Clean Architecture principles from `docs/guides/agents.clean.arch.md`
+2. Identify code patterns violating clean architecture:
+   - **System interactions in business logic** (needs extraction to \*.system.ts)
+   - **Missing interfaces** (hardcoded dependencies)
+   - **Constructor without DI** (should accept dependencies)
+   - **Global singletons** (should use exported singleton pattern)
+   - **Test coupling** (unit tests requiring real system access)
+3. Create git worktree at `.worktree/clean-${timestamp}`
+4. Apply proposed refactorings in worktree:
+   - Extract interfaces for dependencies
+   - Create \*.system.ts files for system interactions
+   - Add dependency injection to constructors/functions
+   - Create mocks for testing
+   - Update test files to use mocks
+5. Generate diff and summary
+6. Report back with structured findings
+
+**Agent will NOT:**
+
+- Directly modify files in main working tree
+- Commit changes automatically
+- Push changes to remote
+- Delete any code without explicit permission
+- Change business logic behavior (only structure)
+
+## Phase 2: Review Agent Findings
+
+**Validate findings against Clean Architecture principles:**
+
+### 2.1 Parse Agent Report
+
+Extract from agent response:
+
+- **Violations found**: List of architecture violations with severity
+- **Worktree location**: Path to worktree with proposed refactorings
+- **Diff summary**: Overview of proposed changes
+- **Metrics**: Files refactored, interfaces created, coverage improvement
+
+### 2.2 Validate Refactorings
+
+Review the proposed refactorings:
+
+**Review checklist:**
+
+- [ ] Are interfaces properly defined? (Correct contract boundaries)
+- [ ] Is DI implemented correctly? (Constructor or parameter injection)
+- [ ] Are system files named correctly? (\*.system.ts suffix)
+- [ ] Do mocks follow naming convention? (tests/mocks/\*-mock.ts)
+- [ ] Is coverage configuration updated? (\*_/_.system.ts exclusion)
+- [ ] Are tests updated to use mocks? (No real system calls)
+- [ ] Does refactoring preserve behavior? (No logic changes)
+
+**If issues found in agent's recommendations:**
+
+```text
+Agent proposed interface IUserAPI but it's too broad (God interface).
+→ Request agent to split into focused interfaces
+
+Agent suggested *.system.ts but file contains business logic.
+→ Request agent to separate business logic from system calls
+
+Agent created mock but it doesn't implement interface correctly.
+→ Request agent to fix mock implementation
+```
+
+### 2.3 Request Refinements (if needed)
+
+If issues identified with agent's recommendations:
+
+```typescript
+// Re-invoke agent with feedback
+await Task({
+  subagent_type: "general-purpose",
+  description: "Refine Clean Architecture analysis",
+  prompt: `Review and refine previous analysis based on feedback:
+
+Previous findings: [agent report]
+
+Feedback:
+${feedback}
+
+Update worktree with refined refactorings and report back.`,
+});
+```
+
+Repeat until analysis quality is satisfactory.
+
+## Phase 3: Generate Clean Architecture Report
+
+**Create `.clean.local.md` with comprehensive findings:**
+
+````markdown
+# Clean Architecture Analysis Report
+
+**Generated:** [timestamp ISO]
+**Scope:** [analyzed scope]
+**Mode:** [file | directory | pattern | diff]
+**Worktree:** `.worktree/clean-[timestamp]`
+**Agent:** general-purpose
+**Reviewed by:** Claude Code
+
+---
+
+## Executive Summary
+
+**Total Violations:** [count]
+
+- 🔴 Critical: [count] (Blocking architecture issues)
+- 🟠 High: [count] (Significant testability problems)
+- 🟡 Medium: [count] (Minor improvements)
+- 🟢 Low: [count] (Nice-to-have)
+
+**Potential Impact:**
+
+- **Interfaces created:** [count]
+- **System files extracted:** [count] (\*.system.ts)
+- **Mocks created:** [count]
+- **Coverage improvement:** [percentage]% ([count] lines now testable)
+- **Files refactored:** [count]
+
+**Overall Assessment:** [summary]
+
+---
+
+## Detailed Findings
+
+### 🔴 Critical Violations (Must Fix)
+
+#### 1. [Violation Title] - [File:Line]
+
+**Category:** [Mixed Logic | Missing Interface | Hardcoded Dependency | System Naming | Coverage]
+
+**Severity:** Critical
+
+**Current Code:**
+
+```typescript
+// File: src/utils/auth.ts
+export async function authenticate(username: string): Promise<User> {
+  // System interaction mixed with business logic
+  const { stdout } = await execSync(`ldap-query ${username}`);
+  const user = JSON.parse(stdout);
+
+  // Business logic
+  if (!user.active) {
+    throw new Error("User inactive");
+  }
+
+  return user;
+}
+```
+
+**Problem:**
+
+- System interaction (`execSync`) mixed with business logic (user validation)
+- Cannot unit test without executing real LDAP queries
+- No interface for LDAP operations (hardcoded dependency)
+- File excluded from coverage unnecessarily
+
+**Proposed Solution:**
+
+**Interface:** `src/utils/ldap-interface.ts`
+
+```typescript
+export interface ILDAPClient {
+  queryUser(username: string): Promise<LDAPUser>;
+}
+```
+
+**System Implementation:** `src/utils/ldap.system.ts`
+
+```typescript
+import type { ILDAPClient, LDAPUser } from "./ldap-interface.js";
+import { execSync } from "node:child_process";
+
+export class LDAPClient implements ILDAPClient {
+  async queryUser(username: string): Promise<LDAPUser> {
+    const { stdout } = await execSync(`ldap-query ${username}`);
+    return JSON.parse(stdout);
+  }
+}
+
+export const defaultLDAP = new LDAPClient();
+```
+
+**Business Logic:** `src/utils/auth.ts` (refactored)
+
+```typescript
+import type { ILDAPClient } from "./ldap-interface.js";
+import { defaultLDAP } from "./ldap.system.js";
+
+export interface AuthDependencies {
+  ldap: ILDAPClient;
+}
+
+export async function authenticate(username: string, deps?: AuthDependencies): Promise<User> {
+  const ldap = deps?.ldap ?? defaultLDAP;
+
+  const user = await ldap.queryUser(username);
+
+  if (!user.active) {
+    throw new Error("User inactive");
+  }
+
+  return user;
+}
+```
+
+**Mock:** `tests/mocks/ldap-mock.ts`
+
+```typescript
+import type { ILDAPClient, LDAPUser } from "../../src/utils/ldap-interface.js";
+
+export class MockLDAPClient implements ILDAPClient {
+  private users = new Map<string, LDAPUser>();
+
+  setUser(username: string, user: LDAPUser): void {
+    this.users.set(username, user);
+  }
+
+  async queryUser(username: string): Promise<LDAPUser> {
+    const user = this.users.get(username);
+    if (!user) throw new Error(`User not found: ${username}`);
+    return user;
+  }
+}
+```
+
+**Test:** `tests/unit/auth.test.ts` (new)
+
+```typescript
+import { authenticate } from "../../src/utils/auth.js";
+import { MockLDAPClient } from "../mocks/ldap-mock.js";
+
+describe("authenticate", () => {
+  it("should reject inactive users", async () => {
+    const mockLDAP = new MockLDAPClient();
+    mockLDAP.setUser("john", { username: "john", active: false });
+
+    await expect(authenticate("john", { ldap: mockLDAP })).rejects.toThrow("User inactive");
+  });
+});
+```
+
+**Impact:**
+
+- **Testability**: Business logic now testable without LDAP access
+- **Coverage**: auth.ts now included in coverage (was previously excluded)
+- **Coverage improvement**: +45 lines testable (ldap.system.ts excluded, auth.ts included)
+- **Files created**: 3 (interface, system, mock)
+- **Tests enabled**: Can now write unit tests for auth logic
+
+**Location in worktree:** `.worktree/clean-[timestamp]/src/utils/`
+
+**Configuration update required:**
+
+```toml
+# bunfig.toml
+coveragePathIgnorePatterns = [
+  "**/*.system.ts",  # Excludes ldap.system.ts
+  # Remove: "src/utils/auth.ts" (now testable)
+]
+```
+
+---
+
+[Repeat for each critical violation]
+
+### 🟠 High Priority Violations
+
+[Same structure as critical]
+
+### 🟡 Medium Priority Violations
+
+[Same structure as critical]
+
+### 🟢 Low Priority Violations
+
+[Same structure as critical]
+
+---
+
+## Metrics Summary
+
+### Coverage Impact
+
+| Metric                  | Before  | After   | Improvement |
+| ----------------------- | ------- | ------- | ----------- |
+| Total lines covered     | [count] | [count] | +[delta]    |
+| Coverage percentage     | [pct]%  | [pct]%  | +[delta]%   |
+| Business logic testable | [count] | [count] | +[delta]    |
+| System files (excluded) | [count] | [count] | +[delta]    |
+
+### Refactoring Breakdown
+
+- **Interfaces created:** [count]
+- **System files extracted:** [count] (\*.system.ts)
+- **Mocks created:** [count]
+- **Business logic files refactored:** [count]
+- **Test files created/updated:** [count]
+- **Dependencies injected:** [count] classes/functions
+
+### Architecture Violations
+
+| Violation Type              | Count   | Resolved | Remaining |
+| --------------------------- | ------- | -------- | --------- |
+| Mixed business/system logic | [count] | [count]  | [count]   |
+| Hardcoded dependencies      | [count] | [count]  | [count]   |
+| Missing interfaces          | [count] | [count]  | [count]   |
+| Incorrect file naming       | [count] | [count]  | [count]   |
+| Untestable code             | [count] | [count]  | [count]   |
+
+---
+
+## Worktree Changes Overview
+
+**Worktree location:** `.worktree/clean-[timestamp]`
+
+**Files created:** [count]
+
+- Interfaces: [count]
+- System implementations: [count]
+- Mocks: [count]
+- Tests: [count]
+
+**Files modified:** [count]
+
+- Business logic refactored: [count]
+- Tests updated: [count]
+- Configuration: [count]
+
+**Lines added:** [count]
+**Lines removed:** [count]
+**Net change:** [±X] lines
+
+**Diff summary:**
+
+```diff
+src/utils/
++ ldap-interface.ts       # Interface definition
++ ldap.system.ts          # System implementation (excluded from coverage)
+~ auth.ts                 # Refactored with DI (now testable)
+
+tests/mocks/
++ ldap-mock.ts           # Mock for testing
+
+tests/unit/
++ auth.test.ts           # New unit tests
+
+bunfig.toml
+- src/utils/auth.ts      # Removed from coverage exclusion
+```
+
+**To review changes:**
+
+```bash
+# View full diff
+git -C .worktree/clean-[timestamp] diff HEAD
+
+# Compare specific refactoring
+git -C .worktree/clean-[timestamp] diff HEAD -- src/utils/
+
+# Browse worktree
+cd .worktree/clean-[timestamp]
+```
+
+---
+
+## Recommendations
+
+### Immediate Actions (Critical Violations)
+
+1. **Extract system interactions from [module]**
+   - Why: Business logic cannot be tested without real system access
+   - Impact: +[count] lines of testable code, +[percentage]% coverage
+   - Effort: [estimation] (interface + system file + mock + tests)
+
+2. **Add dependency injection to [class/function]**
+   - Why: Hardcoded dependencies prevent testing and violate DIP
+   - Impact: Enables unit testing with mocks
+   - Effort: [estimation]
+
+### Short-term Improvements (High Priority)
+
+[Same structure as immediate actions]
+
+### Long-term Enhancements (Medium/Low Priority)
+
+[Same structure as immediate actions]
+
+---
+
+## Next Steps
+
+You have several options for proceeding with these findings:
+
+### Option 1: Accept Worktree Changes
+
+Review and apply refactorings from the worktree:
+
+```bash
+# Review changes in worktree
+cd .worktree/clean-[timestamp]
+
+# Copy specific files back to main tree
+cp src/utils/ldap-interface.ts ../../src/utils/
+cp src/utils/ldap.system.ts ../../src/utils/
+cp src/utils/auth.ts ../../src/utils/
+
+# Or merge all changes
+git -C .worktree/clean-[timestamp] format-patch HEAD~1
+git am < .worktree/clean-[timestamp]/0001-*.patch
+
+# Update coverage configuration
+# (bunfig.toml and sonar-project.properties)
+
+# Run tests to verify
+bun test
+
+# Clean up worktree when done
+git worktree remove .worktree/clean-[timestamp]
+```
+
+### Option 2: Debate and Refine
+
+If you disagree with any refactorings:
+
+```text
+/architect:clean [scope] --compare
+
+Review the differences and provide feedback.
+Agent will be re-invoked with your feedback.
+```
+
+### Option 3: Convert to Tasks
+
+Create Task Master tasks for systematic refactoring:
+
+```text
+/task:add "Refactor auth module with Clean Architecture DI"
+  - Reference: .clean.local.md#auth-refactoring
+  - Priority: High
+  - Complexity: Medium
+
+/task:add "Create LDAP interface and system implementation"
+  - Reference: .clean.local.md#ldap-extraction
+  - Priority: High
+  - Complexity: Low
+```
+
+### Option 4: Convert to Bugs
+
+For critical architecture violations blocking development:
+
+```text
+/bug "Auth module mixed with system calls, untestable"
+  - Reference: .clean.local.md#auth-mixed-logic
+  - Priority: Critical
+  - Impact: Cannot unit test authentication logic
+
+/bug "Database module hardcoded, blocks testing"
+  - Reference: .clean.local.md#db-hardcoded
+  - Priority: High
+  - Impact: Integration tests slow, flaky
+```
+
+### Option 5: Staged Approach
+
+Combine approaches for large refactorings:
+
+1. **Week 1**: Fix critical violations (accept worktree changes for core modules)
+2. **Week 2**: Create tasks for high-priority refactorings
+3. **Week 3**: Update tests and verify coverage improvements
+4. **Week 4**: Review and document exceptions for low-priority items
+
+---
+
+## Comparison with Previous Report
+
+[Only if --compare used]
+
+### Changes Since Last Analysis ([date])
+
+**New violations identified:** [count]
+**Violations resolved:** [count]
+**Violations regressed:** [count]
+
+### Metric Trends
+
+| Metric              | Previous | Current | Trend |
+| ------------------- | -------- | ------- | ----- |
+| Coverage percentage | [pct]%   | [pct]%  | [↑↓→] |
+| Testable lines      | [count]  | [count] | [↑↓→] |
+| System files        | [count]  | [count] | [↑↓→] |
+| Interfaces          | [count]  | [count] | [↑↓→] |
+
+### Status Changes
+
+**Improved:**
+
+- [Violation that was fixed]
+
+**Regressed:**
+
+- [Violation that got worse]
+
+**New:**
+
+- [Newly identified violation]
+
+---
+
+## Analysis Configuration
+
+**Principles applied:**
+
+- Dependency Rule (dependencies point inward)
+- Interface-based boundaries
+- Dependency injection (constructor or parameter)
+- Testability first (unit vs integration)
+
+**Naming conventions:**
+
+- Interfaces: `I{Name}` (e.g., ILDAPClient)
+- System files: `*.system.ts` (e.g., ldap.system.ts)
+- Mocks: `tests/mocks/{name}-mock.ts`
+
+**Coverage patterns:**
+
+- Glob exclusion: `**/*.system.ts`
+- System files: Thin wrappers, no business logic
+- Business logic: Fully testable with mocks
+
+**Excluded paths:**
+
+- `node_modules/**`
+- `dist/**`
+- `**/*.test.ts`
+- `**/*.d.ts`
+- `**/*.system.ts` (system interactions)
+
+---
+
+## Agent Performance
+
+**Analysis time:** [duration]
+**Files analyzed:** [count]
+**Violations found:** [count]
+**Refactorings proposed:** [count] files
+
+**Agent effectiveness:**
+
+- True positives: [count/count] ([percentage]%)
+- False positives: [count] (refined by Claude Code)
+- Refactorings accepted: [count/count] ([percentage]%)
+
+---
+
+## References
+
+- **Clean Architecture Principles:** `docs/guides/agents.clean.arch.md`
+- **TypeScript Implementation:** `docs/guides/agents.clean.arch.ts.md`
+- **Command Documentation:** `docs/commands/architect/clean.md`
+- **KISS Analysis:** `docs/commands/architect/kiss.md` (Complementary complexity reduction)
+- **Worktree Location:** `.worktree/clean-[timestamp]`
+
+---
+
+**Report generated by:** General-Purpose Agent (reviewed by Claude Code)
+**Report location:** `.clean.local.md`
+**Execution time:** [total duration]
+````
+
+## Phase 4: Present Results to User
+
+### 4.1 Write Report to File
+
+```bash
+# Write report to .clean.local.md
+cat > .clean.local.md <<EOF
+[Generated report from Phase 3]
+EOF
+```
+
+### 4.2 Open in Editor
+
+```bash
+# Open report in VS Code
+code .clean.local.md
+```
+
+### 4.3 Console Summary
+
+Print concise summary to console:
+
+```text
+🏛️ Clean Architecture Analysis Complete
+
+Scope: [analyzed scope]
+Violations found: [total count]
+  🔴 Critical: [count]
+  🟠 High: [count]
+  🟡 Medium: [count]
+  🟢 Low: [count]
+
+Refactorings proposed:
+  - Create [count] interfaces
+  - Extract [count] system files (*.system.ts)
+  - Add [count] mocks for testing
+  - Improve coverage by [percentage]% (+[count] testable lines)
+
+Worktree created: .worktree/clean-[timestamp]
+Report: .clean.local.md (opened in editor)
+
+Next steps:
+  1. Review findings in .clean.local.md
+  2. Check worktree diff: cd .worktree/clean-[timestamp] && git diff HEAD
+  3. Choose action:
+     - Accept changes (copy from worktree)
+     - Debate findings (/architect:clean --compare)
+     - Convert to tasks (/task:add <description>)
+     - Convert to bugs (/bug <summary>)
+
+Questions?
+  - View all changes: git -C .worktree/clean-[timestamp] diff HEAD
+  - Review specific file: git -C .worktree/clean-[timestamp] show HEAD:[file]
+  - Remove worktree: git worktree remove .worktree/clean-[timestamp]
+```
+
+### 4.4 Interactive Prompts
+
+Ask user for next action:
+
+```text
+What would you like to do next?
+
+1. Review worktree changes in detail
+2. Accept all worktree changes
+3. Accept specific files from worktree
+4. Debate findings and refine
+5. Convert critical violations to tasks
+6. Convert critical violations to bugs
+7. Clean up worktree and exit
+
+Enter choice [1-7]:
+```
+
+**Handle user responses:**
+
+**Choice 1: Review worktree changes**
+
+```bash
+cd .worktree/clean-[timestamp]
+git diff HEAD --stat
+git diff HEAD
+```
+
+**Choice 2: Accept all worktree changes**
+
+```bash
+# Confirm with user first
+echo "⚠️  This will overwrite files in your main working tree."
+echo "   Worktree: .worktree/clean-[timestamp]"
+echo "   Files affected: [count]"
+read -p "Continue? [y/N] " confirm
+
+if [[ "$confirm" == "y" ]]; then
+  # Copy files from worktree
+  git -C .worktree/clean-[timestamp] diff --name-only HEAD | while read file; do
+    cp ".worktree/clean-[timestamp]/$file" "$file"
+  done
+  echo "✓ Changes applied. Review with 'git diff'"
+  echo "⚠️  Update bunfig.toml and sonar-project.properties coverage exclusions"
+fi
+```
+
+**Choice 3: Accept specific files**
+
+```bash
+# Show list of changed files
+echo "Select files to apply (space-separated indices):"
+git -C .worktree/clean-[timestamp] diff --name-only HEAD | nl
+read -p "Files: " selections
+
+# Copy selected files
+for idx in $selections; do
+  file=$(git -C .worktree/clean-[timestamp] diff --name-only HEAD | sed -n "${idx}p")
+  cp ".worktree/clean-[timestamp]/$file" "$file"
+  echo "✓ Applied: $file"
+done
+```
+
+**Choice 4: Debate findings**
+
+```bash
+echo "Which findings do you disagree with? (Reference by issue number from report)"
+read -p "Issue numbers: " issues
+echo "What are your concerns?"
+read -p "Feedback: " feedback
+
+# Re-invoke agent with feedback (Phase 2.3)
+```
+
+**Choice 5: Convert to tasks**
+
+```bash
+echo "Converting critical and high-priority violations to Task Master tasks..."
+
+# Parse critical violations from report
+# Create tasks using /task:add for each
+
+/task:add "Refactor [module] with Clean Architecture DI" \
+  --priority high \
+  --reference .clean.local.md#issue-1
+
+echo "✓ Created [count] tasks. View with /task:status"
+```
+
+**Choice 6: Convert to bugs**
+
+```bash
+echo "Converting critical violations to bugs..."
+
+# Parse critical violations from report
+# Create bugs using /bug for each
+
+/bug "Critical: [module] untestable due to mixed logic"
+# Reference: .clean.local.md#issue-1
+
+echo "✓ Created [count] bugs. View in .bugs.local.md"
+```
+
+**Choice 7: Clean up and exit**
+
+```bash
+echo "Cleaning up worktree..."
+git worktree remove .worktree/clean-[timestamp]
+echo "✓ Worktree removed. Report saved to .clean.local.md"
+```
+
+## Error Handling
+
+**Clean Architecture guide missing:**
+
+- Error: "❌ Cannot find docs/guides/agents.clean.arch.md. This file contains Clean Architecture principles for analysis."
+- Exit with status 1
+
+**No files in scope:**
+
+- Warning: "⚠️ No files found matching scope: [scope]"
+- Exit with status 0
+
+**Agent fails to respond:**
+
+- Error: "❌ Agent failed to complete analysis."
+- Show agent error message
+- Exit with status 2
+
+**Worktree creation fails:**
+
+- Error: "❌ Cannot create git worktree. Ensure git is available and working tree is clean."
+- Suggestion: "Run 'git status' to check for conflicts"
+- Exit with status 3
+
+**Git not available:**
+
+- Error: "❌ Git is required for worktree functionality."
+- Exit with status 4
+
+**Invalid comparison:**
+
+- Warning: "⚠️ --compare flag used but .clean.local.md not found. Cannot compare."
+- Continue without comparison
+
+## Exit Codes
+
+- 0: Analysis completed successfully
+- 1: Missing required files (Clean Architecture guide)
+- 2: Agent execution failure
+- 3: Worktree creation failure
+- 4: Git not available
+- 5: User canceled operation
+
+## Quick Reference
+
+**Common workflows:**
+
+```bash
+# Analyze specific module for refactoring
+/architect:clean src/utils/auth.ts
+
+# Analyze directory
+/architect:clean src/utils/
+
+# Before committing
+/architect:clean                    # Analyze git-changed files
+/architect:clean --strict           # Fail on violations
+
+# Review and refine
+/architect:clean --compare          # Compare with previous analysis
+
+# Apply changes
+/architect:clean --apply            # Create worktree and apply refactorings (requires review)
+```
+
+**Mode summary:**
+
+- File path → Analyze single file
+- Directory path → Analyze all files in directory
+- Pattern → Analyze files matching glob pattern
+- No scope / `--diff` → Analyze git-changed files only
+
+**Integration with existing workflows:**
+
+```bash
+# Option 1: Accept refactorings directly
+/architect:clean src/
+# Review .clean.local.md
+# Accept changes from worktree
+
+# Option 2: Convert to structured work
+/architect:clean src/
+# Review findings
+/task:add "Refactor auth with Clean Architecture"
+/bug "Critical: DB module untestable"
+
+# Option 3: Iterative refinement
+/architect:clean src/
+# Review and provide feedback
+/architect:clean src/ --compare  # Re-analyze with refinements
+```
+
+## Implementation Notes
+
+This command focuses on identifying and fixing Clean Architecture violations:
+
+**Key violations detected:**
+
+1. **Mixed business logic and system interactions**
+   - Business logic files containing file I/O, shell execution, network calls
+   - Solution: Extract to `*.system.ts` with interface
+
+2. **Hardcoded dependencies**
+   - Direct imports of concrete implementations
+   - Solution: Define interface, use DI
+
+3. **Missing dependency injection**
+   - Classes/functions with hardcoded dependencies
+   - Solution: Constructor or parameter injection with default
+
+4. **Incorrect file naming**
+   - System files not using `*.system.ts` suffix
+   - Solution: Rename and update imports
+
+5. **Coverage configuration issues**
+   - Business logic excluded from coverage
+   - System files not excluded
+   - Solution: Update glob patterns in bunfig.toml and sonar-project.properties
+
+6. **Poor folder organization**
+   - 5+ related files scattered with common prefix instead of in module folder
+   - Solution: Create module folder with index.ts for public API
+
+**Refactoring patterns applied:**
+
+- Interface-based boundaries (IService pattern)
+- Constructor-based DI with exported singleton
+- System file extraction (`*.system.ts`)
+- Mock creation (`tests/mocks/*-mock.ts`)
+- Test updates (use mocks instead of real systems)
+- Coverage configuration updates (glob patterns)
+- Module folder organization (5+ related files → `module/` folder)
+- Public API via `index.ts` re-exports
+
+**Clean Architecture layers:**
+
+```text
+Business Logic (inner)
+  ↓ depends on
+Interface (boundary)
+  ↑ implemented by
+System Implementation (outer) - *.system.ts
+```