Skip to content

docs(OMN-15199): slim CLAUDE.md to the proven root pattern (42,089 -> 19,988 bytes) - #817

Merged
jonahgabriel merged 1 commit into
devfrom
jonah/omn-15199-slim-claude-md
Jul 26, 2026
Merged

jonahgabriel merged 1 commit into
devfrom
jonah/omn-15199-slim-claude-md

Conversation

@jonahgabriel

@jonahgabriel jonahgabriel commented Jul 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Closes OMN-15199 (epic OMN-15197). Slims omniintelligence/CLAUDE.md end to end using the proven root-pattern method (omni_home root 64,334 → 30,766; canary OMN-15198 omnibase_infra 43,049 → 18,136, PR omnibase_infra#2482): delete drift-prone state, delete content duplicated from the always-loaded root CLAUDE.md, delete generic advice, replace procedure and illustrative snippets with pointers at real code.

42,089 → 19,988 bytes (target was ~24,000; every cut is justified below).

No GENERATED block exists in this file (verified: no markers, no script in the repo writes CLAUDE.md).

KEEP contract — live-verified before preservation (8/8 checked, 2 corrected)

Every KEEP item from the survey was verified against source before being preserved. Two were live-false and are corrected, not preserved:

# KEEP item Verdict Evidence
1 Fingerprint ordering risk (missing idempotency_records at first boot ⇒ poisoned auto-stamp ⇒ later boots fail with SchemaFingerprintMismatchError) CORRECTED — stale runtime/plugin.py B1.5 _check_cross_repo_tables (OMN-3531) raises RuntimeHostError with the provisioning command when the table is absent, before B2 runs; the B2 first-boot auto-stamp additionally aborts when live table count < manifest count. The poisoned-fingerprint scenario is defended twice; the migrations-first invariant is kept with the corrected failure mode
2 AdapterPatternStore ignores conn; each method is an independent transaction TRUE — repositories/adapter_pattern_store.py (one-time warning logged, param ignored) kept
3 wire_dispatchers() before start_consumers() — no dispatch engine = no consumers TRUE — start_consumers returns skipped when _dispatch_engine is None; also raises if handshake not validated kept
4 Effect nodes never block on Kafka; optional producer, skip/log when absent TRUE — producer is not None guards across effect handlers; contracts declare required: false kept
5 4th protocol for same resource ⇒ refactor existing first TRUE — protocols verified at protocols/__init__.py + node handler modules kept
6 store_with_version_transition() for atomic version transitions TRUE — adapter_pattern_store.py:564, declared in learned_patterns.repository.yaml kept
7 API module internal-only, no auth, network-topology restricted TRUE — no auth dependency in api/; Depends used only for DI kept
8 Hook status: UserPromptSubmit + Stop ACTIVE; SessionStart/SessionEnd/PreToolUse/PostToolUse DEFERRED; Notification IGNORED CORRECTED — stale handler_claude_event.py routes POST_TOOL_USE and POST_TOOL_USE_FAILURE to handle_post_tool_use(), which persists to agent_actions (OMN-2984) and degrades to no-op when no repository is injected. PostToolUse is ACTIVE, not DEFERRED

Additional corrected false claims found during verification:

  • The "Enforcement (CI/Audit)" table cited tests/audit/test_io_violations.py for four rules — that file does not exist. Purity is enforced by tests/unit/test_node_purity.py (AST purity validator, OMN-1140), whose actual rules differ (interface methods allowed, stub nodes excluded, no line-count check). Corrected.
  • -m audit was described as "I/O purity enforcement (AST checks)" — tests/audit/ now contains model-type-safety and pattern-status audits; purity lives under -m unit. Corrected.
  • Snippet line counts (~22/~35/~40) were stale (real files: 47/82/103 lines) — moot after replacing snippets with pointers.

Where each deleted section landed

  • 3 illustrative node snippets → pointers to the real exemplar files (node_quality_scoring_compute/node.py, node_claude_hook_event_effect/node.py, node_pattern_promotion_effect/node.py)
  • Contract YAML full example (~2.7KB) → pointer at a real contract.yaml + one-paragraph key inventory
  • RuntimeHostProcess boilerplate + anti-pattern table (~4KB) → compressed prose + pointer at omnibase_infra/src/omnibase_infra/runtime/runtime_host_process.py (core-owned architecture)
  • "Key topics" table + Testing-section subscribe/publish tables + duplicated hook/DLQ/correlation blocks → docs/reference/EVENT_SURFACE.md (the file's own stated source of truth; tables were self-contradicting that rule)
  • EnumIntelligenceOperationType operations table → pointer at enums/enum_intelligence_operation_type.py; FSM flows → enums/enum_fsm.py
  • Repository operations table → pointer at repositories/learned_patterns.repository.yaml
  • Hardcoded node counts (60/59) → pyproject.toml [project.entry-points."onex.nodes"] + docs/reference/NODE_INVENTORY.md
  • Handler/protocol/mock code snippets, Key Dependencies table → provably redundant with the source files they quoted (pyproject.toml, handler dirs, tests/conftest.py)
  • Drift-prone dispatch counts ("31 handlers / 40 routes", "14 modules") → dropped in favor of dispatch_handler_*.py glob description

Companion doc coherence: docs/reference/EVENT_SURFACE.md and docs/INDEX.md no longer cite "CLAUDE.md topic tables" as a verification source (contract YAML is the single source).

dod_evidence

  • Bytes: 42,089 → 19,988 (wc -c CLAUDE.md at 6ab20bc); target ≤ ~24,000 met
  • KEEP contract: 8/8 live-verified against source; 2 corrected with file-level evidence (above) per the survey's stale-fact-vector protocol
  • No new per-repo/per-branch state assertions introduced; drift-prone facts replaced with the file/command that regenerates them
  • Gates: pre-commit run --files CLAUDE.md docs/INDEX.md docs/reference/EVENT_SURFACE.md — all hooks Passed/Skipped(no files) on .200 (Stickybeatz-Studio); docs-only diff, no Python changes
  • Edit-locality: edited locally, patch-transferred to .200, sha256-verified identical (c4ba8adc… CLAUDE.md, 48aa4b7f… docs/INDEX.md, 2af75ee9… docs/reference/EVENT_SURFACE.md), committed and pushed from .200
  • Worktree: $OMNI_HOME/omni_worktrees/OMN-15199/omniintelligence, branched from origin/dev @ 287f001 (workspace rule 9 respected)

Evidence-Ticket: OMN-15199
Evidence-Source: OCC#5012

… 19,988 bytes)

Apply the root-pattern slimming method: delete drift-prone state and
duplicated topic tables (EVENT_SURFACE.md is the source of truth),
replace illustrative code snippets with pointers to the real exemplar
files, compress procedure to pointers at code, and correct two
live-false claims (fingerprint auto-stamp poisoning is now defended by
the B1.5 pre-check + auto-stamp abort; PostToolUse hook is ACTIVE via
OMN-2984, not DEFERRED). Purity enforcement corrected to
tests/unit/test_node_purity.py (tests/audit/test_io_violations.py no
longer exists).
@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 07aec0f3-349c-490a-857a-2ad7861f348d

📥 Commits

Reviewing files that changed from the base of the PR and between 287f001 and 6ab20bc.

📒 Files selected for processing (3)
  • CLAUDE.md
  • docs/INDEX.md
  • docs/reference/EVENT_SURFACE.md
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch jonah/omn-15199-slim-claude-md

Comment @coderabbitai help to get the list of available commands.

@jonahgabriel
jonahgabriel merged commit f14e18d into dev Jul 26, 2026
52 of 55 checks passed
@jonahgabriel
jonahgabriel deleted the jonah/omn-15199-slim-claude-md branch July 26, 2026 20:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant