Agent Construction with Relurpify on Relurpify

Chapter 1 — The Second Seam

Fri, 23 Oct 2026 17:23:43 +0000

# Chapter 1 — The Second Seam

Book 1 taught you to hire a line cook with a work permit. This book hands you the forge. By the last page you will have added a new kind of worker to the framework itself — a paradigm, declared in the same language the shipped ones speak, proved at every test layer the framework runs, and shaped into a contribution you could merge. You will never look at an agent framework the same way again. That is not a promise about your feelings; it is a promise about what you will be able to read.

Chapter 2 — Speak Model

Fri, 23 Oct 2026 18:00:40 +0000

# Chapter 2 — Speak Model

Last chapter ended with a leak. Asked to explain a function, the model answered in prose that looked like a tool call — {"thought":…,"action":"file_list","tool":"file_list",…} — and the runtime closed the run having done nothing. Four seconds, twenty-nine tokens, no work.

Here is the builder’s translation of that failure: the runtime never reads the model’s mind. It consumes a structured decision, and the decision was not structured. The seam between “what the model said” and “what the agent can act on” is a Go interface, it has six normative rules about streaming, and this chapter puts you on the implementing side of it. By the end you will have written a model — a scripted, deterministic, table-driven fake — that satisfies the same contract the Ollama transport satisfies, and every remaining chapter of this book will drive the critic through it.

Chapter 3 — The Lay of the Layering

Fri, 23 Oct 2026 18:02:23 +0000

# Chapter 3 — The Lay of the Layering

Every mature codebase has architecture rules. Most keep them in a diagram, and the diagram rots the first time someone merges against it. Relurpify keeps its rules in programs that run in CI and fail loudly — and in this chapter you learn to read them, break one on purpose, and feel how fast the law answers. By the end, make lint-arch stops being a ritual and becomes what it is: the fastest code review you will ever get.

Chapter 4 — Your First Graph

Fri, 23 Oct 2026 18:24:02 +0000

# Chapter 4 — Your First Graph

You own a model now — a scripted one that always says what it means. But a model alone is not an agent; it is a component. In this framework, an agent is a graph: typed nodes, wired by edges, executed as a deterministic state machine while a single envelope threads through. This chapter you build one with your own hands — implement the node interface before you meet the shipped nodes, build, seal, execute, break the wiring on purpose, and read your first preflight report.

Chapter 5 — Nodes That Govern Themselves

Fri, 23 Oct 2026 18:37:41 +0000

# Chapter 5 — Nodes That Govern Themselves

Last chapter you built a machine that runs. This chapter you build one that can be trusted — because its nodes carry their own government with them. In most frameworks, safety is a wrapper: a middleware that inspects your component from the outside and hopes it understands what it sees. Relurpify types governance into the node itself. A node does not merely do something; it declares what it will do, how often it may be done, where it prefers to run, and what recovery owes it — and the graph validates those declarations before a single node executes.

Chapter 6 — Parallel Boards and Retrieved Context

Fri, 23 Oct 2026 18:53:54 +0000

# Chapter 6 — Parallel Boards and Retrieved Context

Two critics are better than one — if they are independent, if their verdicts reach you without overwriting each other, and if you can say exactly which critic said what. That is a concurrency problem with a governance flavor, and the graph runtime has an opinion about how it should go: branches run against immutable snapshots of the graph and clones of the envelope, and their changes merge in edge-declaration order, with conflicts recorded rather than rejected. This chapter you build the ensemble, wire the retrieval and streaming seams, and — the milestone — run the whole thing as a program. Part II ends with a working, hand-composed critic pipeline in Go that you can execute from a shell.

Chapter 7 — Contracts Are the DSL

Fri, 23 Oct 2026 20:37:38 +0000

# Chapter 7 — Contracts Are the DSL

Your pipeline runs from a shell. Now comes the question that separates a program from a paradigm: can a recipe say so? By the end of Part III, agent fixer uses critic will load, lint, and run — and the foundation is laid here, in a struct. In this framework the recipe grammar for your paradigm is not a parser you write; it is data you declare. The loader reads it, the linter replays it, and the contract’s own unit test polices it. The DSL is a registry lookup away.

Chapter 8 — The Critic Agent

Fri, 23 Oct 2026 20:46:59 +0000

# Chapter 8 — The Critic Agent

