R76.P1 Contract — κ Rule Engine Phase 1 Deep Task Breakdown

Step 2 of 5. Supersedes draft planning: this contract binds Step 3 (packet) and Step 4 (implementation).

1. Outputs (binding)

1.1 New file — docs/guides/implementation/task-prompts/p1.1-kappa-rule-engine.md

A single Phase 1 prompt file covering the full κ Rule Engine, structured per the Phase 0 prompt-file convention (see p0.3-beta-task-pipeline.md and p0.5-delta-router.md for reference).

Must contain, in this order:

  1. Frontmatter with title, tags, type: agent-prompts, status: ready, phase: 1, round: R76, updated: 2026-04-18.
  2. Preamble citing: (a) task-breakdown.md §Phase 1 as canonical spec, (b) rule-engine.md as concept doc, (c) kappa-rule-engine-extraction.md as algorithm extraction, (d) roadmap.md Phase 1 start at R81, (e) agent-bootstrap + CLAUDE.md as execution rules.
  3. Group summary table — 5 groups × total 20 sub-tasks × depends-on × effort × unblocks.
  4. 20 sub-task sections, each containing:
    • Heading ## P1.<group>.<index> — <Title>
    • Spec source link to task-breakdown.md §P1.<group>.<index>
    • Extraction reference to kappa-rule-engine-extraction.md section(s)
    • Worktree name — feature/p1-<group>-<index>-<slug>
    • Branch command — git worktree add .worktrees/claude/...
    • Estimated effort — one of S / M / L / XL (per task-breakdown.md §”How to Read This Document”)
    • Depends on — prior sub-task IDs that must be done
    • Unblocks — subsequent sub-task IDs this one enables
    • Files to create — exact paths in src/domains/rules/ + tests
    • Acceptance criteria — bulleted checklist (checkbox-format), 4 to 10 items
    • Pre-flight reading — at minimum CLAUDE.md, task-breakdown.md §, rule-engine.md, extraction, any sibling prior sub-task outputs
    • Ready-to-paste agent prompt — fenced text block, self-contained (references CLAUDE.md §3/§5/§6/§7 inline)
    • Verification checklist — reviewer-facing bullet list
    • Writeback template — yaml block with task_update + thought_record fields per CLAUDE.md §7
    • Common gotchas — 2 to 4 bullets of executor warnings
  5. Footer linking back to index.md and forward to Phase 2 planning (TBD).

1.2 Edited file — docs/guides/implementation/task-breakdown.md §Phase 1

The existing Phase 1 section (lines 457–593 of the pre-edit file) is rewritten to match the 20-sub-task target shape. Specifically:

  • P1.1 — Integer Math Library: 2 existing → 3 sub-tasks (add P1.1.3 — BPS Constants + Overflow Protection).
  • P1.2 — DSL Parser: 3 existing → 4 sub-tasks (add P1.2.4 — Rule Loader / Registry).
  • P1.3 — Deterministic Interpreter: 3 existing → 4 sub-tasks (add P1.3.4 — Policy Gating / Pre-guards).
  • P1.4 — Admission Layer: net-new section with 4 sub-tasks (P1.4.1 Evaluator, P1.4.2 Denial Reason Taxonomy, P1.4.3 Budgets, P1.4.4 Tool-Lock Integration Spec).
  • P1.5 — Governance / Rule Versioning: existing “P1.4” (Rule Versioning) renumbers to this group; contents: P1.5.1 Version Hash (from old P1.4.1), P1.5.2 Rule Migration (from old P1.4.2), P1.5.3 Activation Epoch + Rollback (new), P1.5.4 Canonical Serialization (new), P1.5.5 Test Corpus Parity Harness (new).

Every sub-task retains the template fields: Depends on, Input, Output, Acceptance criteria, Effort. File-path prefixes are harmonized to src/domains/rules/... (from the old src/rules/...) — this is a convention alignment only; no code is touched.

1.3 Edited file — docs/guides/implementation/task-prompts/index.md

