How Moru Core Works · 7-Phase Lifecycle & 5-Wall Verification

From request intake (start) to KMP transcript verification on the first edit, SHA-256 file-hash binding (gate-batch), cryptographic review attestation (review), and final freshness checks (finish)—here is how Moru Core runs and verifies every line of code.

Enforced by runtime contracts, not prompt wishes.

From request intake (start) to KMP transcript verification on the first edit, SHA-256 file-hash binding (gate-batch), cryptographic review attestation (review), and final freshness checks (finish)—here is how Moru Core runs and verifies every line of code.

Seven phases from user prompt to verified commit.

An agent never jumps straight into editing random files. It first checks whether the request is settled, freezes a route manifest, isolates the smallest owner within 4 hops, edits under live PreToolUse guards, binds executable evidence to file hashes, passes structural review, and verifies final freshness.

Epistemic Readiness & Intake

Separates direct read-only questions, unshaped design/prose needing a quick sketch & alignment, and settled code targets.

  • Read-only questions answer statelessly without creating task state
  • Unshaped UX or prose aligns with a concrete 2–3 line sample before start
  • Settled code targets proceed directly to Phase 1

moru start (Admission & Manifest)

Verifies request fingerprint and effect ceiling (read to destructive), freezes required gates, and classifies required_docs.

  • Checks user approval binding for git_write and higher effects
  • Credits unchanged required_docs from same-session doc-takeaway.json
  • Runs baseline Moru Guard (VibeGuard) audit before any edit

4-Hop Owner & Worktree Isolation

Resolves the smallest code owner and nearest falsifying check within 4 hops, and protects main/develop checkouts.

  • Observable anchor → producer → direct usage → smallest owner + test
  • Blocks direct mutations on protected branches when worktree isolation applies
  • Binds task work to a dedicated branch or worktree

Implementation & Live PreToolUse Gate

Intercepts file-modifying tools on the first edit to verify skill-doc reading and block unauthorized mutations.

  • Scans live transcript.jsonl with KMP line matching on the first Edit/Write
  • Injects unread required_docs (≤8KB each, ≤24KB total) inline into hook context
  • Blocks file edits on read-only routes and premature git commit/push calls

Executable Evidence & gate-batch

Runs target tests, validates required gate schema fields, and binds SHA-256 hashes of covered source files.

  • Requires real command/result evidence—empty or prose-only claims fail
  • Snapshots input_paths file SHA-256 hashes into the run ledger
  • Prints a live Review Structure Preview warning if any block exceeds 120 lines

moru review (Structure & Attestation)

Audits diff scope, AST block sizes, boundary plans, doc links, and Moru Guard, then issues a cryptographic attestation.

  • Enforces ≤25 changed paths, ≤120 lines per block, and ≤300 added lines per file
  • Saves doc-takeaway.json so future runs in the session skip rereading
  • Writes review-workflow-validation.json bound to exact Git & rules hashes

moru finish & Commit Readiness

Cross-checks every route gate, verifies ReviewAttestation and file-hash freshness, and unlocks commit.

  • Invalidates any test or review gate if even 1 byte changed afterward
  • Rejects workspace drift on read-only routes and runs git diff --check
  • Confirms final Moru Guard Ready state before writing finish.json (SUCCESS)

Five independent walls that catch skipped rules, fake passes, and post-test edits.

Instead of trusting an agent's self-report at the end of a turn, Moru Core places five mechanical verification walls across the lifecycle. Each wall inspects a different layer of runtime state.

  • Request SHA-256 fingerprint
  • Effect floor & approval record
  • Baseline Moru Guard check
  • Protected checkout & worktree guard
  • First-edit KMP transcript check
  • Read-only route mutation block
  • Per-gate required field schema
  • input_paths file SHA-256 snapshot
  • 120-line block structure preview
  • ≤120L block / ≤300L added / ≤25 files
  • Boundary, side-effect & doc-link check
  • ReviewAttestation snapshot signing
  • ReviewAttestation signature verify
  • Post-test file SHA-256 re-verification
  • git diff --check & Moru Guard Ready

How Moru Core proves whether an agent actually read the required rules.

Loading 20+ rule files at session start wastes context, but merely asking an agent to 'read when needed' leads to skipped rules. Moru Core solves both with a 4-stage pipeline and KMP transcript verification.

SHA-256 + Takeaway Credit (94.2% Reused)

At start, agent_required_doc_reuse.py compares each required doc's (path, sha256, size_bytes) against prior runs in the same runtime session. If unchanged and credited in doc-takeaway.json, it is marked reused (0 bytes reloaded).

100% Contiguous Line Match in transcript.jsonl

The moment the agent calls Edit, Write, MultiEdit, or apply_patch, _read_in_context() scans live tool results after the last compact_boundary using the Knuth-Morris-Pratt (KMP) algorithm to verify every non-empty line of the doc appeared.

Automatic Context Injection When Unread

If an agent tries to edit without reading a required doc, delivery_text() injects the full text of unread docs (≤8KB each, ≤24KB total) directly into the PreToolUse hook response and records required-docs-delivered.json.

Compaction-Safe Summary Persistence

During review, --doc-takeaway records the applied rules into doc-takeaway.json so subsequent tasks in the same session reuse the rule without rereading the file.

First edit call runs while inline delivery attaches to the same turn

Because PreToolUse returns allow() with the injected document text rather than deny(), the very first edit payload executes immediately and the agent sees the injected rule text right after that tool call completes.

Oversized docs (>8KB) emit a path warning instead of inline injection

Documents larger than 8KB (or 24KB total) print a warning to read the file directly rather than flooding hook context, and runtimes without PreToolUse hooks rely on start manifest + review takeaway checks.

Why agents cannot fake a review pass or loop forever on a broken check.

Two cryptographic bindings keep the ledger honest, and a 4-branch failure classifier recovers from errors while stopping infinite token burn at 3 repair cycles.

Detects silent 1-byte edits after tests pass

When gate-batch records a passing test, it stores the SHA-256 hash of each covered file. At finish, Moru Core hashes the working tree again. Editing even a single character after running tests flips the SHA-256 digest and marks the gate Stale—while committing identical file contents keeps the hash valid.

Blocks forged 'review hook: SUCCESS' ledger entries

Agents cannot submit review hook via gate-batch. Only agent_review_hook.py can write review-workflow-validation.json with the exact Git status and rules snapshot. At finish, enforce_review_hook_attestation() strips any ledger entry whose cryptographic snapshot is missing or mismatched.

  • Phase
  • Moru Core Scripts
  • What It Verifies
  • On Failure