Last chapter the contract promised an agent. This chapter you write it — and you write it the way the framework’s authors write paradigms: against the runtime surface, with the governance bar stated in the type system, the phases structured as prompts, and every claim pinned by a test driven by the fake model you built in Chapter 2. When this chapter is done, cognitionzoo/critic contains a complete paradigm: contract, agent, and prompt file. What it will not yet have is a runtime that hands it work — that is the Chapter 9 wiring, and knowing exactly what is missing is part of this chapter’s lesson.

Chapter 9 — Address It From the DSL

Fri, 23 Oct 2026 21:29:58 +0000

# Chapter 9 — Address It From the DSL

Everything exists; nothing is addressable. paradigm.Registry carries the critic’s contract, the agent runs under governance, the prompt file validates — and agent fixer uses critic still fails at load with unsupported agent paradigm in any runtime that has not linked the package. This chapter closes that gap: four small edits that teach the framework to believe, the goldens that pin the grammar, the linter that replays the loader, and the payoff — a recipe, loaded and run against stringkit, with the telemetry receipts to prove which route the runtime took. Part III ends here: critic is a DSL-addressable paradigm.

Chapter 10 — Test It Like the Framework Does

Fri, 23 Oct 2026 22:27:58 +0000

# Chapter 10 — Test It Like the Framework Does

Your paradigm has three proofs so far: thirty-eight unit tests (the fake model’s domain), a golden triple (the DSL’s domain), and one live TUI run (the operator’s domain). This chapter adds the framework’s own test layer — agenttest — where behavior is asserted from the outside: real runs, real receipts, structured assertions in three tiers. You will write the critic’s suite, watch three subsystems fight over your prompt’s wording, meet the ratchet that guards the committed catalog, and learn where the tape seam is honest about its own limits. By the end you will know what the framework considers proof at this layer — and what it refuses to certify.

Chapter 11 — Passing the Gates

Fri, 23 Oct 2026 22:45:38 +0000

# Chapter 11 — Passing the Gates

Everything you have built — the package, the contract, the agent, the wiring, the suite — now faces the gauntlet: the same gates every contributor’s PR runs. This chapter is the gauntlet as curriculum. You will run each gate, meet the failures your contribution causes, and fix every one at the cause — never at the gate. Three of the failures you meet are the best teachers in the book: one catches a real integration gap in your agent, one teaches how the framework keeps its configuration honest, and one hands you the coverage philosophy in a single output line. When the last gate goes green, the contribution is real in the only currency this repository trades in.

Chapter 12 — Meet a Real Model

Fri, 23 Oct 2026 23:13:06 +0000

# Chapter 12 — Meet a Real Model

Every proof so far rode a metronome: the fake model, the scripted conformance queues, the offline backend. The metronome taught you the framework’s shape — but a paradigm is only honest about real models after it has met one. This chapter hands the clock over. You will run the critic against the live gemma4:e4b, watch it refuse to rubber-stamp a weak draft, watch the recipe path degrade a verdict format and recover honestly, and classify what you saw in the framework’s own flake vocabulary. One chapter from now, the book hands you the PR.

Labs — Agent Construction with Relurpify

Fri, 23 Oct 2026 18:24:47 +0000

# Labs — Agent Construction with Relurpify

This folder holds every artifact the book builds, exactly as it reads at the end of the chapter that introduced it. It is the book’s cumulative code listing; Appendix D is generated from it.

# Layout

stringkit/ — the demo repo, reset for book 2 (D11): slugify strips punctuation, both tests pass, and no seeded failure is carried over from book 1. The critic you build in this book reads and critiques code against this library; chapters that need a broken state seed their own.
testdata/overlay/ — from Chapter 2 on, one folder per chapter (ch02-fake-model/, …, ch13-final/) holding the files the reader has added or changed by that chapter’s end, at true repo-root-relative paths. The folder is named testdata/ on purpose: the Go toolchain (and the repository’s own AST gates) ignore testdata directories, so the lab source of truth never pollutes gate scans; verify.sh copies the overlay into place. Chapter 1 has no overlay: its baseline is the unmodified repository.
transcripts/ — captured output from real runs: ch01-baseline.md holds the build, vet, make lint-arch, doctor, and turn transcripts quoted in Chapter 1; ch02-critic-package.md and ch03-gate-failures.md hold the Chapters 2–3 captures.
verify.sh — the tiered verifier. See below.

# Where the book’s Go code lives (D13)

Every file the book writes is self-contained in one sub-package, cognitionzoo/critic/ — the critic agent and everything that supports it. The overlay mirrors that path; nothing else in the repository is modified except the one registration import in Chapter 9, which is the act of declaring a paradigm. Two sequencing rules the repository’s own consumer gate forces, and the book obeys from the first line:

Chapter 1 — baseline transcripts (captured)

Fri, 23 Oct 2026 17:20:13 +0000

# Chapter 1 — baseline transcripts (captured)

Every block below is real output from a real run on the verification machine: Linux 6.18, Go 1.27.3, Ollama 0.40.8 serving gemma4:e4b, Docker 29.9.2, runsc release-20260406.0, Python 3.14.8, pytest 9.1.1. The tree the binaries were built from reports service.version v0.0.0-20261020195847-1bc57c620296+dirty in its own telemetry. Scratch paths are normalized to ~/code/stringkit in the chapter; elisions are marked.

Chapter 2 — critic package transcripts (captured)

Fri, 23 Oct 2026 17:58:23 +0000

# Chapter 2 — critic package transcripts (captured)

Real output from the verification machine (same environment as ch01-baseline.md). The package under test is cognitionzoo/critic/, applied into a scratch clone by verify.sh build ch02.

# 1. First layout, first lesson: the consumer gate

The chapter’s first draft of the package was two production files (fake_model.go, fake_model_test.go) with no importer anywhere in the tree. make lint-arch in the scratch clone:

Chapter 3 — gate-failure transcripts (captured)

Fri, 23 Oct 2026 17:58:23 +0000

# Chapter 3 — gate-failure transcripts (captured)

Real output from the verification machine, produced in a scratch clone with the Chapter 2 overlay applied. Every violation below was planted, captured, and reverted (git checkout restores the file; make lint-arch ends green). The violations live only in this transcript.

# Beat 1 — env access in a `_test.go` file: the gate does not look

An os.Getenv("CRITIC_FALLBACK") planted in the critic package’s fake_model_impl_test.go — envcheck still passes, and its file count does not move:

Chapter 4 — graph tour transcripts (captured)

Fri, 23 Oct 2026 18:24:47 +0000

# Chapter 4 — graph tour transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 4 overlay (ch04-first-graph) adds cognitionzoo/critic/graph_tour_test.go — six tests covering build, seal, conditions, the visit cap, validation, and preflight — on top of the Chapter 2–3 package.

# Full critic package test run (ch02+ch03+ch04 overlays)

$ go test ./cognitionzoo/critic/... -count=1 -v
--- PASS: TestEnvelopeTour (0.00s)
--- PASS: TestFakeModelIsALanguageModel (0.00s)
--- PASS: TestGenerateStreamEmitsScriptedChunksInOrder (0.00s)
--- PASS: TestGenerateReturnsJoinedText (0.00s)
--- PASS: TestChatWithToolsReturnsScriptedToolCalls (0.00s)
--- PASS: TestTurnsCycleInOrder (0.00s)
--- PASS: TestGenerateStreamClosesOnCancellation (0.03s)
--- PASS: TestGenerateStreamDropsAndCountsOnSendContention (0.03s)
--- PASS: TestErrorInjectionFailsEveryMethod (0.00s)
--- PASS: TestEmptyScriptFailsCleanly (0.00s)
--- PASS: TestFirstGraphRuns (0.00s)
--- PASS: TestConditionalEdgesRoutes (0.00s)
--- PASS: TestGraphSealsOnExecute (0.00s)
--- PASS: TestVisitCapCatchesCycle (0.00s)
--- PASS: TestValidationCatchesBrokenWiring (0.00s)
--- PASS: TestPreflightGatesToolPlacement (0.00s)
PASS
ok  	codeburg.org/lexbit/relurpify/cognitionzoo/critic	0.059s

The six Chapter 4 tests, and what each asserts:

Chapter 5 — critic graph transcripts (captured)

Fri, 23 Oct 2026 18:36:27 +0000

# Chapter 5 — critic graph transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 5 overlay (ch05-critic-graph) adds cognitionzoo/critic/critic_graph_test.go — the critic pipeline as a hand-composed graph, plus contract-default and contract-validation tests — on top of the Chapter 2–4 package.

# Full critic package test run (ch02–ch05 overlays)

$ go test ./cognitionzoo/critic/... -count=1 -v        (20 tests)
--- PASS: TestCriticPipelineRevisesWhenFlagged (0.00s)
--- PASS: TestCriticPipelineDenialSkipsRevision (0.00s)
--- PASS: TestContractDefaultsAreTyped (0.00s)
--- PASS: TestContractValidationRefusesGarbage
    --- PASS: …/invalid_side_effect_class (0.00s)
    --- PASS: …/tool_node_must_declare_capabilities (0.00s)