Add a new subsection below the Phase 0 task index titled ## Phase 1 Task Prompts, containing a single table row referencing p1.1-kappa-rule-engine.md with group count (1), sub-task count (20), and status planning (R76). Also add a forward pointer in the existing ## After Phase 0 section.

1.4 Chain docs (4) — docs/{audits,contracts,packets,verification}/r76-p1-kappa-planning-*.md

Standard 5-step chain artifacts; this file is the contract.

2. Scope bound — what this PR does NOT include

  1. No κ TypeScript code. Zero files under src/ are created or modified.
  2. No ADR changes. ADR-002 (VRF), ADR-005 (multi-model defer), ADR-006 (DSL grammar) are cited, not edited.
  3. No roadmap edits (R76.P3’s task).
  4. No δ planning (R76.P2’s task).
  5. No skill file edits. .agents/skills/ and .claude/skills/ remain untouched.
  6. No CLAUDE.md / AGENTS.md edits.
  7. No test additions or runs beyond the build + lint + jest no-op gate. Docs-only PR means Jest suite is expected to pass unchanged.

3. Template applied to every sub-task in the new prompt file

Each of the 20 sub-tasks gets a fully-fleshed block with this exact shape:

## P1.<G>.<N> — <Title>

**Spec source:** [task-breakdown.md §P1.<G>.<N>](../task-breakdown.md#p1<G><N>--<slug>)
**Extraction reference:** `docs/reference/extractions/kappa-rule-engine-extraction.md` §<section>
**Worktree:** `feature/p1-<G>-<N>-<slug>`
**Branch command:** `git worktree add .worktrees/claude/p1-<G>-<N>-<slug> -b feature/p1-<G>-<N>-<slug> origin/main`
**Estimated effort:** <S|M|L|XL>
**Depends on:** <P1.x.y list or "—">
**Unblocks:** <P1.x.y list or "Phase 2+">

### Files to create
- `src/domains/rules/<name>.ts`
- `src/domains/rules/__tests__/<name>.test.ts`

### Acceptance criteria
- [ ] … (4–10 items, testable)

### Pre-flight reading
- `CLAUDE.md` — worktree, gate, writeback rules
- `docs/guides/implementation/task-breakdown.md` §P1.<G>.<N>
- `docs/3-world/physics/laws/rule-engine.md`
- `docs/reference/extractions/kappa-rule-engine-extraction.md` §<section>
- <sibling prior sub-task outputs, when relevant>

### Ready-to-paste agent prompt

```text
You are a Phase 1 builder agent for Colibri (κ Rule Engine).

TASK: P1.<G>.<N> — <Title>
<One-sentence task description>

FILES TO READ FIRST:
1. CLAUDE.md (worktree rules §3, gate §5, 5-step chain §6, writeback §7)
2. docs/guides/implementation/task-breakdown.md §P1.<G>.<N>
3. docs/3-world/physics/laws/rule-engine.md
4. docs/reference/extractions/kappa-rule-engine-extraction.md §<section>
<5+. additional sibling context>

WORKTREE SETUP:
git fetch origin
git worktree add .worktrees/claude/p1-<G>-<N>-<slug> -b feature/p1-<G>-<N>-<slug> origin/main
cd .worktrees/claude/p1-<G>-<N>-<slug>

FILES TO CREATE:
- src/domains/rules/<name>.ts
  * <bullet list of functions + invariants>
- src/domains/rules/__tests__/<name>.test.ts
  * <bullet list of test categories>

ACCEPTANCE CRITERIA (headline):
<checkmark list>

SUCCESS CHECK:
cd .worktrees/claude/p1-<G>-<N>-<slug> && npm run build && npm run lint && npm test

WRITEBACK (after success, per CLAUDE.md §7):
task_update(id="P1.<G>.<N>", status="done", progress=100)
thought_record(session_id="r81-kappa-phase-1", thought_type="reflection",
  content="task_id: P1.<G>.<N>
branch: feature/p1-<G>-<N>-<slug>
worktree: .worktrees/claude/p1-<G>-<N>-<slug>
commit: <SHA>
tests: npm run build && npm run lint && npm test
summary: <what was done>
blockers: <residual risks or 'none'>")

FORBIDDENS:
✗ <task-specific forbiddens>
✗ Do not edit main checkout
✗ Do not skip any of build / lint / test (CLAUDE.md §5)

NEXT:
P1.<G>.<N+1> — <next sub-task title>

Verification checklist (for reviewer agent)

  • … (3–6 items, reviewer-facing)

Writeback template 

task_update:
  task_id: P1.<G>.<N>
  status: done
  progress: 100

thought_record:
  session_id: r81-kappa-phase-1
  task_id: P1.<G>.<N>
  branch: feature/p1-<G>-<N>-<slug>
  commit_sha: <sha>
  tests_run: ["npm run build", "npm run lint", "npm test"]
  summary: "<what was done>"
  blockers: []

Common gotchas

  • <2–4 bullets of executor warnings> ```

4. Invariants preserved across all prompts (from the κ concept doc)

  1. 64-bit signed integer math only. Every sub-task prompt calls this out in the FORBIDDENS section.
  2. Floor rounding for all division. Explicit in P1.1 / P1.3 prompts.
  3. Deterministic execution. Fuzz/property tests are mandatory acceptance items for every compute sub-task.
  4. Collect-then-apply mutation pattern. Called out in P1.3.1 and P1.4.1.
  5. AST cap of 10,000 nodes per rule. Acceptance item in P1.2.2 and P1.3.1.
  6. Forbidden operations enumerated. P1.2.3 (validator) and P1.4.1 (admission evaluator) cite the list.
  7. Chevrotain for lexer + parser. P1.2.1 and P1.2.2 pin this (per ADR-006).
  8. Rule version hash inputs to θ consensus and ι fork ids. P1.5.1 covers it.
  9. π governance parity requirement. P1.5.5 (Test Corpus Parity Harness) is named explicitly.

5. Acceptance criteria for R76.P1 itself

  • docs/guides/implementation/task-prompts/p1.1-kappa-rule-engine.md exists with frontmatter + preamble + group summary table + 20 sub-task sections + footer.
  • Each sub-task section contains all 10 required fields listed in §3 above.
  • docs/guides/implementation/task-breakdown.md Phase 1 section contains 20 sub-tasks across 5 groups (P1.1: 3, P1.2: 4, P1.3: 4, P1.4: 4, P1.5: 5) with no TBD placeholders.
  • docs/guides/implementation/task-prompts/index.md has a Phase 1 subsection listing the new file.
  • docs/audits/r76-p1-kappa-planning-audit.md, docs/contracts/r76-p1-kappa-planning-contract.md (this file), docs/packets/r76-p1-kappa-planning-packet.md, docs/verification/r76-p1-kappa-planning-verification.md all exist.
  • npm run build && npm run lint && npm test all green.

6. References bound into every sub-task prompt

Every one of the 20 prompts must cite at a minimum:

  • CLAUDE.md — for worktree, gate, chain, writeback rules.
  • docs/guides/implementation/task-breakdown.md — for the canonical spec row.
  • docs/3-world/physics/laws/rule-engine.md — for the concept and design invariants.
  • docs/reference/extractions/kappa-rule-engine-extraction.md — for algorithmic pseudocode.

Additional per-group references:

  • P1.2 sub-tasks: docs/architecture/decisions/ADR-006-dsl-grammar.md (Chevrotain ratification).
  • P1.3 sub-tasks: docs/spec/s11-rule-engine.md (authoritative rule engine spec).
  • P1.4 sub-tasks: docs/spec/s10-admission.md (authoritative admission spec).
  • P1.5 sub-tasks: docs/spec/s12-dsl.md (DSL spec) and docs/3-world/physics/enforcement/governance.md (π governance) when it exists.

Contract complete — proceed to packet.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.