codecruise 0.1.0

package/config/rules/decision-rules.md

@@ -0,0 +1,308 @@
+# Decision Rules
+
+Rules that determine what happens after a TODO is executed and scored.
+
+## Decision Flow
+
+```
+TODO Executed
+     ↓
+Verification (hooks capture real output)
+     ↓
+Scorecard Generated
+     ↓
+Decision Rules Applied
+     ↓
+Action: proceed | proceed_with_comment | retry | flag_for_human
+```
+
+## Score Calculation
+
+### Component Scores (0.0 - 1.0)
+
+**Quality Score:**
+```
+quality = 1.0
+quality -= 0.3 if lint.exit_code != 0
+quality -= 0.2 if typecheck.exit_code != 0
+quality -= 0.4 if tests.exit_code != 0
+quality -= 0.1 if tests.failed > 0
+quality -= 0.05 * lint.errors (capped at 0.2)
+quality = max(0, quality)
+```
+
+**Alignment Score:**
+```
+alignment = criteria_met / criteria_total
+alignment -= 0.1 * len(unexpected_files) (capped at 0.3)
+alignment = max(0, alignment)
+```
+
+**Guardrails Score:**
+```
+guardrails = 1.0
+guardrails = 0.0 if no_secrets violated
+guardrails -= 0.5 if no_new_deps violated (when set to block)
+guardrails -= 0.2 if atomic_commit violated
+guardrails = max(0, guardrails)
+```
+
+### Overall Score
+
+```
+overall = (quality * 0.4) + (alignment * 0.4) + (guardrails * 0.2)
+```
+
+**Weight rationale:**
+- Quality (40%): Tests and lint are critical
+- Alignment (40%): Doing what was asked matters equally
+- Guardrails (20%): Important but binary checks
+
+## Decision Rules
+
+### Rule 1: Proceed
+
+**Condition:**
+```
+overall >= profile.quality_threshold
+AND guardrails.no_secrets == true
+AND attempt <= profile.max_retries
+```
+
+**Action:**
+- Mark TODO as `done`
+- Commit changes
+- Update progress.yaml
+- Move to next TODO
+
+**Output:**
+```
+✓ todo-1.1b-004 | 3m24s | 1 attempt | abc1234
+  [████████████░░░░░░░░] 57% feature-1.1 (8/14) | quality: 0.91
+```
+
+### Rule 2: Proceed with Comment
+
+**Condition:**
+```
+overall >= (profile.quality_threshold - 0.1)
+AND overall < profile.quality_threshold
+AND guardrails.no_secrets == true
+```
+
+**Action:**
+- Mark TODO as `done` with flag
+- Commit changes with note
+- Add to review list
+- Move to next TODO
+
+**Output:**
+```
+⚠ todo-1.1b-004 | 3m24s | 1 attempt | abc1234
+  quality: 0.78 (below 0.85 threshold)
+  flagged: alignment score low - unexpected file touched
+  [████████████░░░░░░░░] 57% feature-1.1 (8/14)
+```
+
+### Rule 3: Retry
+
+**Condition:**
+```
+overall < (profile.quality_threshold - 0.1)
+AND attempt < profile.max_retries
+AND guardrails.no_secrets == true
+```
+
+**Action:**
+- Increment attempt counter
+- Analyze failure reason
+- Retry with context about what failed
+
+**Output:**
+```
+↻ todo-1.1b-004 | attempt 2/3
+  reason: tests failing (3/47 failed)
+  retrying with fix context...
+```
+
+### Rule 4: Flag for Human
+
+**Condition:**
+```
+attempt >= profile.max_retries
+OR guardrails.no_secrets == false
+OR user requested manual intervention
+```
+
+**Action:**
+- Pause execution
+- Present options to user
+- Wait for input
+
+**Output:**
+```
+✗ todo-1.2a-005 failed (3/3 attempts)
+
+  Last attempt:
+    quality: 0.45 | alignment: 0.70 | guardrails: 1.0
+    tests: 12 passed, 5 failed
+    lint: 3 errors
+
+  [r]etry    - Try one more time
+  [s]kip     - Mark as skipped, continue
+  [f]ix      - I'll fix manually, then continue
+  [a]bort    - Stop execution, save state
+  [d]etails  - Show full error output
+
+  Choice: _
+```
+
+## Special Rules
+
+### Secrets Detected (Immediate Block)
+
+**Condition:** `guardrails.no_secrets == false`
+
+**Action:**
+- NEVER commit
+- NEVER proceed
+- Immediately flag
+
+**Output:**
+```
+🚫 BLOCKED: Potential secret detected
+
+  File: src/config.ts
+  Line 23: const API_KEY = "sk-live-..."
+
+  This looks like a production API key.
+
+  Options:
+  [1] Remove secret and retry
+  [2] Add to .gitignore
+  [3] It's not a secret (override)
+
+  Choice: _
+```
+
+### Coverage Drop (Careful profile only)
+
+**Condition:**
+```
+profile == careful
+AND coverage_delta < -5%
+```
+
+**Action:**
+- Block commit
+- Require tests to be added
+
+**Output:**
+```
+⚠ Coverage dropped from 85% to 78%
+
+  Profile 'careful' requires maintaining coverage.
+
+  Options:
+  [1] Add more tests (recommended)
+  [2] Accept coverage drop (override)
+
+  Choice: _
+```
+
+### New Dependency Detected
+
+**When `no_new_deps: ask`:**
+```
+📦 New dependency detected: zod@3.22.0
+
+  This TODO added a new package.
+
+  [y] Approve and continue
+  [n] Remove and retry
+  [?] Why is this needed?
+
+  Choice: _
+```
+
+**When `no_new_deps: block`:**
+```
+🚫 New dependency blocked: zod@3.22.0
+
+  Profile 'careful' blocks new dependencies.
+
+  Options:
+  [1] Override for this TODO
+  [2] Retry without new dependency
+
+  Choice: _
+```
+
+## Error Analysis
+
+When retry is triggered, analyze the failure:
+
+### Test Failures
+
+```
+Analyzing test failures...
+
+  FAIL src/auth/login.test.ts
+    ✗ should return 401 for invalid password
+      Expected: 401
+      Received: 500
+
+  Likely cause: Error handling not implemented
+  Suggestion: Add try/catch in login handler
+
+Retrying with this context...
+```
+
+### Lint Errors
+
+```
+Analyzing lint errors...
+
+  error: 'user' is defined but never used (@typescript-eslint/no-unused-vars)
+  error: Missing return type on function (@typescript-eslint/explicit-function-return-type)
+
+Retrying with fixes...
+```
+
+### TypeScript Errors
+
+```
+Analyzing TypeScript errors...
+
+  error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'
+    src/utils/calc.ts:15:23
+
+  Likely cause: Type mismatch in function call
+
+Retrying with type fix...
+```
+
+## Profile-Specific Behavior
+
+| Rule | ship-fast | balanced | careful |
+|------|-----------|----------|---------|
+| Proceed threshold | 0.70 | 0.85 | 0.95 |
+| Proceed with comment | 0.60-0.70 | 0.75-0.85 | 0.85-0.95 |
+| Retry threshold | <0.60 | <0.75 | <0.85 |
+| Max retries | 2 | 3 | 3 |
+| Default on_error | skip | ask | ask |
+| Coverage required | No | No | Yes (80%) |
+
+## Integration
+
+These rules are applied in the SCORE phase of the execution loop:
+
+```
+1. TODO executed (code written)
+2. VERIFY phase (hooks capture output)
+3. Read .codecruise/verification/summary.json
+4. Calculate scores
+5. Apply decision rules (this file)
+6. Take action (proceed/retry/flag)
+7. Update scorecard and progress.yaml
+```

