Every rule that lived in the 410-line root CLAUDE.md maps to exactly one authoritative home below. This is the lossless-migration gate: no rule may be orphaned, and the home determines how it is enforced/recalled (per the "route by trigger shape" principle).
Homes: core = stays in the slim CLAUDE.md (outage-safe); hook = .claude/hooks/*.sh (edit-time); scan = scripts/pattern-validation.sh (adherence metric); doc = a conventions/*.md reference recalled via MCP-first + the SessionStart digest; knowledge = a guidance-*-tagged platform knowledge entry (created via create_knowledge), recalled cross-executor via search_knowledge — it reaches non-Claude executors, unlike the Claude-only SessionStart digest.
The doc/SessionStart digest is Claude-only. knowledge-home rules (guidance-* entries) are delivered to every executor — Grok/Codex/Gemini/etc. as well as Claude — through two model-agnostic seams that instruct the executor to run search_knowledge tag:guidance-* before implementing and honor applicable rules:
- Loop guardrails — the
guidance-*recall line inAi::DevLoop::CampaignDriver::DEFAULT_GUARDRAILS,Ai::DevLoop::AuditBacklogSeeder::GUARDRAILS, andAi::DevLoop::ImprovementPromotionService::GUARDRAILS, delivered in thedev_next_taskpayload to loop-driven executors. - Agent baseline —
Ai::Agent::BASE_GUARDRAILS, prepended into every agent's system prompt (build_system_prompt_with_profile) regardless of model/executor.
No file in docs/contributing/conventions/ and no global-scoped guidance knowledge entry may name a private extension (its Namespace::, extensions/private/<name> path, or import alias) or contain crypto/private-extension implementation specifics. Such guidance belongs in the extension's own docs or CLAUDE.local.md. Source-file enforcement is the blocking core-purity-check.sh hook, which derives the forbidden names dynamically from extensions/private/*.
| Rule (from old CLAUDE.md) | Home | Where | Enforcement |
|---|---|---|---|
| Project overview, core models, specialists | core | CLAUDE.md | — |
| Git rules (never commit unless asked, no AI attribution [ANY executor], branch/tag naming, staged commits) | core+knowledge | CLAUDE.md + guidance-git-conventions |
— (cross-executor recall) |
| Business submodule / core-mode note | core | CLAUDE.md | — |
| Permission-based access control (permissions not roles) | core+knowledge | CLAUDE.md + guidance-permissions-not-roles |
permission-not-roles-check.sh (nudge) + pattern-validation.sh (scan) |
| Frontend: colors / theme classes | doc+hook | frontend-patterns.md | hardcoded-color-check.sh + scan |
Frontend: no any |
doc+hook | frontend-patterns.md | no-any-type-check.sh + scan |
| Frontend: no console.log | doc+hook | frontend-patterns.md | console-log-check.sh + scan |
| Frontend: flat nav | doc+scan | frontend-patterns.md | pattern-validation.sh |
| Frontend: actions/state/imports | doc | frontend-patterns.md | review |
Backend: namespace ::, FK prefix, JSON lambda default, t.references index, class_name+foreign_key |
doc+hook | backend-patterns.md | ruby-convention-check.sh |
| Backend: frozen_string_literal | doc+hook | backend-patterns.md | ruby-syntax-check.sh + scan |
| Backend: render_success/error, Rails.logger, worker BaseJob | doc+scan | backend-patterns.md | pattern-validation.sh |
| Backend: controller size <300 | doc+hook | backend-patterns.md | controller-size-check.sh |
| Backend: webhook 200/202 (never 500) | core | CLAUDE.md | webhook-500-check.sh (nudge) |
| Backend: eager loading (.includes) | core | CLAUDE.md | n-plus-one-check.sh (nudge) |
| Backend: seeds, controllers Api::V1 | doc | backend-patterns.md | review |
| Cryptographic material safety (GENERIC principles) | core+knowledge | CLAUDE.md + guidance-crypto-material-safety + agent BASE_GUARDRAILS |
review (private specifics → CLAUDE.local.md) |
| Design principles (Stop&Ask, Test-First Bug Reproduction, etc.) | core | CLAUDE.md | — |
| Design: Verify / Completion Gate + Quality Gates (run the verification gate before reporting done) | core+knowledge | CLAUDE.md + guidance-verification-gate + loop guardrails |
scripts/validate.sh is the gate (specs + tsc + pattern-validation + gitleaks; pre-commit hook / any committer); /verify is a Claude-only wrapper |
| Design: dev-workflow governance (Audit=report, Surface Assumptions, Trace Changes, Plan Before Multi-File, Dead Reference Cleanup) | core+knowledge | CLAUDE.md + guidance-audit-report-only / guidance-surface-assumptions / guidance-trace-to-request / guidance-plan-before-multifile / guidance-dead-reference-cleanup (one bundled entry) + agent BASE_GUARDRAILS (audit-report-only, surface-assumptions only) |
— (cross-executor recall) |
| Design: Reuse First (discover before building; never greenfield) | core+knowledge | CLAUDE.md + guidance-reuse-first + agent BASE_GUARDRAILS |
— (cross-executor recall) |
| Architecture principles (Pull Never Push, Extension Isolation, Service Boundaries) | core+knowledge | CLAUDE.md + guidance-architecture-invariants |
core-purity-check.sh (isolation hook) + pattern-validation.sh extension-isolation scan mirror |
| Bulk operation safety (state the count, never batch-approve) | core+knowledge | CLAUDE.md + guidance-bulk-op-safety + agent BASE_GUARDRAILS + loop guardrails |
— (cross-executor recall) |
| Claude Fable 5 compliance (thinking always-on / no sampling params / no prefill / 30-day retention; refusal auto-reframe→Opus; effort from complexity; routing gated, default off) | doc+knowledge | fable5-compliance.md + guidance-fable5-compliance + agent BASE_GUARDRAILS + loop guardrails |
enforced in code (Ai::Llm::ModelCapabilities request builder, Ai::FableRouting toggle, Ai::Routing::EffortMapper); cross-executor recall via SessionStart digest + search_knowledge |
| Submodule safety | core+knowledge | CLAUDE.md + guidance-submodule-safety |
submodule-boundary-check.sh (hook) — process rules, no static scan |
| Terminology | core | CLAUDE.md | — |
| Worker architecture invariants (no jobs in server/, no sidekiq in server Gemfile) | core | CLAUDE.md | pattern-validation.sh |
Worker: AI-execution jobs MUST include AiSuspensionCheckConcern (kill-switch compliance) |
core+knowledge | worker/CLAUDE.md + guidance-kill-switch-compliance |
pattern-validation.sh (via scripts/checks/kill-switch-compliance-check.sh) |
| Service management + operations reference | doc | service-and-ops.md | — |
| Automation scripts | doc | service-and-ops.md | — |
| Test execution + multi-agent rules + patterns | doc | testing-patterns.md | — |
| MCP-first workflow (4 phases) | doc | mcp-first-workflow.md | SessionStart digest |
| MCP tool catalog | pointer | reference/auto/mcp-tools.md | auto-generated |
| Knowledge quality lifecycle + tool evolution | doc | knowledge-lifecycle.md | — |
| File organization (NEVER save to root) | core+knowledge | CLAUDE.md + guidance-file-organization |
pattern-validation.sh (no stray root files) |
| Key platform documentation (fallback table) | core | CLAUDE.md | — |
Verification: wc -l CLAUDE.md ≈ 150; no conventions/*.md references a private-extension namespace/alias/path (derive the name list from extensions/private/*); every row above resolves to an existing home.