{ "pack_id": "atomic-step-contract", "title": "Atomic step contract", "version": "0.1.0", "summary": "A collection of nouns and verbs for giving each atomic step exactly what it needs: a pinned procedure, a closed slice of state, the last observation and a stated grant, with transcripts left out; grants that deny on the wire rather than in wording; refusals that name what is allowed; state returned as a checked patch; and per-step overhead measured before work is sliced finer.", "dependencies": [ "decomposition-patterns", "findings-to-fixes" ], "boundaries": [ "Packets, patches and refusals are data. They never widen a worker's grant.", "Measurements use a local endpoint that records requests and answers nothing; no provider is called.", "A step's own report is never its verdict; the runner's check or a person decides.", "Workers create nouns and propose verbs; an authorized requester enqueues the proposals worth doing.", "Importing the pack writes nothing and enqueues nothing." ], "nouns": [ { "slug": "pack", "category": "noun.skill_pack", "role": "pack", "title": "A collection of nouns and verbs for giving each atomic step exactly what it needs", "value": { "lets_workers": "Hand each atomic step exactly what it needs and nothing else, the way a colleague hands over a task with the file attached instead of forwarding the whole thread: define step kinds, audit that their grants deny on the wire, assemble bounded packets, check every returned patch, review refusals and repeated calls, measure what one step costs before any content and decide how finely to slice work.", "flow": [ { "verb": { "$verb": "atomic-step-contract.define-step-kind" }, "when": "Once per kind of step, before any run uses it." }, { "verb": { "$verb": "atomic-step-contract.audit-grant" }, "when": "When a kind is defined or its harness changes; deterministic." }, { "verb": { "$verb": "atomic-step-contract.assemble-step-packet" }, "when": "Before every step; deterministic." }, { "verb": { "$verb": "atomic-step-contract.check-patch" }, "when": "After every step returns; deterministic." }, { "verb": { "$verb": "atomic-step-contract.review-refusals" }, "when": "After a run that looped, stalled or hit a limit." }, { "verb": { "$verb": "atomic-step-contract.measure-step-overhead" }, "when": "Before deciding how finely to slice work, and when a harness changes." }, { "verb": { "$verb": "atomic-step-contract.review-pull-log" }, "when": "After enough runs to show what steps fetch on demand." } ], "guardrails": [ "A step is atomic only if its grant cannot do the other things; wording is not a boundary.", "Success comes from a check the runner runs, never from the step's account of its own work.", "Packets never carry earlier transcripts; state travels as named fields.", "Measurements say how they were taken and what they did not measure." ], "worked_examples": [ { "$pin": "step-checks" }, { "$pin": "example.step-kind" }, { "$pin": "example.overhead-measurement" } ] }, "relations": [ [ "requires_noun", "method" ], [ "requires_noun", "packet-rules" ], [ "requires_noun", "grant-rules" ], [ "requires_noun", "refusal-rules" ], [ "requires_noun", "patch-rules" ], [ "requires_noun", "overhead-model" ] ] }, { "slug": "method", "category": "noun.skill_pack", "role": "method", "title": "How a step kind is defined, granted, fed, checked and measured", "category_reason": "A reusable procedure with guardrails, followed by every verb in this pack.", "value": { "lifecycle": [ "define-step-kind writes the procedure, the closed state slice, the write scope, the observation, the grant, an exploration allowance and the check.", "audit-grant records what the harness actually offers the step and flags any tool that can write when the kind is read-only.", "assemble-step-packet builds the packet for one step: procedure digest, state slice, last observation, stated grant, nothing else.", "The step runs under its grant and returns a patch of named fields.", "check-patch admits or rejects each field, and rejected fields become the next observation.", "review-refusals finds refusals that do not name the legal set, repeated identical answers and the limit that really bound the run.", "measure-step-overhead and review-pull-log tune how finely to slice and what to push by default." ], "rules": [ "One step, one job. The atomic step is the largest unit that still recurs, so a match can be reused later.", "Attempt a task whole first and split it only when its check fails; a child without its own check inherits the parent's.", "A failed step is followed by an observing step with real output and no write tools, not by the same step with an error string added.", "Ask for the most structured response form the content supports: a value, a sentence, a list, a rule, a measurement, an evaluation or code.", "Workers create nouns and propose verbs; they never enqueue." ], "follow_ups": { "finding": { "$verb": "findings-to-fixes.record-finding" }, "breakdown": { "$verb": "decomposition-patterns.propose-breakdown" } } } }, { "slug": "packet-rules", "category": "noun.reflex_procedure", "role": "packet_rules", "title": "What one step always receives, may fetch, and never sees", "category_reason": "A zero-call deterministic rule set: the same kind, state and observation give the same packet.", "value": { "always": [ "The procedure for this step kind, written once and pinned by digest.", "The state slice this kind may read: named fields from a closed schema, not the whole record.", "The last observation from the runner: a check's exit code and tail, a listing, or the reasons the last patch was rejected.", "The grant, stated, so a refusal is predictable instead of a surprise." ], "on_demand": [ "Files or records the step names, resolved by the runner through the same rails that guard writes.", "A second request for the same item gets a short reminder, not the content again." ], "never": [ "The transcript of earlier steps.", "An unbounded ledger. Pull from it through a logged query with a closed vocabulary." ], "push_or_pull": "Push what the step will almost certainly need. Pull only what is large and usually unneeded, because each pull costs another turn that repeats the whole prefix.", "learning_rule": "The pull log shows what the next default packet should have held; review-pull-log turns it into a proposal.", "model_calls": 0 } }, { "slug": "grant-rules", "category": "noun.reflex_procedure", "role": "grant_rules", "title": "Grants that deny by construction, not by request", "category_reason": "Deterministic rules applied to a recorded grant and a recorded request.", "value": { "rules": [ "A write scope is only as strong as the weakest tool in the grant. A shell, an interpreter or a stream editor can write.", "The step requests tools; the runner grants them from a closed catalog. A step never composes its own instance.", "A verifying or observing step holds no write tools.", "Unattended steps hold no permission to ask, because nobody will answer.", "Allowances come from the remaining budget, not from a fixed timeout per step.", "Prompt text never travels as command-line arguments, which other local users can read.", "Denial is checked on the wire: a tool refused at use but still described in every request still costs its schema." ], "verdicts": { "structural": "The denied tools are absent from what the harness sends and cannot be called.", "wording_only": "The denial exists only in the instructions; the tools are still offered.", "write_leak": "A tool that can write is offered to a step declared read-only.", "unknown": "What the harness sends could not be observed." } } }, { "slug": "refusal-rules", "category": "noun.reflex_procedure", "role": "refusal_rules", "title": "Refusals that name what is allowed", "category_reason": "Deterministic rules checked against recorded refusals.", "value": { "rules": [ "A refusal names what is wrong and what is available: the nearest valid paths, the legal values, the tools the step holds.", "An identical request answered identically spends a turn to learn nothing; answer a repeat with a reminder.", "Past the exploration allowance, the runner stops serving lookups and asks for the step's output, or ends the step as blocked.", "Name the limit that actually bound the run. Raising a limit that did not bind changes nothing.", "Machine vocabulary in a refusal is fine; a refusal with no legal set is a finding." ], "model_calls": 0 } }, { "slug": "patch-rules", "category": "noun.reflex_procedure", "role": "patch_rules", "title": "State returned as a checked patch of named fields", "category_reason": "Deterministic admission rules for returned patches.", "value": { "rules": [ "A step returns a patch: named field changes, checked against its kind's write scope, merged by the runner.", "An unknown field is rejected with its name and the legal fields; an immutable field is refused; null deletes.", "Rejected fields and their reasons become the next observation; the reasoning that produced the patch is not kept.", "A prompt-side schema only steers. The runtime contract is the only validator that admits or rejects.", "Refuse an empty reply, an echo of the prompt or prose with no structured part; ask again once, naming the problem, and stop when the same invalid reply repeats." ], "model_calls": 0 } }, { "slug": "overhead-model", "category": "noun.reflex_procedure", "role": "overhead_model", "title": "What one step costs before any content, and when slicing finer pays", "category_reason": "Deterministic arithmetic over recorded measurements.", "value": { "terms": { "P": "Tokens a harness sends before any task content: instructions plus tool schemas.", "C": "Task content tokens for the coarse step.", "k": "Number of atomic steps replacing it.", "h": "Share of atomic steps answered by reuse at no cost." }, "costs": { "coarse": "P + C", "atomic": "k(1 - h)(P + C/k) = (1 - h)(kP + C)" }, "break_even": "Slicing pays when h > (k - 1)P / (kP + C).", "readings": [ "When P is much larger than C, the threshold approaches 1 - 1/k: four slices need a hit rate near 75 percent.", "When P is small next to C, the threshold falls toward (k - 1)P / C, so a cheap prefix makes fine slicing affordable.", "Compute the exact value; a cheap prefix lowers the threshold but does not remove it." ], "measuring": [ "Point each harness at a local endpoint that answers nothing and records every request.", "Count with one named tokenizer; never estimate from characters.", "A request reaching the endpoint is a lower bar than the harness working; record which configurations ran cleanly." ], "model_calls": 0 } }, { "slug": "template.step-kind", "category": "noun.seed_hypothesis", "role": "template", "title": "Template: one kind of atomic step: its pinned procedure, the closed state it reads, what it may write, its observation, grant, allowance and check", "category_reason": "A step kind is a claim that exactly this information and grant are enough; its runs confirm or refute it.", "value": { "describes": "one kind of atomic step: its pinned procedure, the closed state it reads, what it may write, its observation, grant, allowance and check", "schema": { "type": "object", "additionalProperties": false, "required": [ "kind_id", "purpose", "procedure", "reads", "writes", "immutable_fields", "observation", "grant", "on_demand", "exploration_allowance", "acceptance", "failure_policy", "max_depth", "response_form" ], "properties": { "kind_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 300 }, "procedure": { "type": "object", "additionalProperties": false, "required": [ "text_ref", "sha256", "immutable" ], "properties": { "text_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "immutable": { "type": "boolean", "enum": [ true ] } } }, "reads": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "field", "why" ], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 80 }, "why": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "writes": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "field", "rule" ], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 80 }, "rule": { "type": "string", "minLength": 1, "maxLength": 200 } } } }, "immutable_fields": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "observation": { "type": "string", "enum": [ "check_output", "listing", "rejection_reasons", "file_excerpt", "none_first_step" ] }, "grant": { "type": "object", "additionalProperties": false, "required": [ "read_only", "tools", "write_paths", "network", "ask" ], "properties": { "read_only": { "type": "boolean" }, "tools": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "writes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "writes": { "type": "boolean" } } } }, "write_paths": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "network": { "type": "string", "enum": [ "none", "local_only", "read_only", "assigned_tessera" ] }, "ask": { "type": "boolean", "enum": [ false ] } } }, "on_demand": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "ref_kind", "resolved_by" ], "properties": { "ref_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "resolved_by": { "type": "string", "enum": [ "runner" ] } } } }, "exploration_allowance": { "type": "integer", "minimum": 1, "maximum": 100 }, "acceptance": { "type": "object", "additionalProperties": false, "required": [ "check", "run_by" ], "properties": { "check": { "type": "string", "minLength": 1, "maxLength": 300 }, "run_by": { "type": "string", "enum": [ "runner", "person" ] } } }, "failure_policy": { "type": "string", "enum": [ "observe_then_retry", "split_on_failure", "stop_blocked" ] }, "max_depth": { "type": "integer", "minimum": 0, "maximum": 10 }, "response_form": { "type": "string", "enum": [ "value", "sentence", "list", "rule", "measurement_spec", "evaluation", "code_or_test" ] } } }, "rules": [ "The grant is the boundary; the procedure text never widens it.", "Every kind names the check that decides success and who runs it." ] } }, { "slug": "template.step-packet", "category": "noun.seed_hypothesis", "role": "template", "title": "Template: what one step receives: procedure digest, state slice, last observation, stated grant, what it may fetch and what was left out", "category_reason": "A packet is a claim that this information is enough for one step.", "value": { "describes": "what one step receives: procedure digest, state slice, last observation, stated grant, what it may fetch and what was left out", "schema": { "type": "object", "additionalProperties": false, "required": [ "packet_id", "step_kind", "procedure_sha256", "state_slice", "observation", "grant", "on_demand", "excluded", "exploration_allowance", "acceptance", "size", "assembled_at" ], "properties": { "packet_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "step_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "procedure_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "state_slice": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "field", "value" ], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 80 }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } } } }, "observation": { "type": "object", "additionalProperties": false, "required": [ "kind", "text", "exit_code", "rejections" ], "properties": { "kind": { "type": "string", "enum": [ "check_output", "listing", "rejection_reasons", "file_excerpt", "none_first_step" ] }, "text": { "type": "string", "minLength": 0, "maxLength": 4000 }, "exit_code": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "rejections": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "reason", "legal_options" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "legal_options": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } }, "grant": { "type": "object", "additionalProperties": false, "required": [ "read_only", "tools", "write_paths", "network", "ask" ], "properties": { "read_only": { "type": "boolean" }, "tools": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "writes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "writes": { "type": "boolean" } } } }, "write_paths": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "network": { "type": "string", "enum": [ "none", "local_only", "read_only", "assigned_tessera" ] }, "ask": { "type": "boolean" } } }, "on_demand": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "ref", "resolved_by" ], "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolved_by": { "type": "string", "minLength": 1, "maxLength": 40 } } } }, "excluded": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exploration_allowance": { "type": "integer", "minimum": 0, "maximum": 100 }, "acceptance": { "type": "object", "additionalProperties": false, "required": [ "check", "run_by" ], "properties": { "check": { "type": "string", "minLength": 1, "maxLength": 300 }, "run_by": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "size": { "type": "object", "additionalProperties": false, "required": [ "tokens", "counter", "reason_if_unknown" ], "properties": { "tokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000000 }, "counter": { "type": "string", "minLength": 0, "maxLength": 80 }, "reason_if_unknown": { "type": "string", "minLength": 0, "maxLength": 300 } } }, "assembled_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "Assembled by the runner, never by the step.", "Excluded lists name transcripts explicitly." ] } }, { "slug": "template.grant-audit", "category": "noun.eval_run", "role": "template", "title": "Template: whether a step kind's grant denies structurally, from what the harness actually sent", "category_reason": "A grant audit is a deterministic check run.", "value": { "describes": "whether a step kind's grant denies structurally, from what the harness actually sent", "schema": { "type": "object", "additionalProperties": false, "required": [ "audit_id", "step_kind", "harness", "declared", "observed_on_wire", "write_capable_observed", "verdict", "evidence", "audited_at" ], "properties": { "audit_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "step_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "harness": { "type": "object", "additionalProperties": false, "required": [ "name", "version", "configuration" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "version": { "type": "string", "minLength": 1, "maxLength": 60 }, "configuration": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "declared": { "type": "object", "additionalProperties": false, "required": [ "read_only", "tools" ], "properties": { "read_only": { "type": "boolean" }, "tools": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 80 } } } }, "observed_on_wire": { "type": "object", "additionalProperties": false, "required": [ "method", "tool_schemas", "tool_names" ], "properties": { "method": { "type": "string", "minLength": 1, "maxLength": 300 }, "tool_schemas": { "type": "integer", "minimum": 0, "maximum": 500 }, "tool_names": { "type": "array", "minItems": 0, "maxItems": 60, "items": { "type": "string", "minLength": 1, "maxLength": 80 } } } }, "write_capable_observed": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "verdict": { "type": "string", "enum": [ "structural", "wording_only", "write_leak", "unknown" ] }, "evidence": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 400 } }, "audited_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "Verdicts follow the grant rules only.", "Evidence cites the recorded request." ] } }, { "slug": "template.patch-check", "category": "noun.eval_run", "role": "template", "title": "Template: one returned patch: fields admitted, fields rejected with the legal options, and the next observation", "category_reason": "A patch check is a deterministic admission run.", "value": { "describes": "one returned patch: fields admitted, fields rejected with the legal options, and the next observation", "schema": { "type": "object", "additionalProperties": false, "required": [ "check_id", "packet_ref", "step_kind", "reply_form", "fields_written", "admitted", "rejected", "immutable_refused", "reasks", "next_observation", "checked_at" ], "properties": { "check_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "packet_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "step_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "reply_form": { "type": "string", "enum": [ "schema_tool", "fenced_json", "prose_refused", "empty_refused", "echo_refused" ] }, "fields_written": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "admitted": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "rejected": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "field", "reason", "legal_options" ], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 80 }, "reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "legal_options": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 120 } } } } }, "immutable_refused": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "reasks": { "type": "integer", "minimum": 0, "maximum": 1 }, "next_observation": { "type": "string", "minLength": 0, "maxLength": 4000 }, "checked_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "Every rejection names the legal options." ] } }, { "slug": "template.refusal-review", "category": "noun.eval_run", "role": "template", "title": "Template: a run's refusals, repeated answers, exploration without output and the limit that really bound it", "category_reason": "A review of recorded refusals against the refusal rules.", "value": { "describes": "a run's refusals, repeated answers, exploration without output and the limit that really bound it", "schema": { "type": "object", "additionalProperties": false, "required": [ "review_id", "run_ref", "refusals", "repeated_identical_answers", "exploration_turns_without_output", "binding_limit", "findings_proposed", "reviewed_at" ], "properties": { "review_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "run_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "refusals": { "type": "array", "minItems": 0, "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "message", "names_legal_set", "rewrite" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 400 }, "names_legal_set": { "type": "boolean" }, "rewrite": { "type": "string", "minLength": 0, "maxLength": 400 } } } }, "repeated_identical_answers": { "type": "integer", "minimum": 0, "maximum": 10000 }, "exploration_turns_without_output": { "type": "integer", "minimum": 0, "maximum": 10000 }, "binding_limit": { "type": "object", "additionalProperties": false, "required": [ "name", "value", "raised_but_not_binding" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "value": { "type": "string", "minLength": 1, "maxLength": 40 }, "raised_but_not_binding": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 80 } } } }, "findings_proposed": { "type": "integer", "minimum": 0, "maximum": 50 }, "reviewed_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "Each refusal without a legal set gets a proposed rewrite." ] } }, { "slug": "template.overhead-measurement", "category": "noun.eval_run", "role": "template", "title": "Template: per-step prefix cost for each harness configuration, measured on the wire, with the hit rate finer slicing would need", "category_reason": "A measurement run with its method and limits.", "value": { "describes": "per-step prefix cost for each harness configuration, measured on the wire, with the hit rate finer slicing would need", "schema": { "type": "object", "additionalProperties": false, "required": [ "measurement_id", "method", "configurations", "slicing", "break_even", "not_measured", "measured_at" ], "properties": { "measurement_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "method": { "type": "object", "additionalProperties": false, "required": [ "endpoint", "answers", "tokenizer", "task", "workspace" ], "properties": { "endpoint": { "type": "string", "enum": [ "local_recording_endpoint" ] }, "answers": { "type": "string", "enum": [ "nothing" ] }, "tokenizer": { "type": "string", "minLength": 1, "maxLength": 80 }, "task": { "type": "string", "minLength": 1, "maxLength": 200 }, "workspace": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "configurations": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "harness", "version", "configuration", "tool_schemas", "message_tokens", "tool_tokens", "total_prefix_tokens", "ran_cleanly", "note" ], "properties": { "harness": { "type": "string", "minLength": 1, "maxLength": 80 }, "version": { "type": "string", "minLength": 1, "maxLength": 60 }, "configuration": { "type": "string", "minLength": 1, "maxLength": 200 }, "tool_schemas": { "type": "integer", "minimum": 0, "maximum": 500 }, "message_tokens": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "tool_tokens": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "total_prefix_tokens": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "ran_cleanly": { "type": "boolean" }, "note": { "type": "string", "minLength": 0, "maxLength": 300 } } } }, "slicing": { "type": "object", "additionalProperties": false, "required": [ "content_tokens", "slices", "assumption" ], "properties": { "content_tokens": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "slices": { "type": "integer", "minimum": 2, "maximum": 50 }, "assumption": { "type": "string", "minLength": 1, "maxLength": 400 } } }, "break_even": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "harness", "required_hit_rate" ], "properties": { "harness": { "type": "string", "minLength": 1, "maxLength": 80 }, "required_hit_rate": { "type": "number", "minimum": 0, "maximum": 1 } } } }, "not_measured": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 300 } }, "measured_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "required_hit_rate is (k - 1)P / (kP + C), rounded to three places.", "Configurations that did not run cleanly say so." ] } }, { "slug": "template.packet-revision", "category": "noun.seed_hypothesis", "role": "template", "title": "Template: a proposed change to a step kind's default packet, from what its steps fetched and used across runs", "category_reason": "A revision proposal is a hypothesis about what the next packet should hold.", "value": { "describes": "a proposed change to a step kind's default packet, from what its steps fetched and used across runs", "schema": { "type": "object", "additionalProperties": false, "required": [ "revision_id", "step_kind", "runs_read", "window", "pulls", "add_to_push", "drop_from_push", "keep_on_demand", "proposed_at" ], "properties": { "revision_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "step_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "runs_read": { "type": "integer", "minimum": 1, "maximum": 100000 }, "window": { "type": "object", "additionalProperties": false, "required": [ "from", "to" ], "properties": { "from": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}", "maxLength": 40 }, "to": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}", "maxLength": 40 } } }, "pulls": { "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "ref_kind", "fetched_in_runs", "used_in_output_runs" ], "properties": { "ref_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "fetched_in_runs": { "type": "integer", "minimum": 0, "maximum": 100000 }, "used_in_output_runs": { "type": "integer", "minimum": 0, "maximum": 100000 } } } }, "add_to_push": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "drop_from_push": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "keep_on_demand": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "proposed_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "rules": [ "A proposal only; the kind's owner decides." ] } }, { "slug": "step-checks", "category": "noun.benchmark_suite", "role": "record_checks", "title": "Record checks for step packets, with synthetic golden packets", "category_reason": "A deterministic check suite with known-good and known-bad examples; the validator recomputes every verdict.", "value": { "fixture_kind": "finding_checks", "purpose": "Checks every step packet must pass before the step runs. The two synthetic good packets pass all of them; each synthetic bad packet fails exactly the one check named in fails.", "deterministic_checks": [ { "id": "procedure-pinned", "rule": { "rule": "pattern_present", "path": "procedure_sha256", "pattern": "^[0-9a-f]{64}$" }, "why": "The procedure for the step kind is fixed and pinned by digest, not assembled per run." }, { "id": "state-slice-named", "rule": { "rule": "each_has", "path": "state_slice", "min": 1, "fields": [ "field", "value" ] }, "why": "The step reads a closed, named slice of state, not the whole record." }, { "id": "transcript-excluded", "rule": { "rule": "pattern_present", "path": "excluded", "pattern": "^transcript$" }, "why": "Earlier steps' transcripts are never part of a packet." }, { "id": "no-transcript-in-slice", "rule": { "rule": "pattern_absent", "path": "state_slice", "pattern": "(?i)\\b(transcript|conversation so far|previous steps)\\b" }, "why": "The slice does not smuggle a transcript back in under another field name." }, { "id": "read-only-holds-no-writer", "rule": { "rule": "when", "if": { "path": "grant.read_only", "equals": true }, "then": { "rule": "pattern_absent", "path": "grant.tools", "pattern": "(?i)^(shell|bash|sed|edit|write|apply_patch|python)$" } }, "why": "A read-only step that holds a shell or editor can still write; the grant is only as strong as its weakest tool." }, { "id": "no-runtime-question", "rule": { "rule": "enum", "path": "grant.ask", "values": [ false ] }, "why": "An unattended step cannot wait for an answer; asking is refused when the step is composed." }, { "id": "refusals-name-legal-set", "rule": { "rule": "when", "if": { "path": "observation.kind", "equals": "rejection_reasons" }, "then": { "rule": "each_has", "path": "observation.rejections", "min": 1, "fields": [ "reason", "legal_options" ] } }, "why": "A rejection says what is wrong and what is allowed, so the step does not guess the same thing again." }, { "id": "fetched-by-runner", "rule": { "rule": "pattern_absent", "path": "on_demand", "pattern": "(?i)^model$" }, "why": "Extra context is resolved by the runner through the same rails as writes, never fetched freely by the model." }, { "id": "verdict-by-runner", "rule": { "rule": "enum", "path": "acceptance.run_by", "values": [ "runner", "person" ] }, "why": "Success comes from a check the runner runs or a person, never from the step's report about itself." }, { "id": "exploration-bounded", "rule": { "rule": "present", "path": "exploration_allowance" }, "why": "Past its exploration allowance the step must produce its output or stop as blocked." }, { "id": "size-counted-or-explained", "rule": { "rule": "when", "if": { "path": "size.tokens", "equals": null }, "then": { "rule": "present", "path": "size.reason_if_unknown" } }, "why": "An unmeasured size stays empty with a reason; it is never recorded as zero." } ], "golden_fixtures": [ { "id": "good-repair", "label": "known_good", "provenance": "synthetic", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "good-observe", "label": "known_good", "provenance": "synthetic", "finding": { "packet_id": "PK-15", "step_kind": "observe-failure", "procedure_sha256": "9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9", "state_slice": [ { "field": "task", "value": "The price list import test fails." }, { "field": "acceptance_command", "value": "run-tests tests/test_import.py" } ], "observation": { "kind": "check_output", "text": "1 failed: test_rounding expected 2.50, got 2.5", "exit_code": 1, "rejections": [] }, "grant": { "read_only": true, "tools": [ { "name": "read_file", "writes": false }, { "name": "list_dir", "writes": false } ], "write_paths": [], "network": "none", "ask": false }, "on_demand": [], "excluded": [ "transcript" ], "exploration_allowance": 4, "acceptance": { "check": "The observation quotes the failing line and names one file.", "run_by": "runner" }, "size": { "tokens": null, "counter": "", "reason_if_unknown": "The harness reports no token counters for this step." }, "assembled_at": "2026-10-30T02:12Z" } }, { "id": "bad-procedure-unpinned", "label": "known_bad", "fails": "procedure-pinned", "why": "The procedure is not pinned by digest.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-empty-slice", "label": "known_bad", "fails": "state-slice-named", "why": "The packet names no state fields.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-transcript-allowed", "label": "known_bad", "fails": "transcript-excluded", "why": "Transcripts are not excluded.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-transcript-smuggled", "label": "known_bad", "fails": "no-transcript-in-slice", "why": "A slice field carries the earlier transcript.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" }, { "field": "history", "value": "The transcript of the previous 12 steps, pasted in full." } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-read-only-shell", "label": "known_bad", "fails": "read-only-holds-no-writer", "why": "A read-only step holds a shell.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": true, "tools": [ { "name": "edit_by_site", "writes": true }, { "name": "shell", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-asks", "label": "known_bad", "fails": "no-runtime-question", "why": "The step may ask a question at run time.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": true }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-bare-refusal", "label": "known_bad", "fails": "refusals-name-legal-set", "why": "The rejection does not say what is allowed.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope." } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-model-fetches", "label": "known_bad", "fails": "fetched-by-runner", "why": "The model fetches extra context itself.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "any file it wants", "resolved_by": "model" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-self-grading", "label": "known_bad", "fails": "verdict-by-runner", "why": "The step grades its own work.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "step" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-unbounded", "label": "known_bad", "fails": "exploration-bounded", "why": "No exploration allowance.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": 912, "counter": "a named tokenizer, counted before sending", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } }, { "id": "bad-size-zeroed", "label": "known_bad", "fails": "size-counted-or-explained", "why": "The size is unknown and no reason is given.", "finding": { "packet_id": "PK-14", "step_kind": "repair-config-value", "procedure_sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "state_slice": [ { "field": "task", "value": "The service config check rejects the retry setting." }, { "field": "acceptance_command", "value": "validate-config config/service.json" }, { "field": "target_file", "value": "config/service.json" } ], "observation": { "kind": "rejection_reasons", "text": "The previous patch was not applied.", "exit_code": null, "rejections": [ { "reason": "Field timeout_s is not in this kind's write scope.", "legal_options": [ "timeout_seconds", "retry_limit" ] } ] }, "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref": "the current text of config/service.json", "resolved_by": "runner" } ], "excluded": [ "transcript", "unbounded ledger" ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "size": { "tokens": null, "counter": "", "reason_if_unknown": "" }, "assembled_at": "2026-10-30T02:10Z" } } ], "finding_schema": { "type": "object", "additionalProperties": false, "required": [ "packet_id", "step_kind", "procedure_sha256", "state_slice", "observation", "grant", "on_demand", "excluded", "exploration_allowance", "acceptance", "size", "assembled_at" ], "properties": { "packet_id": { "type": "string", "minLength": 1, "maxLength": 60 }, "step_kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "procedure_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "state_slice": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "field", "value" ], "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 80 }, "value": { "type": "string", "minLength": 1, "maxLength": 2000 } } } }, "observation": { "type": "object", "additionalProperties": false, "required": [ "kind", "text", "exit_code", "rejections" ], "properties": { "kind": { "type": "string", "enum": [ "check_output", "listing", "rejection_reasons", "file_excerpt", "none_first_step" ] }, "text": { "type": "string", "minLength": 0, "maxLength": 4000 }, "exit_code": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 255 }, "rejections": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "reason", "legal_options" ], "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 200 }, "legal_options": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 200 } } } } } } }, "grant": { "type": "object", "additionalProperties": false, "required": [ "read_only", "tools", "write_paths", "network", "ask" ], "properties": { "read_only": { "type": "boolean" }, "tools": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "writes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "writes": { "type": "boolean" } } } }, "write_paths": { "type": "array", "minItems": 0, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "network": { "type": "string", "enum": [ "none", "local_only", "read_only", "assigned_tessera" ] }, "ask": { "type": "boolean" } } }, "on_demand": { "type": "array", "minItems": 0, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "ref", "resolved_by" ], "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "resolved_by": { "type": "string", "minLength": 1, "maxLength": 40 } } } }, "excluded": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 80 } }, "exploration_allowance": { "type": "integer", "minimum": 0, "maximum": 100 }, "acceptance": { "type": "object", "additionalProperties": false, "required": [ "check", "run_by" ], "properties": { "check": { "type": "string", "minLength": 1, "maxLength": 300 }, "run_by": { "type": "string", "minLength": 1, "maxLength": 40 } } }, "size": { "type": "object", "additionalProperties": false, "required": [ "tokens", "counter", "reason_if_unknown" ], "properties": { "tokens": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000000 }, "counter": { "type": "string", "minLength": 0, "maxLength": 80 }, "reason_if_unknown": { "type": "string", "minLength": 0, "maxLength": 300 } } }, "assembled_at": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?Z$", "maxLength": 30 } } }, "expected": { "good-repair": { "verdict": "pass", "failed_checks": [] }, "good-observe": { "verdict": "pass", "failed_checks": [] }, "bad-procedure-unpinned": { "verdict": "fail", "failed_checks": [ "procedure-pinned" ] }, "bad-empty-slice": { "verdict": "fail", "failed_checks": [ "state-slice-named" ] }, "bad-transcript-allowed": { "verdict": "fail", "failed_checks": [ "transcript-excluded" ] }, "bad-transcript-smuggled": { "verdict": "fail", "failed_checks": [ "no-transcript-in-slice" ] }, "bad-read-only-shell": { "verdict": "fail", "failed_checks": [ "read-only-holds-no-writer" ] }, "bad-asks": { "verdict": "fail", "failed_checks": [ "no-runtime-question" ] }, "bad-bare-refusal": { "verdict": "fail", "failed_checks": [ "refusals-name-legal-set" ] }, "bad-model-fetches": { "verdict": "fail", "failed_checks": [ "fetched-by-runner" ] }, "bad-self-grading": { "verdict": "fail", "failed_checks": [ "verdict-by-runner" ] }, "bad-unbounded": { "verdict": "fail", "failed_checks": [ "exploration-bounded" ] }, "bad-size-zeroed": { "verdict": "fail", "failed_checks": [ "size-counted-or-explained" ] } } } }, { "slug": "example.step-kind", "category": "noun.seed_hypothesis", "role": "example", "title": "Worked example: a step kind that changes one configuration value", "synthetic": true, "category_reason": "A synthetic step kind in the template's shape.", "value": { "conforms_to": { "$pin": "template.step-kind" }, "instance": { "kind_id": "repair-config-value", "purpose": "Change one value in one configuration file so the configuration check passes.", "procedure": { "text_ref": "procedures/repair-config-value.md", "sha256": "3f1c9a5e2b7d4c6a8e0f1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60", "immutable": true }, "reads": [ { "field": "task", "why": "What the person asked for, unchanged." }, { "field": "acceptance_command", "why": "The check that decides success." }, { "field": "target_file", "why": "The one file this kind may change." } ], "writes": [ { "field": "edit", "rule": "One numbered edit site from the runner's menu, with its replacement text." }, { "field": "cause", "rule": "One sentence quoting the failing value." } ], "immutable_fields": [ "task", "acceptance_command" ], "observation": "rejection_reasons", "grant": { "read_only": false, "tools": [ { "name": "edit_by_site", "writes": true } ], "write_paths": [ "config/service.json" ], "network": "none", "ask": false }, "on_demand": [ { "ref_kind": "current file text", "resolved_by": "runner" } ], "exploration_allowance": 3, "acceptance": { "check": "validate-config config/service.json exits 0", "run_by": "runner" }, "failure_policy": "observe_then_retry", "max_depth": 1, "response_form": "code_or_test" }, "shows": "The kind reads three named fields, writes one edit chosen from the runner's numbered sites, holds one write tool scoped to one file and cannot ask.", "source": "Synthetic. Written for this pack; every name, number and identifier is made up." } }, { "slug": "example.overhead-measurement", "category": "noun.eval_run", "role": "example", "title": "Worked example: three harness configurations measured on the wire", "synthetic": true, "category_reason": "A synthetic measurement in the template's shape.", "value": { "conforms_to": { "$pin": "template.overhead-measurement" }, "instance": { "measurement_id": "OM-3", "method": { "endpoint": "local_recording_endpoint", "answers": "nothing", "tokenizer": "one named tokenizer for every request", "task": "the same one-line change for every configuration", "workspace": "one folder holding one three-line file" }, "configurations": [ { "harness": "harness A", "version": "1.0", "configuration": "default tools", "tool_schemas": 10, "message_tokens": 3300, "tool_tokens": 4900, "total_prefix_tokens": 8200, "ran_cleanly": true, "note": "" }, { "harness": "harness A", "version": "1.0", "configuration": "one read tool only", "tool_schemas": 1, "message_tokens": 760, "tool_tokens": 80, "total_prefix_tokens": 840, "ran_cleanly": true, "note": "Tool schemas were removed from the request, not only refused at use." }, { "harness": "harness B", "version": "2.3", "configuration": "edit blocks in prose, no tool schemas", "tool_schemas": 0, "message_tokens": 430, "tool_tokens": 0, "total_prefix_tokens": 430, "ran_cleanly": true, "note": "" } ], "slicing": { "content_tokens": 500, "slices": 4, "assumption": "Content splits evenly across slices, a hit costs nothing and the coarse step never hits." }, "break_even": [ { "harness": "harness A, default tools", "required_hit_rate": 0.739 }, { "harness": "harness A, one read tool only", "required_hit_rate": 0.653 }, { "harness": "harness B, edit blocks in prose, no tool schemas", "required_hit_rate": 0.581 } ], "not_measured": [ "Whether a step with the smaller prefix solves as many tasks; this measures what is sent, not what comes back." ], "measured_at": "2026-10-30T03:00Z" }, "shows": "With 500 content tokens and four slices, the configuration with 8,200 prefix tokens needs a 73.9 percent hit rate to break even and the one with 430 still needs 58.1 percent.", "source": "Synthetic. Written for this pack; every name, number and identifier is made up." } } ], "verbs": [ { "slug": "define-step-kind", "kind": "verb.distill_reflex", "title": "Define a kind of atomic step", "claimant": "agent", "summary": "Write one step kind from the work it must do: the pinned procedure, the closed state slice it reads, the fields it may write, its observation, the grant it needs, an exploration allowance, its check and failure policy.", "outcome": "A step kind, or no_change when an existing kind already fits.", "ready_outcome": "kind_defined", "pinned": [ "packet-rules", "grant-rules", "patch-rules" ], "slots": [ { "name": "examples", "category": "noun.eval_run", "description": "Pins of runs or failures this kind should handle.", "many": true, "max": 10, "required": false } ], "produces": [ { "name": "step_kind", "template": "template.step-kind" } ], "steps": [ "Verify the pins. Start from the smallest job that still recurs across tasks; reuse an existing kind when one fits.", "List only the state fields the job needs, and the fields it may write; mark task and check immutable.", "Grant the fewest tools that can do the job. A read-only kind holds no shell, interpreter or editor.", "Name the check that decides success and who runs it, and set an exploration allowance.", "Choose the most structured response form the content supports." ], "acceptance": [ { "id": "kind-matches-template", "check": "The kind validates against template.step-kind's schema.", "method": "deterministic" }, { "id": "grant-minimal", "check": "Every granted tool is needed for a written field.", "method": "judgment" }, { "id": "check-named", "check": "acceptance.check names a command or a person's check.", "method": "deterministic" } ], "bounds": { "max_elapsed_seconds": 1200 } }, { "slug": "audit-grant", "kind": "verb.verify_gate", "title": "Audit that a grant denies on the wire", "claimant": "agent", "model_use": "none", "summary": "Record what one harness configuration actually offers a step, by pointing it at a local endpoint that answers nothing, and compare it with the kind's declared grant.", "outcome": "A grant audit with a verdict of structural, wording only, write leak or unknown.", "ready_outcome": "grant_audited", "pinned": [ "grant-rules" ], "slots": [ { "name": "step_kind", "category": "noun.seed_hypothesis", "description": "Pin of the step kind." } ], "params": { "harness": { "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Harness name and exact version.", "required": true } }, "produces": [ { "name": "grant_audit", "template": "template.grant-audit" } ], "steps": [ "Verify the pins. Drive the harness with the kind's configuration against a local recording endpoint; no provider is called.", "List every tool schema in the recorded request and mark each tool that can write.", "Apply the grant rules; write unknown with the reason when the request could not be recorded." ], "acceptance": [ { "id": "audit-matches-template", "check": "The audit validates against template.grant-audit's schema.", "method": "deterministic" }, { "id": "verdict-follows-rules", "check": "The verdict is write_leak whenever a write-capable tool is offered to a read-only kind.", "method": "deterministic" }, { "id": "evidence-cited", "check": "Every evidence entry cites the recorded request.", "method": "deterministic" } ], "network": [ "local_only", "Only a local endpoint that records requests and answers nothing; no provider or remote host is contacted." ], "bounds": { "max_elapsed_seconds": 600 } }, { "slug": "assemble-step-packet", "kind": "verb.situate", "title": "Assemble the packet for one step", "claimant": "agent", "model_use": "none", "summary": "Build the packet one step receives from its kind, the current state and the last observation: the procedure digest, the named slice, the observation, the stated grant and what may be fetched on demand, with transcripts left out.", "outcome": "A step packet that passes the step checks, or blocked when the state lacks a field the kind reads.", "ready_outcome": "packet_assembled", "pinned": [ "packet-rules", "step-checks" ], "slots": [ { "name": "step_kind", "category": "noun.seed_hypothesis", "description": "Pin of the step kind." }, { "name": "state", "category": "noun.seed_hypothesis", "description": "Pin of the current state record." }, { "name": "observation", "category": "noun.eval_run", "description": "Pin of the last observation, if any.", "required": false } ], "produces": [ { "name": "step_packet", "template": "template.step-packet" } ], "steps": [ "Verify the pins. Copy only the fields the kind reads from the current state.", "Attach the last observation from the runner as it was recorded; never summarize it from memory.", "State the grant exactly as the kind defines it; list transcripts in excluded.", "Count the packet's size with a named counter, or leave it empty with the reason." ], "acceptance": [ { "id": "packet-matches-template", "check": "The packet validates against template.step-packet's schema.", "method": "deterministic" }, { "id": "step-checks-pass", "check": "The packet passes every check in step-checks.", "method": "deterministic" }, { "id": "slice-closed", "check": "Every slice field appears in the kind's reads list.", "method": "deterministic" } ], "bounds": { "max_elapsed_seconds": 120 } }, { "slug": "check-patch", "kind": "verb.verify_gate", "title": "Check a step's returned patch", "claimant": "agent", "model_use": "none", "summary": "Admit or reject each field of a returned patch against the kind's write scope, refuse empty, echoed or prose-only replies, and turn every rejection into the next observation with the legal options.", "outcome": "A patch check, with admitted fields and rejections that name what is allowed.", "ready_outcome": "patch_checked", "pinned": [ "patch-rules" ], "slots": [ { "name": "step_kind", "category": "noun.seed_hypothesis", "description": "Pin of the step kind." }, { "name": "packet", "category": "noun.seed_hypothesis", "description": "Pin of the packet the step received." }, { "name": "reply", "category": "noun.eval_run", "description": "Pin of the step's recorded reply." } ], "produces": [ { "name": "patch_check", "template": "template.patch-check" } ], "steps": [ "Verify the pins. Reject unknown fields by name and list the legal fields; refuse writes to immutable fields.", "Refuse an empty reply, an echo of the prompt or prose with no structured part, and ask again once naming the problem.", "Write the next observation from the rejections; never pass the step's reasoning forward." ], "acceptance": [ { "id": "check-matches-template", "check": "The patch check validates against template.patch-check's schema.", "method": "deterministic" }, { "id": "rejections-name-options", "check": "Every rejected field lists at least one legal option.", "method": "deterministic" }, { "id": "one-reask", "check": "reasks is 0 or 1.", "method": "deterministic" } ], "bounds": { "max_elapsed_seconds": 120 } }, { "slug": "review-refusals", "kind": "verb.recheck_fragility", "title": "Review a run's refusals and repeats", "claimant": "agent", "summary": "Read a run's refusals, repeated calls and exploration turns, flag every refusal that does not name the legal set and every repeated identical answer, and name the limit that actually bound the run.", "outcome": "A refusal review with proposed findings and rewrites, or no_change when every refusal named its legal set.", "ready_outcome": "refusals_reviewed", "pinned": [ "refusal-rules" ], "slots": [ { "name": "run", "category": "noun.eval_run", "description": "Pin of the run record with its refusals." } ], "produces": [ { "name": "refusal_review", "template": "template.refusal-review" } ], "steps": [ "Verify the pins. Read only the run's recorded refusals, calls and limits.", "For each refusal without a legal set, write the rewrite that would have named it.", "Name the limit that ended the run, and list limits that were raised but never bound.", "Propose one record-finding verb per distinct defect." ], "acceptance": [ { "id": "review-matches-template", "check": "The review validates against template.refusal-review's schema.", "method": "deterministic" }, { "id": "every-refusal-read", "check": "Every refusal in the run appears once.", "method": "deterministic" }, { "id": "binding-limit-right", "check": "The named binding limit is the one that ended the run.", "method": "judgment" } ], "bounds": { "max_elapsed_seconds": 900 } }, { "slug": "measure-step-overhead", "kind": "verb.benchmark_harness", "title": "Measure what one step costs before any content", "claimant": "agent", "model_use": "none", "summary": "Measure the prefix each harness configuration puts in front of the same small task, with a local recording endpoint and one named tokenizer, and compute the hit rate that finer slicing would need.", "outcome": "An overhead measurement with the break-even hit rate per configuration and what was not measured.", "ready_outcome": "overhead_measured", "pinned": [ "overhead-model" ], "params": { "content_tokens": { "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "Task content tokens for the coarse step.", "required": true }, "slices": { "schema": { "type": "integer", "minimum": 2, "maximum": 50 }, "description": "Number of atomic steps that would replace it.", "default": 4 } }, "produces": [ { "name": "measurement", "template": "template.overhead-measurement" } ], "steps": [ "Verify the pins. Use the same task and workspace for every configuration; no provider is called.", "Count message and tool-schema tokens separately with the named tokenizer.", "Compute required_hit_rate as (k - 1)P / (kP + C) for the stated content size and slice count.", "Record which configurations ran cleanly, and state that answer quality was not measured." ], "acceptance": [ { "id": "measurement-matches-template", "check": "The measurement validates against template.overhead-measurement's schema.", "method": "deterministic" }, { "id": "totals-add-up", "check": "total_prefix_tokens equals message_tokens plus tool_tokens for every configuration.", "method": "deterministic" }, { "id": "break-even-recomputes", "check": "Every required_hit_rate recomputes from the overhead model.", "method": "deterministic" } ], "network": [ "local_only", "Only a local endpoint that records requests and answers nothing; no provider or remote host is contacted." ], "bounds": { "max_elapsed_seconds": 1800 } }, { "slug": "review-pull-log", "kind": "verb.distill_reflex", "title": "Propose what a step kind should receive by default", "claimant": "agent", "summary": "Read what steps of one kind fetched on demand across runs, and which fetched items their outputs used, and propose what to add to the default packet, what to drop and what to keep on demand.", "outcome": "A packet revision proposal, or no_change when the default packet already fits.", "ready_outcome": "revision_proposed", "pinned": [ "packet-rules" ], "slots": [ { "name": "step_kind", "category": "noun.seed_hypothesis", "description": "Pin of the step kind." }, { "name": "runs", "category": "noun.eval_run", "description": "Pins of run records with their pull logs.", "many": true, "max": 100 } ], "produces": [ { "name": "revision", "template": "template.packet-revision" } ], "steps": [ "Verify the pins. Count, per kind of item, the runs that fetched it and the runs whose output used it.", "Propose adding items fetched in most runs to the default packet, dropping default items no output used, and keeping large rare items on demand.", "The kind's owner decides; propose a new define-step-kind verb instead of editing the kind." ], "acceptance": [ { "id": "revision-matches-template", "check": "The revision validates against template.packet-revision's schema.", "method": "deterministic" }, { "id": "counts-bounded", "check": "Every used_in_output_runs is at most its fetched_in_runs.", "method": "deterministic" }, { "id": "evidence-sufficient", "check": "The window holds enough runs to support each change.", "method": "judgment" } ], "bounds": { "max_elapsed_seconds": 900 } } ] }