--- PASS: TestEnvelopeTour
--- PASS: (…the nine Chapter 2 fake-model tests…)
--- PASS: (…the six Chapter 4 graph-tour tests…)
PASS
ok  	codeburg.org/lexbit/relurpify/cognitionzoo/critic	0.059s

The four Chapter 4→5 additions, and what each asserts:

Chapter 6 — ensemble & runner transcripts (captured)

Fri, 23 Oct 2026 18:52:51 +0000

# Chapter 6 — ensemble & runner transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 6 overlay (ch06-ensemble-runner) adds the package’s first production code — cognitionzoo/critic/ensemble.go and cognitionzoo/critic/cmd/critic-runner/main.go — plus ensemble_test.go.

# The critic-runner, offline end to end

$ go run ./cognitionzoo/critic/cmd/critic-runner
telemetry graph_start          node=
telemetry node_start           node=drafter
telemetry node_finish          node=drafter success=true
telemetry graph_start          node=
telemetry node_start           node=critic-2
telemetry graph_start          node=
telemetry graph_start          node=
telemetry node_finish          node=critic-2 success=true
telemetry node_start           node=branch-done-2
telemetry node_finish          node=branch-done-2 success=true
telemetry graph_finish         node= status=success
telemetry node_start           node=critic-0
telemetry node_finish           node=critic-0 success=true
telemetry node_start           node=branch-done-0
telemetry node_finish          node=branch-done-0 success=true
telemetry graph_finish         node= status=success
telemetry node_start           node=critic-1
telemetry node_finish          node=critic-1 success=true
telemetry node_start           node=branch-done-1
telemetry node_finish          node=branch-done-1 success=true
telemetry graph_finish         node= status=success
telemetry graph.branch_merged  node= branches=[critic-0 critic-1 critic-2] conflicted_keys=[] keys_deleted=0 keys_skipped=0 keys_written=6 refs_retrieval=0 refs_streamed=0 units_applied=3 winner_index=map[]
telemetry node_start           node=merge
telemetry node_finish          node=merge success=true
telemetry node_start           node=gate
telemetry node_finish          node=gate success=true
telemetry node_start           node=revise
telemetry node_finish          node=revise success=true
telemetry graph_start          node=
telemetry node_start           node=critic-2
…  [second re-review round: the three critics' second scripted turns,
    another graph.branch_merged, merge, gate — then done; elided]
telemetry graph_finish         node= status=success

result:     success=true node=done
ensemble:   size=3 verdict=clean
revisions:  1
final draft: a revised draft with error handling
preflight:  0 issues, 0 placements

Read the transcript: the nested graph_start events are the three parallel branches (each branch runs against its own structural snapshot and cloned envelope); graph.branch_merged reports the merge in edge declaration order (branches=[critic-0 critic-1 critic-2], units_applied=3, no conflicts, six keys written — three verdicts per round); the revise node fired once and the re-review passed clean.

Chapter 7 — critic contract transcripts (captured)

Fri, 23 Oct 2026 20:36:30 +0000

# Chapter 7 — critic contract transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 7 overlay (ch07-critic-contract) adds the critic’s paradigm contract as production code (cognitionzoo/critic/contract.go, self-registering from init) plus its tests (contract_test.go).

# Package tests (ch02–ch07 overlays)

$ go test ./cognitionzoo/critic/... -count=1 -v        (30 tests)
--- PASS: TestCriticContractRegistered (0.00s)
--- PASS: TestContractCompleteness (0.00s)
--- PASS: TestRegistrationValidatesIntrinsics
    --- PASS: …/unknown_shape (0.00s)
    --- PASS: …/duplicate_directive (0.00s)
    --- PASS: …/requires_undeclared_directive (0.00s)
    --- PASS: …/order_rule_references_undeclared_directive (0.00s)
    --- PASS: …/case_pins_undeclared_directive (0.00s)
    --- PASS: …/declared_directive_without_a_case (0.00s)
    --- PASS: …/duplicate_registration (0.00s)
--- PASS: (…the twenty-three Chapter 2–6 tests…)
PASS
ok  	codeburg.org/lexbit/relurpify/cognitionzoo/critic	0.061s

