KeiSeiKit-1.0/docs/RULES-AS-BLOCKS.md

Rules-as-Blocks — Wave 14 Architectural Note

Status: infrastructure landed 2026-04-30 (Wave 14a + 14b). Manifest migration is per-install — public release ships with rule_blocks = [] (default empty) on every manifest.

What this enables

Treat user-defined rule files as composable substrate fragments. Each agent manifest declares which rule fragments it needs. The assembler injects them at build time, alongside existing substrate blocks.

This unifies two previously-separate concepts:

• Substrate blocks (_blocks/*.md) — composed by _assembler from manifest's blocks = [...] field
• Rules (user's ~/.claude/rules/*.md) — previously global umbrella, loaded for every session regardless of agent

After Wave 14, rules are first-class blocks with their own DNA and per-agent selection.

Pipeline

~/.claude/rules/*.md
  │
  │  kei-decompose decompose-rules
  ▼
~/.claude/registry.sqlite
  blocks(block_type='rule', name='<rule-slug>::<section-slug>',
         scope_sha8=sha8(rule-slug), body_sha8=sha8(body))
  │
  │  _assembler reads manifest
  ▼
_manifests/<agent>.toml
  rule_blocks = ["karpathy-behavioral::1-think-before-coding",
                 "code-style::code-style-constructor-pattern", ...]
  │
  │  assembler composes
  ▼
agents/<agent>.md
  ┌─────────────────────────────────┐
  │ frontmatter (name, tools, model)│
  │ ROLE                            │
  │ role-section (capabilities)     │
  │ <!-- RULE: karpathy::think... -->│
  │ <fragment body verbatim>        │
  │ <!-- RULE: code-style::... -->  │
  │ <fragment body verbatim>        │
  │ blocks (existing substrate)     │
  │ footer                          │
  └─────────────────────────────────┘

Step-by-step migration (for a user's install)

1. Decompose your rules into fragments

kei-decompose decompose-rules
# → Decomposed N rule files into M fragments (M new, 0 superseded, 0 unchanged)

This walks ~/.claude/rules/*.md (and specialty/*.md + projects/*.md), splits each on ## H2 headings, and registers each section as a BlockType::Rule row in ~/.claude/registry.sqlite.

Re-running is idempotent: unchanged bodies are no-ops; changed bodies create supersede chain entries.

2. List available fragments

sqlite3 ~/.claude/registry.sqlite \
  "SELECT name FROM blocks WHERE block_type='rule' ORDER BY name"

Output is <rule-slug>::<section-slug> per line.

3. Pick fragments per agent category

Suggested mapping for the 37 ship manifests (refine to your rules corpus):

Agent category	Suggested rule_blocks
Universal (all agents)	karpathy-behavioral::*, code-style::*, numeric-claims-evidence::*
code-implementer- (rust/swift/python/go/flutter/typescript)	+ dev-workflow::*, git-conventions::*, debugging::*, agent-git-model::*, orchestrator-branch-first::*, shipped-vs-functional::*
ml-implementer, ml-researcher	+ ml-protocol::*, math-first-gate::*, observable-classification::*, manifold-tangent-sanity::*, pre-registration::*, specialized-node-training::*
security-auditor- (differential/supply-chain/variant)	+ security::*, secrets-single-source::*, no-downgrade-constructive::*
critic- (anti-pattern/bug/perf/tech-debt)	+ debugging::*
infra-implementer- (cicd/container/iac/secrets)	+ dev-workflow::*, git-conventions::*, secrets-single-source::*, api-cost-guard::*
researcher- (code/web/hybrid)	minimal — universal only + numeric-claims-evidence::*
validator- (api/benchmark/code-reality/doc/version)	minimal — universal only
architect	+ code-style::*, dev-workflow::*, debugging::*, no-downgrade-constructive::*
modal-runner, fal-ai-runner, cost-guardian	+ api-cost-guard::*

* means "all fragments under that rule slug". You can also be precise by listing each section explicitly:

rule_blocks = [
    "karpathy-behavioral::1-think-before-coding",
    "karpathy-behavioral::2-surgical-changes",
    "karpathy-behavioral::3-goal-driven-execution",
    "code-style::code-style-constructor-pattern",
    "numeric-claims-evidence::the-rule",
]

4. Edit _manifests/<agent>.toml files

Add the field next to existing blocks = [...]:

substrate_role = "edit-local"
blocks = [
    "baseline",
    "evidence-grading",
    ...
]
rule_blocks = [
    "karpathy-behavioral::1-think-before-coding",
    "code-style::code-style-constructor-pattern",
]

#[serde(default)] means manifests without the field still work — no breakage during gradual migration.

5. Re-run the assembler

cd path/to/KeiSeiKit-public
./_assembler/target/release/assemble  # or `cargo run -p agent-assembler`

Generated .md files now contain <!-- RULE: ... --> markers around each injected fragment, between the substrate-role section and the existing blocks injection.

6. Verify

grep -c "RULE:" agents/code-implementer-rust.md
# → number of rule fragments injected

Why this is better than the umbrella CLAUDE.md approach

Before Wave 14:

• All agents got the FULL rule corpus via global CLAUDE.md umbrella loading
• Explore (read-only) saw specialized-node-training.md (irrelevant)
• ml-implementer saw patents.md (irrelevant)
• No way to deduplicate _blocks/baseline.md (which summarizes rules) vs full rule files
• Token waste, signal dilution

After Wave 14:

• Each agent sees ONLY rule fragments in its rule_blocks list
• DNA-level identity per fragment enables supersede tracking + caching
• Same composition mechanism for substrate blocks AND rule blocks
• Public _blocks/ remains the public substrate layer; user's ~/.claude/rules/ becomes the user's per-install overlay

Technical references

• Parser: _primitives/_rust/kei-decompose/src/parsers/rule.rs
• CLI: _primitives/_rust/kei-decompose/src/rules_cmd.rs (subcommand decompose-rules)
• Registry: _primitives/_rust/kei-registry/src/block.rs (BlockType::Rule)
• Assembler injection: _assembler/src/assembler.rs::write_rule_blocks
• Validator: _assembler/src/rule_blocks_check.rs
• DNA wire format: _primitives/_rust/kei-shared/src/dna.rs::compose_dna

Migration progress in this repo

Public KeiSeiKit-public 1.0: ships with rule_blocks = [] on every manifest. Infrastructure ready, no opinionated default rules.

Per-user install: follow the steps above. kei-decompose decompose-rules is idempotent; manifest edits are forward-compatible.

Lock

2026-04-30 (Wave 14 a+b infrastructure). Wave 14c manifest migration is per-install (no canonical commits in public).