refactor: restructure CLAUDE.md into modular rules and per-directory files

[technicalpickles]

Summary

• Slims root CLAUDE.md from ~994 lines to 54 lines with routing table
• Adds .claude/rules/ for cross-cutting concerns (testing, security, development)
• Adds per-directory CLAUDE.md files for implementation details
• Updates .gitignore to track .claude/commands/ and .claude/rules/
• Updates constitution.md to reference routing table for doc updates
• Adds speckit commands to version control

Motivation

1. Context bloat - Claude loads ~994 lines regardless of relevance, triggering character warnings
2. Merge conflicts - Claude updates CLAUDE.md during work (Recent Changes, HTTP APIs, etc.), causing conflicts when pulling main
3. No routing - Claude didn't know where to put new learnings, defaulted to dumping in root CLAUDE.md

Solution

Component	Purpose
Root CLAUDE.md	~54 lines: essentials + routing table
.claude/rules/*.md	Cross-cutting concerns with paths: frontmatter
Per-directory CLAUDE.md	Deep implementation details, loaded contextually
CLAUDE.local.md	Gitignored volatile notes (branch-specific)

New Structure

CLAUDE.md                    # 54 lines - essentials + routing table
.claude/rules/
├── testing.md               # Path-scoped: *_test.go, tests/**
├── security.md              # Path-scoped: quarantine/**, isolation/**
└── development.md           # Always loaded: workflow, commits
cmd/mcpproxy/CLAUDE.md       # CLI details
cmd/mcpproxy-tray/CLAUDE.md  # Tray state machine
internal/oauth/CLAUDE.md     # OAuth flows
internal/httpapi/CLAUDE.md   # REST API
internal/server/CLAUDE.md    # MCP protocol
internal/runtime/CLAUDE.md   # Event bus, lifecycle
internal/upstream/CLAUDE.md  # 3-layer client
frontend/CLAUDE.md           # Vue/TypeScript

Test plan

• Start new Claude Code session in this branch
• Verify root CLAUDE.md loads (check with /memory)
• Work on a test file, verify testing.md rules load
• Work on OAuth code, verify internal/oauth/CLAUDE.md loads
• Verify no character limit warnings

Design doc

See docs/plans/2025-12-15-claude-md-restructure.md

[Dumbris]

Critic (Codex) review — technicalpickles's PR #202
Verdict: request_changes
Strengths: The PR decomposes the root CLAUDE.md into scoped rule and per-directory files, which directly addresses context bloat and merge-conflict pressure.
Findings:

• Merge-readiness is not established: the PR is still marked Draft and has an empty check rollup at head 906ec11e3febc671f0f8a8a8e7ec29fcb90f6032 (PR metadata: refactor: restructure CLAUDE.md into modular rules and per-directory files #202). The PR body also leaves the manual validation checklist unchecked. Convert out of draft and produce a current green CI/check signal before this can receive an accept verdict.
  Provenance check: ok

[Dumbris]

Critic (Codex) review — technicalpickles's PR #202
Verdict: request_changes
Head: 906ec11e3febc671f0f8a8a8e7ec29fcb90f6032

Strengths: The restructure has a clear goal: reduce root CLAUDE.md context load and route detailed guidance into path-specific files.

Findings:

1. Required verification is absent. gh pr checks 202 --watch=false reports no checks reported on the 'claude-md-restructure' branch, and the PR is still marked draft at refactor: restructure CLAUDE.md into modular rules and per-directory files #202. The pre-merge gate requires required checks to be green before an accept verdict; with no checks reported, this PR has no current CI evidence for the large instruction-file rewrite.

Provenance check: ok