package/config/rules/hygiene.md

@@ -0,0 +1,247 @@
+# Code Hygiene & Cost Efficiency
+
+## Model Selection
+
+| Task | Model | Reason |
+|------|-------|--------|
+| `/status`, `/verify` | Haiku | Quick lookups |
+| `/task`, `/compact`, `/dashboard`, `/init` | Sonnet | Scoped implementation |
+| `/plan`, code review, planner agent, reviewer agent | Opus | Complex reasoning |
+| Explore subagent | Haiku | Fast research |
+| Mixed planning + execution | `opusplan` | Auto-switches (see below) |
+
+### The `opusplan` Model Alias
+
+Use `model: opusplan` for automatic switching:
+
+- **Plan mode active** → Uses Opus (complex reasoning)
+- **Execution mode** → Uses Sonnet (cost-effective)
+
+This is ideal for commands that do both planning and implementation.
+
+### Use Sonnet For
+
+- Scoped, well-defined tasks
+- Code generation with clear specs
+- File edits with specific instructions
+- Test writing
+- Documentation
+
+### Use Opus For
+
+- Complex reasoning across multiple files
+- Architectural decisions
+- Debugging subtle issues
+- Code review requiring deep analysis
+
+### Use Haiku For
+
+- Quick lookups (Explore subagent)
+- Simple transformations
+- Validation checks
+
+## MCP Management
+
+Context window protection is critical. Too many MCPs drain available context.
+
+### Limits
+
+- Configure: 20-30 MCPs total
+- Enable: <10 per project
+- Active tools: <80
+
+### Per-Project Configuration
+
+Use `disabledMcpServers` in project `.claude/settings.json`:
+
+```json
+{
+  "disabledMcpServers": [
+    "mcp-that-isnt-needed-for-this-project"
+  ]
+}
+```
+
+### Signs of MCP Overload
+
+- Claude forgetting recent context
+- Repeated questions about things already discussed
+- Slower responses
+- "Context limit" warnings
+
+### Fix
+
+1. Check enabled MCPs in settings
+2. Disable unused ones for current project
+3. Restart Claude Code after config changes
+
+## Context Management
+
+### Signs to Compact
+
+- 15+ exchanges in conversation
+- TODO completed
+- Switching to different feature
+- Context feels "fuzzy"
+
+### Before Compacting
+
+- Verify state persisted to files
+- Confirm `progress.yaml` updated
+- Commit any pending changes
+- Note next task in compact summary
+
+### Keep Context Lean
+
+- Use Explore subagent for research
+- Summarize findings, don't paste raw content
+- Reference files by path, don't include full contents
+- Delete outdated context
+
+## Response Style
+
+### Short Responses
+
+- Checklists over paragraphs
+- Diffs over full file contents
+- Tables for comparisons
+- Code blocks with highlights
+
+### Structured Output
+
+```markdown
+✓ TODO-003 complete
+
+Files modified:
+- src/auth/login.ts (added validation)
+- tests/auth/login.test.ts (3 tests)
+
+Quality: ✓ PASS
+Next: TODO-004 (session management)
+```
+
+## Git Hygiene
+
+### Git Attribution
+
+Never include in commit messages, PR titles, or descriptions:
+
+- "Claude", "AI", "Anthropic", "GPT", "LLM", "Copilot"
+- "Generated by", "Co-authored by AI", "AI-assisted"
+- Any AI tool attribution or signatures
+
+Write as if the human authored everything.
+
+### Commit Messages
+
+```
+type(scope): description
+
+body (optional - explain WHY, not WHAT)
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+Scope: feature or component name
+Description: imperative, lowercase, no period, max 50 chars
+
+### PR Titles
+
+```
+type(scope): description
+```
+
+Same format as commits. Examples:
+
+- `feat(auth): add password reset flow`
+- `fix(cart): resolve quantity update bug`
+
+### PR Descriptions
+
+```markdown
+## Summary
+Brief description of what this PR does (2-3 sentences max).
+
+## Changes
+- Bullet list of key changes
+- Focus on WHAT changed, not HOW
+
+## Testing
+- How to test these changes
+- Any edge cases to verify
+```
+
+### PR Rules
+
+- No AI attribution (see Git Attribution above)
+- No emojis in titles or commits
+- Link issues: `Closes #123` or `Fixes #123`
+
+### Atomic Commits
+
+- One logical change per commit
+- Tests with implementation
+- Don't mix refactoring with features
+
+### Branch Hygiene
+
+- Delete merged branches
+- Rebase feature branches on main
+- Squash WIP commits before merge
+
+## File Hygiene
+
+### Don't Commit
+
+- `node_modules/`
+- `.env` files (use `.env.example`)
+- Build outputs (`dist/`, `.next/`)
+- IDE settings (unless shared)
+- OS files (`.DS_Store`)
+
+### Keep Clean
+
+- Remove unused imports
+- Delete dead code
+- Update stale comments
+- Remove console.logs
+
+## Dependency Hygiene
+
+### Before Adding
+
+- Check bundle size impact
+- Review maintenance status
+- Consider native alternatives
+- Get approval for new deps
+
+### Regular Maintenance
+
+- Update patch versions
+- Review security advisories
+- Audit unused dependencies
+- Lock versions in production
+
+## Token Efficiency
+
+### In Prompts
+
+- Be specific about scope
+- Provide relevant context only
+- Use file paths, not full contents
+- Reference previous work
+
+### In Responses
+
+- Answer directly
+- Skip unnecessary preamble
+- Use formatting for clarity
+- Summarize long outputs
+
+### Cost Optimization
+
+1. **Use Explore subagent** for codebase research (preserves main context)
+2. **Reference files by path**, don't paste full contents
+3. **Summarize findings**, don't dump raw data
+4. **Batch related questions** in one exchange
+5. **Run /compact** after completing a TODO or 15+ exchanges
+6. **Use Memory MCP** to persist context across sessions (avoids re-reading)