TestCriticContractRegistered — the process-wide registry holds a critic contract: ShapeReviewLoop, Composes [react], directives exactly [critique revise] in declaration order, revise a predicate block requiring critique, an order rule present, no required directives (goal-only recipes preserved).
TestContractCompleteness — the mirror of every shipped paradigm’s own completeness test: every declared directive pinned by a conformance case, no case pinning an undeclared directive, and react (the Composes entry) resolved in the fully-populated registry.
TestRegistrationValidatesIntrinsics — a scoped registry driven through the seven intrinsic refusals, each captured verbatim from the validator: unknown execution shape "Whirlpool"; duplicate directive "critique"; directive "revise" requires undeclared directive "approve"; order rule references undeclared directive "polish"; conformance case "lab/ghost" pins undeclared directive "polish"; directive "revise" has no conformance case; and duplicate paradigm contract registration for "critic-lab".

# The registry now carries nine paradigms

The critic package’s init registers the contract in any binary that links it — including the runner:

Chapter 8 — critic agent transcripts (captured)

Fri, 23 Oct 2026 20:45:47 +0000

# Chapter 8 — critic agent transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 8 overlay (ch08-critic-agent) adds cognitionzoo/critic/critic.go (the agent), the workspace prompt file relurpify_cfg/prompts/agents/agent.critic.default.prompt, and cognitionzoo/critic/critic_agent_test.go.

# Package tests (ch02–ch08 overlays)

$ go test ./cognitionzoo/critic/... -count=1 -v        (32 tests)
--- PASS: TestCriticFailsClosedWithoutPermissionChecker (0.00s)
--- PASS: TestCritiqueWritesScratch (0.00s)
--- PASS: TestReviseFiresOnPredicateAndRecritiques (0.00s)
--- PASS: TestRevisionCapEndsLoopNormally (0.00s)
--- PASS: TestLibraryModeReportsWithoutRevision (0.00s)
--- PASS: TestCriticPromptFileLoadsAndValidates (0.00s)
--- PASS: (…the twenty-six Chapter 2–7 tests…)
PASS
ok  	codeburg.org/lexbit/relurpify/cognitionzoo/critic	0.061s

The six new tests, and what each pins:

Chapter 9 — registration & DSL transcripts (captured)

Fri, 23 Oct 2026 21:28:52 +0000

# Chapter 9 — registration & DSL transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 9 overlay (ch09-registration) carries the registration wiring — modified copies of four repository files at their true paths, plus the recipe and golden fixtures — applied into a scratch clone; the main repository is never modified.

Chapter 10 — agenttest transcripts (captured)

Fri, 23 Oct 2026 22:27:08 +0000

# Chapter 10 — agenttest transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts; live Ollama serving gemma4:e4b). The Chapter 10 overlay (ch10-agenttest) adds testsuite/agenttests/euclo.critic.testsuite.yaml and the suite-count ratchet bump in testsuite/agenttest/osb_coverage_test.go (24 → 26: +1 for this book’s suite, +1 for book 1’s euclo.stringkit.osb, committed alongside).

# 1. The green run

$ ./dev-agent agenttest run --suite testsuite/agenttests/euclo.critic.testsuite.yaml
euclo.critic.testsuite.yaml [record]: 2/2 passed (0 infra, 0 assertion)

Run 20261023-222227.638, per-case receipts from report.json:

Chapter 11 — gates transcripts (captured)

Fri, 23 Oct 2026 22:44:47 +0000

# Chapter 11 — gates transcripts (captured)

Real output from the verification machine (same environment as the earlier transcripts). The Chapter 11 overlay (ch11-gates) adds: the critic’s conformance runners + fixtures (testsuite/conformance/), the regenerated paradigm_matrix.yaml, the streamed-context matrix entry, the legacy paradigm parity vectors (named/euclo/surface/paradigm_test.go), the coverage override for the runner main (tooling/coverage/overrides.yaml), and the two embedded-template sources (the recipe and the prompt — ADR-002). It also carries the D-2 fix to the agent itself (cognitionzoo/critic/critic.go — the critique phase now renders the compiled slice, mirroring reflection).

Chapter 12 — live-model transcripts (captured)

Fri, 23 Oct 2026 23:12:18 +0000

# Chapter 12 — live-model transcripts (captured)

Real output from the verification machine: live Ollama 0.40.8 serving gemma4:e4b, Linux, the full ch02–ch12 overlay in a fresh scratch clone. The Chapter 12 overlay (ch12-live) adds the build-tagged live test (cognitionzoo/critic/live_critique_test.go, //go:build live) and the agenttest harness fix (testsuite/agenttest/execution.go fork: a permissive permission checker in the harness Deps, so governed-paradigm recipe runs are not refused before they start).