Skip to content

Mistaber Encoding Plugin

The Mistaber Encoding Plugin is a comprehensive Claude Code plugin that provides a complete, supervised pipeline for encoding halachic content from traditional sources into the Mistaber formal reasoning system. It combines five specialized skills, seven enforcement hooks, and one orchestrating agent to ensure high-quality, traceable encodings with mandatory human review at every checkpoint.

Overview

The plugin transforms the complex, multi-step process of halachic encoding into a guided, checkpoint-based workflow that balances AI assistance with human expert oversight. Every encoding passes through structured phases: corpus preparation, HLL encoding, validation, review, and commit - each requiring explicit human approval before proceeding.

graph TD
    subgraph "Encoding Pipeline"
        A[corpus-prep] -->|Checkpoint 1| B[hll-encode]
        B -->|Checkpoint 2| C[validate]
        C -->|Checkpoint 3| D[review]
        D -->|Checkpoint 4| E[commit]
    end

    subgraph "Hook Enforcement"
        H1[session-init] -.-> A
        H2[phase-gate] -.-> B
        H3[encoding-guard] -.-> B
        H4[sefaria-logger] -.-> A
        H5[validation-handler] -.-> C
        H6[checkpoint-enforcement] -.-> D
        H7[git-commit-guard] -.-> E
    end

    subgraph "Agent Coordination"
        ORCH[encoding-orchestrator] --> A
        ORCH --> B
        ORCH --> C
        ORCH --> D
        ORCH --> E
    end

Plugin Components

Five Encoding Skills

Skill Purpose Checkpoint
corpus-prep Fetch sources from Sefaria, build derivation chains, identify machloket 1: Source Review
hll-encode Transform sources to HLL/ASP rules with world scoping 2: Rule Review
validate Compile rules, run semantic checks, execute tests 3: Test Review
review Generate comprehensive review package for human approval 4: Final Approval
commit Finalize encoding, create git commit, archive session None (Terminal)

Additionally, the workflow-guide skill provides comprehensive documentation of the entire encoding pipeline.

Seven Enforcement Hooks

Hook Event Purpose
session-init SessionStart Initialize encoding session, inject workflow context
phase-gate PreToolUse (Write/Edit) Prevent out-of-order writes to ontology files
encoding-guard PreToolUse (Write .lp) Validate HLL syntax and makor attribution
sefaria-logger PreToolUse (Sefaria MCP) Log all source fetches for traceability
validation-handler PostToolUse (Bash) Parse test results, update session state
checkpoint-enforcement Stop Warn about pending checkpoints on session end
git-commit-guard PreToolUse (Bash git) Require review approval before committing

One Orchestrating Agent

Agent Purpose
encoding-orchestrator Coordinates the complete encoding workflow, manages checkpoints, ensures human supervision

Key Features

Human-in-the-Loop Supervision

The plugin enforces mandatory human review at four critical checkpoints:

  1. Corpus Checkpoint: Before encoding begins, humans verify:
  2. Source text accuracy
  3. Commentary completeness
  4. Derivation chain validity

  5. Resolution of ambiguous questions

  6. Encoding Checkpoint: Before validation, humans verify:

  7. Predicate selection correctness
  8. World scoping accuracy
  9. Machloket representation

  10. Makor chain completeness

  11. Validation Checkpoint: Before final review, humans verify:

  12. All tests pass
  13. No regressions

  14. Machloket properly distinguished

  15. Review Checkpoint: Before commit, humans verify:

  16. Halachic accuracy checklist
  17. Technical accuracy checklist
  18. Interactive query testing

Complete Source Attribution

Every rule in the system maintains a complete makor/2 chain tracing back to authoritative sources:

% Example: Basar Bechalav eating prohibition
makor(r_bb_beheima_achiila, sa("yd:87:1")).
makor(r_bb_beheima_achiila, tur("yd:87")).
makor(r_bb_beheima_achiila, rambam("maachalot:9:1")).
makor(r_bb_beheima_achiila, gemara("chullin:104b")).
makor(r_bb_beheima_achiila, mishnah("chullin:8:1")).
makor(r_bb_beheima_achiila, torah("shemot:23:19")).

Multi-World Semantics

The plugin fully supports the Kripke world model for encoding disputes (machloket):

