Estate files reference ​
The files of an estate test suite: the map driftbench estate scan writes and a person approves, the plan estate plan writes, and the phrase bank and session index that sit beside the map for estate generate. See estate. The page lists every field, generated from the zod schemas the CLI uses.
- Keys are as written below, some in camelCase. An unknown key is an error.
- Descriptions come from the schemas. An empty cell means the schema has no description for that field yet.
Contents ​
- EstateMap
- DocumentInfo
- DocumentRole
- DocumentInfo sections
- Atom
- AtomKind
- Provenance
- EvidencePredicate
- Atom replyAct
- Edge
- EdgeKind
- EstateMap producedBy
- Plan
- PlanRow
- TestType
- RunMode
- Plan summary
- PhraseBank
- WorkspaceSeed
- Situation
- SituationUse
- Touches
- Situation provokes
- BankPhrase
- PhraseBank deviations
- SessionIndex
- SessionEntry
EstateMap ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version | 1 | yes | Map format version, always 1. | |
runtime | string, not empty | yes | The adapter that read the estate: claude-code, nexus, ... | |
root | string, not empty | yes | The estate root, as given; never an absolute private path in a committed file | |
readAt | string, not empty | yes | ISO time the scan read the estate. | |
documents | list of DocumentInfo | no | Document authority and non-normative line spans; absent in older maps. | |
atoms | list of Atom | yes | Every atom the scan read from the estate. | |
edges | list of Edge | yes | The edges of the estate graph, decided by code. | |
space | string | no | Path of the exported space map of the situation axes | |
ignore | list of strings, each not empty | no | Globs the scan skipped beside the runtime defaults; lint reads the estate with them again | |
userSkills | true | no | true when the scan read a user-level skill layer; lint then needs the folder to read it again | |
followedLinks | list of strings, each not empty | no | Links, relative to the estate root, that the scan read through to a real path outside the root | |
producedBy | EstateMap producedBy | no | Who proposed the model atoms; code atoms say producedBy: code on the atom itself | |
hash | string, not empty | yes | SHA-256 over the sorted atom hashes and edges |
DocumentInfo ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string, not empty | yes | Path of the document, relative to the estate root. | |
role | DocumentRole | yes | The authority of the document as a whole, from its folder, headings and entries. | |
reasons | list of strings, each not empty, at least 1 item | yes | What the classification read: the folder, the heading or the entries that gave the role. | |
sections | list of DocumentInfo sections | no | Spans of a live document that carry a non-normative role, such as an example or a history. |
DocumentRole ​
| Value | Meaning |
|---|---|
normative | Live content: its rules, gates and references count. |
changelog | A record of releases: it holds no rule and gives no test, and it documents the files it names. |
history | A dated record of what happened: no rule, no test, and the files it names are documented. |
template | A form to fill in: read when a live document sends the reader to it, and it gives no test of its own. |
example | An illustration, or a counter-example shown so that it is not followed: no rule and no test. |
journal | A diary or work log of dated entries: no rule and no test. |
fixture | Data a test or a skill ships: no rule and no test. |
archive | Material kept for the record, loaded by nothing: no rule and no test. |
DocumentInfo sections ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
startLine | integer, at least 1 | yes | First line of the section, counted from 1. | |
endLine | integer, at least 1 | yes | Last line of the section, counted from 1. | |
role | DocumentRole | yes | The role of this section, which differs from the role of the document. |
Atom ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string, not empty | yes | Stable id: kind, file and a slug of the quote | |
kind | AtomKind | yes | The kind of place the atom comes from, which sets its mandatory test types. | |
title | string, not empty | yes | One line in plain words | |
provenance | Provenance | yes | Where the atom is read from: file, line span, quote and hash. | |
producedBy | code or model | yes | Code when read from file structure and approved as read; model when split from prose by a model. | |
role | axis or detail | no | axis | Axis puts the atom in the space map as a target; detail keeps it for the generator only. |
approved | boolean | no | false | Whether the atom is approved; only approved atoms enter the space map and the plan. |
situation | string | no | When the atom applies, in words; empty means always | |
evidence | list of EvidencePredicate, at least 1 item | yes | What a trace shows when the atom is obeyed, as at least one typed predicate. | |
enforcement | list of strings | no | [] | Ids of guards or tests that already check it; empty means trusted |
fields | map of string to any value | no | Kind-specific structure read by code: a guard event, a tool schema, a brief field list | |
replyAct | Atom replyAct | no | The act of the agent reply that the atom governs, when it governs one. |
AtomKind ​
| Value | Meaning |
|---|---|
instruction | A rule of the estate: an obligation or a prohibition with its situation, split from prose by a model. |
gate | An order rule: before one act, do another, such as reading a file before editing it. |
route | A trigger: an ask of one class loads a named skill or helper. |
skill | A skill unit with its trigger, instructions, references and scripts. |
reference | A file a skill or helper names, read at the moment its body names. |
script | An executable a skill ships, with its inputs and outputs. |
subagent | A helper contract: name, description, allowed tools, model, brief fields, output shape and acts it must not do. |
guard | A guard the settings or a skill declare: its event, matcher and command, with its check registry row. |
tool | A permission rule of the settings that allows, denies or asks for a tool, or a tool a skill declares. |
setting | A run setting such as the model, the permission mode or an environment key, never its secret value. |
stage | A step of the step list the estate defines, such as plan, do, verify or report. |
register | An output rule: language, length, format, forbidden words or tone. |
hazard | A passage of the estate that names a runtime hazard, such as a compaction or a new session. |
invariant | A static property of the estate files, such as the size ceiling of the standing instructions. |
Provenance ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
file | string, not empty | yes | Path relative to the estate root | |
startLine | integer, at least 1 | yes | First line of the quote in the file, counted from 1. | |
endLine | integer, at least 1 | yes | Last line of the quote in the file, counted from 1. | |
quote | string, not empty | yes | The exact text the atom is read from | |
hash | string, not empty | yes | SHA-256 of the quote, the file and the span; a change here is a changed atom |
EvidencePredicate ​
Write one of these forms.
- a mapping with
type: skill_loaded, with the fields below - a mapping with
type: skill_not_loaded, with the fields below - a mapping with
type: guard, with the fields below - a mapping with
type: tool_called, with the fields below - a mapping with
type: tool_not_called, with the fields below - a mapping with
type: reference_not_read, with the fields below - a mapping with
type: subagent_not_dispatched, with the fields below - a mapping with
type: guard_not_fired, with the fields below - a mapping with
type: stage_not_reached, with the fields below - a mapping with
type: artifact_not_created, with the fields below - a mapping with
type: file_not_written, with the fields below - a mapping with
type: ordered, with the fields below - a mapping with
type: stage_reached, with the fields below - a mapping with
type: workspace, with the fields below - a mapping with
type: artifact, with the fields below - a mapping with
type: text, with the fields below - a mapping with
type: static, with the fields below - a mapping with
type: custom, with the fields below
With type: skill_loaded:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | skill_loaded | yes | This form holds when the named skill loads in the block. | |
name | string, not empty | yes | The skill name the trace records on its load. | |
min | integer, at least 1 | no | The fewest loads that count; defaults to 1. |
With type: skill_not_loaded:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | skill_not_loaded | yes | This form holds when the named skill never loads in the block. | |
name | string, not empty | yes | The skill name that must not load. |
With type: guard:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | guard | yes | This form holds when the named guard records a decision in the trace. | |
name | string, not empty | yes | The guard name its decision records carry, such as its script file name. | |
verdict | string, not empty | no | Without it, any verdict counts, as in the guards check | |
min | integer, at least 0 | no | The fewest decisions that count; defaults to 1. |
With type: tool_called:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | tool_called | yes | This form holds when the agent calls the tool. | |
label | string, not empty | yes | The tool label as the trace records it, such as Read or Bash. | |
input | map of string to any value | no | Input fields one call must match; without it, any call of the tool counts. | |
min | integer, at least 1 | no | The fewest matching calls that count; defaults to 1. |
With type: tool_not_called:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | tool_not_called | yes | This form holds when the agent never calls the tool. | |
label | string, not empty | yes | The tool label that must not appear in the trace. | |
input | map of string to any value | no | Only forbid calls matching these input assertions; without it, forbid every call. |
With type: reference_not_read:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | reference_not_read | yes | No successful read of this path or glob in the block. | |
path | string, not empty | yes | The path or glob of the reference that must not be read. |
With type: subagent_not_dispatched:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | subagent_not_dispatched | yes | No dispatch of this helper in the block. | |
name | string, not empty | yes | The name of the helper that must not be dispatched. |
With type: guard_not_fired:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | guard_not_fired | yes | No firing of this guard in the block. | |
name | string, not empty | yes | The name of the guard that must not fire. | |
verdict | string, not empty | no | Only forbid this verdict; without it, forbid every firing. |
With type: stage_not_reached:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | stage_not_reached | yes | This stage never appears in the block. | |
name | string, not empty | yes | The name of the stage that must not be reached. |
With type: artifact_not_created:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | artifact_not_created | yes | The workspace diff lists no creation of this path or glob. | |
path | string, not empty | yes | The path or glob that must not be created. |
With type: file_not_written:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | file_not_written | yes | The workspace diff lists no creation or change of this path or glob. | |
path | string, not empty | yes | The path or glob that must not be created or changed. |
With type: ordered:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | ordered | yes | This form holds when the before act comes earlier than the after act. | |
before | string, not empty | yes | A tool label, a skill name or a stage name | |
after | string, not empty | yes | A tool label, a skill name or a stage name that must come second. |
With type: stage_reached:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | stage_reached | yes | This form holds when the run reaches the named stage. | |
name | string, not empty | yes | The stage name from the step list of the estate. |
With type: workspace:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | workspace | yes | This form holds when the workspace changes as listed. | |
created | list of strings | no | Paths the run creates in the workspace. | |
changed | list of strings | no | Paths the run changes in the workspace. | |
deleted | list of strings | no | Paths the run deletes from the workspace. | |
othersUntouched | boolean | no | When true, every path not listed stays untouched. |
With type: artifact:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | artifact | yes | This form holds when the run produces a file at the path. | |
path | string, not empty | yes | Workspace path of the produced file. | |
kind | string | no | File kind: xlsx, docx, pptx, pdf, csv, json, text or code; the generator drops any other value. |
With type: text:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | text | yes | This form holds when the reply text meets its word and language rules. | |
must | list of strings | no | Literal words the reply must contain. | |
mustNot | list of strings | no | Literal words the reply must not contain. | |
lang | string | no | Language tag the reply is written in, such as EN. |
With type: static:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | static | yes | This form holds when a property of the estate files holds, with no run. | |
check | string, not empty | yes | A property of the estate files, no run |
With type: custom:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | custom | yes | This form names a check that decides the evidence, run by code or judged. | |
name | string, not empty | yes | The check name, such as ordered, max_words or grounded_values. | |
options | map of string to any value | no | Options passed to the named check, such as a word limit. |
Atom replyAct ​
The act of the agent reply that the atom governs, when it governs one.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string, not empty | yes | The act of the reply the rule governs: answer, clarify, refuse, ... | |
evidence | map of string to any value | yes | What in the reply shows the act, typed. |
Edge ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
from | string, not empty | yes | Id of the atom the edge starts at. | |
to | string, not empty | yes | Id of the atom the edge ends at, or an event node on an event edge. | |
kind | EdgeKind | yes | The relation the edge states, such as route, reference or dispatch. |
EdgeKind ​
| Value | Meaning |
|---|---|
route | A route atom to the skill or helper it loads. |
reference | A skill or helper to a file its body names. |
script | A skill to a script it ships. |
dispatch | A skill or helper to a helper its body names. |
enforces | A guard to a rule it checks. |
event | A guard to the event node it runs on. |
allows | A skill or helper to a tool or skill it may use. |
next | A stage to the stage that follows it. |
cites | A rule to a rule its words name by label. |
EstateMap producedBy ​
Who proposed the model atoms; code atoms say producedBy: code on the atom itself
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
family | string, not empty | yes | The model family that split the prose, code when no model ran | |
model | string, not empty | yes | The model that split the prose, or unknown when the model port names none. | |
at | string matching ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ | yes | ISO time of the scan, the same as readAt. |
Plan ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version | 1 | yes | Plan format version, always 1. | |
mapHash | string, not empty | yes | Hash of the approved map the plan was derived from. | |
spaceHash | string | no | Content hash of the space map the plan used. | |
rows | list of PlanRow | yes | The rows from the contract, the journeys and the pairwise cells. | |
summary | Plan summary | yes | Counts and lists that describe the plan. |
PlanRow ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string, not empty | yes | Row id: test type and atom id for a contract row, journey.N or pairwise.N otherwise. | |
atomIds | list of strings, each not empty, at least 1 item | yes | Atoms the row exercises: the atom under test, then its skill or helper; a journey lists its path in order. | |
cell | map of string to string | yes | Dimension id to value id on the situation axes | |
testType | TestType | yes | The test type the row asks for. | |
mode | RunMode | yes | How the row runs: replay, unit or live, set by its test type. | |
status | one of proposed, approved, struck | no | proposed | Proposed until a person approves or strikes the row; generate skips struck rows. |
weight | number, at least 0 | no | 1 | The share of the run budget the row gets, edited by hand. |
note | string | no | What the row checks, in plain words. |
TestType ​
| Value | Meaning |
|---|---|
obligation | The required act happens, or a forbidden act does not, in the situation of the rule. |
outside_trigger | Negative control: outside its situation the act does not happen, or an allowed act is not held back. |
twin | The obligation again, with the ask put in another phrasing. |
ordered_pair | The first act of a gate comes before the second. |
skip_pressure | The owner pushes to go faster, and the order of the gate still holds. |
route_positive | A positive ask loads the route target. |
route_near_miss | Negative control: an ask close to the trigger that belongs elsewhere does not load the target. |
misroute | The ask names the act without the skill; the right target loads, or the agent says why not. |
read_when | The reference file is read at the moment named. |
script_fixture | The script runs on a fixture, checked by its exit code and output. |
dispatch | The helper dispatch carries every brief field the helper needs. |
contract_alone | The helper runs alone: its typed output, and no act it must not do. |
stop_resume | The helper stops mid-task and is resumed with its work intact. |
guard_positive | A recorded event gives the guard verdict. |
guard_negative | Negative control: a look-alike event leaves the guard silent. |
guard_hostile | Malformed input gives no crash and a safe verdict. |
guard_speed | The guard answers within its time budget. |
guard_register | The guard message follows the output rules. |
tool_boundary | Tool calls stay inside the schema and the permission rule. |
tool_denied | A call the settings deny is never attempted. |
tool_deferred | A deferred tool is loaded before its first use. |
stage_order | The stage is reached in its order in the step list. |
stage_skip | The owner pushes to go faster, and the stage is not skipped. |
stage_anytime | A step allowed at any point shows once in the block, wherever, and is not required. |
register_sample | A sample of replies to one ask class, judged and counted against the output rule. |
hazard_recovery | The hazard during a long task: the agent recovers, edits nothing out of scope and loses no row. |
invariant | A static test of the estate files, with no run. |
setting | A static test that the settings still hold the key, and its value when kept. |
journey | A path of atoms from the standing instructions over the estate graph, one block per atom. |
RunMode ​
| Value | Meaning |
|---|---|
replay | The row runs over a recorded session, offline, with no model call. |
unit | The row runs offline on one piece of the estate, such as a guard, a script or a helper alone. |
live | The row runs the agent headless in a sandboxed copy of the estate. |
Plan summary ​
Counts and lists that describe the plan.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
cells | integer, at least 0 | yes | Distinct pairs of the atoms of a row and its situation values. | |
coveringArraySize | integer, at least 0 | yes | Rows of the pairwise covering array. | |
perKind | map of string to integer, at least 0 | yes | Contract rows per atom kind, a row counted once for each kind it names. | |
perTestType | map of string to integer, at least 0 | yes | Rows per test type across contract, journey and pairwise rows. | |
unenforcedAtoms | list of strings | yes | Ids of approved instruction, gate and register atoms that no guard enforces. | |
cellsWithoutPhrase | integer, at least 0 | yes | Cells with no approved phrase; the plan reads no phrase bank, so it equals cells. | |
edgesWithoutJourney | integer, at least 0 | yes | Journey edges that no journey takes. |
PhraseBank ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version | 1 | yes | The version of the phrase bank format, 1. | |
estate | string, not empty | yes | The name of the estate the bank is written for. | |
mapHash | string, not empty | yes | The hash of the approved map the bank was written against | |
workspaces | list of WorkspaceSeed | no | [] | The workspace seeds a situation can start from. |
situations | list of Situation | no | [] | May be empty: a model-free run still gets the gap report, each row naming the phrase it needs |
deviations | list of PhraseBank deviations | no | [] | The phrases for each deviation class a plan cell can carry. |
WorkspaceSeed ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string matching ^[a-z0-9][a-z0-9._-]*$ | yes | A short id, unique among the seeds; a situation names it under workspace. | |
title | string, not empty | yes | What the workspace holds, in a few words. | |
files | map of string to string | yes | The files of the workspace, as path and content; a spec inlines them as world.workspace.files. |
Situation ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string matching ^[a-z0-9][a-z0-9._-]*$ | yes | A short id, unique among the situations of the bank. | |
title | string, not empty | yes | What the situation is, in a few words. | |
use | SituationUse | yes | What the situation is for, such as setting the atom off or tempting the agent to skip a gate. | |
atoms | list of strings, each not empty, at least 1 item | yes | The atoms this situation exercises | |
cell | map of string to string | no | Situation axis values the phrases express; a plan row must agree with each of them | |
workspace | string matching ^[a-z0-9][a-z0-9._-]*$ | no | The workspace seed the ask starts from | |
touches | Touches | no | The workspace paths the ask may touch; every other path stays untouched | |
provokes | Situation provokes | no | A call the stand-in agent makes while the situation is in force, such as the removal a PostToolUse guard watches | |
phrases | list of BankPhrase, at least 1 item | yes | The asks that put the agent in the situation, each approved or not. |
SituationUse ​
| Value | Meaning |
|---|---|
trigger | The situation sets the atom off. |
outside | The situation sits just outside the atom's trigger, so the act must not happen. |
near_miss | The situation reads like a route's asks but is not one. |
misroute | The situation names the wrong primitive for the work. |
pressure | The situation tempts the agent to skip a gate or a stage. |
resume | The situation picks a stopped helper up again. |
forced | The situation instructs the guarded act itself, so a live guard test never waits for the agent to choose it. |
Touches ​
The workspace paths the ask may touch; every other path stays untouched
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
created | list of strings, each not empty | no | [] | The workspace paths the ask may create. |
changed | list of strings, each not empty | no | [] | The workspace paths the ask may change. |
deleted | list of strings, each not empty | no | [] | The workspace paths the ask may delete. |
Situation provokes ​
A call the stand-in agent makes while the situation is in force, such as the removal a PostToolUse guard watches
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
tool | string, not empty | yes | The tool of the call, such as Bash. | |
command | string, not empty | yes | The command of the call (fictional text); the call runs it as written. |
BankPhrase ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
text | string, not empty | yes | The ask, word for word, as the user writes it. | |
lang | string, 2 to 8 characters | yes | The language code of the phrase, such as en or de. | |
approved | boolean | yes | Only approved phrases reach a spec |
PhraseBank deviations ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
class | string, not empty | yes | The deviation class the phrases inject, as a cell names it under deviation. | |
phrases | list of BankPhrase, at least 1 item | yes | The messages that inject the deviation before the ask, each approved or not. |
SessionIndex ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version | 1 | yes | The version of the session index format, 1. | |
sessions | list of SessionEntry, at least 1 item | yes | The recorded sessions, one entry per transcript. |
SessionEntry ​
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string, not empty | yes | The transcript's file name without .jsonl | |
situation | string matching ^[a-z0-9][a-z0-9._-]*$ | yes | The situation of the bank the session was recorded in. | |
ask | string, not empty | yes | The recorded ask: one approved phrase of the situation | |
from_block | integer, at least 0 | no | 0 | The session block a generated spec's first block replays from; 0 is the first block. |
violates | list of strings, each not empty | no | [] | The atoms the session breaks: a spec on any of them is planned to fail |
note | string | no | A free remark about the session, for a person; the generator does not read it. |