World Description Inherits From
base Universal rulings (all agree) -
mechaber Sefardi positions (Shulchan Arukh) base
rema Ashkenazi positions base
gra Vilna Gaon positions base
sefardi_yo Yalkut Yosef rulings mechaber
ashk_mb Mishnah Berurah rulings rema
ashk_ah Aruch HaShulchan rulings rema, gra

Sefaria Integration

Direct integration with Sefaria through MCP tools provides access to:

  • Primary source texts (Hebrew and English)
  • Multiple translation versions
  • Commentary texts (Shach, Taz, etc.)
  • Cross-references and links
  • Topic metadata
  • Dictionary definitions

Quick Start

Starting a New Encoding Session

User: "Prepare corpus for YD 87:3"

This invokes the corpus-prep skill, which:

  1. Validates the seif reference with Sefaria
  2. Fetches primary text (Hebrew + English)
  3. Fetches commentaries (Shach, Taz, etc.)
  4. Builds derivation chain
  5. Identifies machloket
  6. Generates review artifacts
  7. Requests human approval

Progressing Through Checkpoints

After each checkpoint approval:

User: "Approved - corpus looks correct"
Agent: [Proceeds to hll-encode skill]

User: "Approved - encoding is accurate"
Agent: [Proceeds to validate skill]

User: "Approved - tests all pass"
Agent: [Proceeds to review skill]

User: "Final approval granted"
Agent: [Proceeds to commit skill]

Using the Orchestrator Agent

For guided encoding:

User: "Let's encode YD 87:3"
Agent: [encoding-orchestrator activates and guides through entire pipeline]

Work Unit: Single Seif

The encoding pipeline processes one seif at a time, which is the natural unit of halachic codification:

  • Small enough for thorough human review
  • Large enough to be meaningful
  • Clear boundaries in source texts
  • Tractable validation scope

Example work units: - YD 87:1 (Beheima + Chalav prohibition) - YD 87:3 (Fish and Dairy - machloket) - YD 88:1 (Bitul in Basar Bechalav)

Artifact Management

Session Artifacts

During encoding, artifacts are stored in .mistaber-artifacts/:

Artifact Description
corpus-report-YD-{siman}-{seif}.md Human-readable corpus summary
corpus-sources-YD-{siman}-{seif}.yaml Machine-readable source data
corpus-chain-YD-{siman}-{seif}.mermaid Visual derivation chain
corpus-questions-YD-{siman}-{seif}.yaml Questions for human review
encoding-report-YD-{siman}-{seif}.md Encoding summary
encoding-mapping-YD-{siman}-{seif}.yaml Statement-to-rule mapping
validation-report-YD-{siman}-{seif}.md Test results summary
validation-results-YD-{siman}-{seif}.yaml Machine-readable results
test-scenarios-YD-{siman}-{seif}.yaml Generated test scenarios
review-package-YD-{siman}-{seif}.md Complete review package

Final Output

After commit, files are organized as:

mistaber/ontology/
├── corpus/
│   └── yd_{siman}/
│       ├── base.lp              # Shared definitions
│       └── manifest.yaml        # Siman metadata
├── worlds/
│   ├── mechaber.lp              # Mechaber-specific rules
│   ├── rema.lp                  # Rema-specific rules
│   └── ...
└── tests/
    └── yd_{siman}/
        ├── seif_{seif}_test.yaml
        └── seif_{seif}_metadata.yaml

Session State

Workflow progress is tracked in .mistaber-session.yaml:

current_phase: hll-encode
target_seif: "YD:87:3"
started: 2026-01-25T10:00:00Z
checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: 2026-01-25T10:30:00Z
  hll-encode:
    status: pending_review
    artifacts:
      - encoding-report-YD-87-3.md
      - encoding-mapping-YD-87-3.yaml
  validate:
    status: not_started
  review:
    status: not_started

Integration with Mistaber Engine

The plugin produces encodings compatible with the Mistaber engine:

from mistaber.engine import HsrsEngine
from pathlib import Path

engine = HsrsEngine(Path("mistaber/ontology"))

# Query the encoded rules
result = engine.analyze('''
    food(salmon). food_type(salmon, dag).
    food(cream). food_type(cream, chalav).
    mixture(m1). contains(m1, salmon). contains(m1, cream).
''', world="mechaber")

# Compare across worlds
comparison = engine.compare(
    "holds(sakana(M), W)",
    worlds=["mechaber", "rema"]
)

Next Steps