@r1z4x/tezgah 1.0.0

package/docs/glossary.md

@@ -0,0 +1,201 @@
+# Glossary
+
+The one place a tezgah term is defined. Read it when a word in the injected
+contract or in another `docs/` page is ambiguous, or before you use one of these
+words in a new rule, a page or a review comment. Every other page uses these terms
+and links here; no page restates a definition. Entries are alphabetical; each
+gives the sense this repository uses, the `path:line` where the concept lives, and
+- where a term is confused with a neighbour - one line on what it is not. These
+are definitions, not rules: the rule text belongs to [contract](contract.md),
+[gate](gate.md) and [evidence](evidence.md).
+
+### after-block row
+A ledger [row](#row) of kind `after_block`: the [Stop rule](#stop-rule)'s record-only verdict on the reply that answers its own block. The host sets `stop_hook_active`, and the turn already holds a `blocked:` [claim](#claim) row. `stop_reason(..., record_only=True)` (`hooks/tezgah_integrity.py::stop_reason`) writes it on Claude, Codex and omp, with `detail` `would block: <reason class>`, `ok` or `no claim`. Not a [claim](#claim): the rule never refuses that reply a second time, and `counters()` counts it neither as a claim nor as a reply.
+
+### always-on
+The part of the contract every session pays for - the invariants plus the one-line [pointer](#pointer) - built by `always_on_core()` (`hooks/tezgah_context.py::always_on_core`) out of [CORE](#core) with the [conditional rules](#conditional-rule) removed; it is not the whole contract, whose long tail is the `tezgah-contract` [skill](#skill) ([contract](contract.md)).
+
+### attestation
+The per-session check of tezgah's own hook entries against the install record. `run()` (`hooks/tezgah_attest.py::run`) reads each host's entries. It compares them with the `hook:<host>:<entry>` lines in `contract.sha256` (`bin/tezgah-setup::record_hooks`). It writes one `attest` [row](#row) and sets or clears the `drift` [mark](#mark). Not integrity: whoever can edit a hook can edit the record. A clean row is evidence, not proof.
+
+### budget
+The byte ceiling one injected event may spend: `CONTEXT_BUDGET` per event with `DEFAULT_BUDGET` behind it (`hooks/tezgah_context.py::CONTEXT_BUDGET`), enforced by `budgeted()` (`hooks/tezgah_context.py::budgeted`), which gives up blocks lowest value first along `DROP_ORDER` (`hooks/tezgah_context.py::DROP_ORDER`) - the skill hint among the first, the task phase, the delta and the pointer last - shrinking a block in `SHRINK` (the per-turn relevant lessons, to their first lesson) before it drops it (`hooks/tezgah_context.py::SHRINK`). The core, the reminder, an armed paragraph and the pinned user constraints sit outside `DROP_ORDER`. An event can therefore stay over its budget, and its note says so. The ceiling counts bytes, never tokens, because the module has no tokenizer. Not the [metadata band](#metadata-band), which is the installer's measurement of the same text rather than a runtime bound.
+
+### capture
+The pre-write copy the gate takes of every file a write is about to change, `capture()` (`hooks/tezgah_snapshot.py::capture`), called on the gate's allow path (`hooks/tezgah_gate.py::decision`) and capped at `CAP` snapshots and `MAX_BYTES` per file (`hooks/tezgah_snapshot.py:52-53`); a file too large or unreadable is left uncaptured and writes no row, so nothing claims a copy that is not there. Not a transaction: the copy is bytes on disk, not a rollback that runs itself.
+
+### claim
+A ledger [row](#row) recording the [Stop rule](#stop-rule)'s verdict on one reply, `detail` being `ok` or `blocked: <reason class>`, written by `stop_reason()` (`hooks/tezgah_integrity.py::stop_reason`, row at `hooks/tezgah_integrity.py::stop_reason`). Not a deny: nothing ran, the turn simply may not end.
+
+### conditional rule
+A rule armed for one prompt only, when its task class matches - `spec`, `consult`, `research`, `product`, `graph` (`hooks/tezgah_policy.py::CONDITIONAL_KEYS`) - selected by `classify_prompt()` against the prompt hints (`hooks/tezgah_context.py::classify_prompt`, `hooks/tezgah_context.py::PROMPT_HINTS`) and injected in full on the first turn of a session that matched, one line on a later match (`hooks/tezgah_context.py::armed_again`) until a compaction or `ARMED_RESURFACE` turns bring the paragraph back (`hooks/tezgah_context.py::context_for`). Not an [always-on](#always-on) rule, though it sits in [CORE](#core) even while unarmed.
+
+### contract
+The whole working document, the long-form blocks of `hooks/tezgah_policy.py` shipped on demand as the hand-kept `skills/tezgah-contract/SKILL.md` (pinned to them by `tests/test_setup.py::ContractParity`), with the always-on [CORE](#core) as its summary and the [pointer](#pointer) line as the way in (`hooks/tezgah_policy.py::POINTERS`). Its clauses are [contract](contract.md)'s subject.
+
+### CORE
+The single string holding the whole always-on contract, one bold-labelled paragraph per [rule](#rule) (`hooks/tezgah_policy.py::CORE`), filtered against [per-repo marks](#per-repo-mark) and [kill switches](#kill-switch) by `core_split()` (`hooks/tezgah_context.py::core_split`). Not [contract](#contract), the on-demand skill of every block.
+
+### deny
+A refusal the gate returns and records: `_deny()` writes a `deny` row carrying the rule name and the first 80 characters of the reason (`hooks/tezgah_gate.py::_deny`). Not the reason text itself - the adapter renders the reason into its own envelope ([hosts](hosts.md)).
+
+### digest
+The identity of one tool call, `call_id()` = `sha1(tool.lower() + " " + canonical(args))[:12]` (`hooks/tezgah_integrity.py::call_id`); both the gate and the post-tool hook compute it here, so a [row](#row) and the call it belongs to agree. Not a session id.
+
+### enforcement capability
+What one host can do with one rule surface: the gate, the Stop rule or a subagent. Four words name it. `gate`: it can refuse. `observe`: it records and never refuses. `partial`: only part of the surface fires. `unavailable`: the host has no event for it. `unverified` marks a cell no driver here can show the host obeying ([hosts](hosts.md#enforcement-capability)). Not an [observable measure](#observable-measure), a status mark a surface can see, and not a mark [state](#state).
+
+<a id="ledger"></a>
+### evidence ledger
+One JSONL file per session recording what ran, `<cache>/evidence/<slug>.jsonl` (`hooks/tezgah_integrity.py::_path`), appended by `note()` (`hooks/tezgah_integrity.py::note`) and read by `events()` (`hooks/tezgah_integrity.py::events`), with its contract in the module docstring (`hooks/tezgah_integrity.py:2-24`) and every reader failing open. Not the [session store](#session-store), which holds only used-tool marks.
+
+### false completion
+The count of [claim](#claim) rows a stop refused, `false_completion` in `counters()`, read against `claims` so the rate is meaningful (`hooks/tezgah_integrity.py::_counts`, `hooks/tezgah_integrity.py::drift_series`). Not the count of [denies](#deny): a deny is the gate refusing a call, a false completion is the Stop rule refusing the end of a turn.
+
+### gate
+The pre-tool refusal layer, `decision()` (`hooks/tezgah_gate.py::decision`), which runs only inside a [root](#root) (`hooks/tezgah_gate.py::decision`) and returns a reason or nothing ([gate](gate.md)). Not the [Stop rule](#stop-rule), which runs after the reply.
+
+### group
+The partition a status [mark](#mark) carries so a renderer separates the marks the same way: `_GROUP` maps each key to an index and `render_line()` joins groups with `  ·  ` (`hooks/tezgah_context.py::_GROUP`, `hooks/tezgah_context.py::render_line`). Not a [state](#state).
+
+### harness
+This project's own frame for the work, tezgah being the wrapper it puts around a coding agent - the injected contract, the [gate](#gate) and the [ledger](#evidence-ledger) - whose per-turn text still travels in the `<harness-reminder>` envelope (`hooks/tezgah_policy.py::PROMPT_REMINDER`). Two neighbours share the word: the agent runtime itself, which the current literature calls a complete agent harness (arXiv 2606.10106; `README.md:27-28` calls dsh one) and the multi-agent selection of the `harness` [skill](#skill), including the graph workflows the policy lists under "Graph harnesses" (`hooks/tezgah_policy.py::WORKFLOWS`); [layers](layers.md) draws the three apart. Not the [host](#host): the host is the agent, the harness is what tezgah puts around it.
+
+### harness skill
+The [skill](#skill) that picks and runs a multi-agent harness for a task too wide for one context window - a code-graph workflow such as `graph-map` or a briefed subagent set (`skills/harness/SKILL.md:2-8`). Not tezgah's own wrapper around a [host](#host) ([harness](#harness), [layers](layers.md)).
+
+### host
+One coding agent tezgah is installed into - claude, codex, cursor, opencode, dsh, omp - with its config location in `HOST_DIRS` (`hooks/tezgah_paths.py::HOST_DIRS`), its presence test in `host_installed()` (`hooks/tezgah_paths.py::host_installed`) and its adapter under `hosts/<name>/` ([hosts](hosts.md)); also written "agent host", and the agent runtime the current literature calls the agent harness ([harness](#harness), [layers](layers.md)). Not a [root](#root): a host is a program, a root is a directory tezgah is armed over.
+
+### kind
+The label on an evidence [row](#row) saying what happened: `classify()` gives `edit` or `run`/`verify` (`hooks/tezgah_integrity.py::classify`), `note_tool()` refines a check into `verify_ok`/`verify_fail` (`hooks/tezgah_integrity.py::note_tool`), writes `interrupted` when the host said the call was stopped (`hooks/tezgah_integrity.py::note_tool`) and adds `external` (`hooks/tezgah_integrity.py::note_tool`) or `unknown` (`hooks/tezgah_integrity.py::note_tool`), and the machinery adds `deny`, `nudge`, `turn`, `claim`, `drift`, `snapshot`, `rollback`, `lesson`; `kinds()` returns the distinct set (`hooks/tezgah_integrity.py::kinds`).
+
+### kill switch
+A file whose presence removes exactly its own rule from the injected text and from the gate, not merely from the status line: `off()` checks the canonical config dir and the legacy `~/.claude` (`hooks/tezgah_paths.py::off`, `hooks/tezgah_paths.py::OFF_DIRS`), and the list is in [CORE](#core) (`hooks/tezgah_policy.py::CORE`). Not a [per-repo mark](#per-repo-mark): a switch is per machine, a mark per repo.
+
+### legend
+The prose explaining the status [marks](#mark) and their glyphs, `LEGEND` (`hooks/tezgah_context.py::LEGEND`), printed by `tezgah-status --legend` (`bin/tezgah-status::main`). Not the marks themselves.
+
+### mark
+One item of the armed/used checklist as a host shows it, a segment carrying `key`, `state`, `glyph`, `text` and `group` from `health_segments()` (`hooks/tezgah_context.py::health_segments`), for example `pony✓` or `consult○`. Not a [kind](#kind), which is a ledger row, and not the [state](#state), which is the value one mark carries.
+
+### metadata band
+One measured row of always-on context the installer reports in bytes: the core contract, the per-turn reminder, skill metadata, subagent metadata and the conditional rules (`context_budget()`, `bin/tezgah-setup::context_budget`), with the MCP tool schemas as the one band it cannot count and measures by handshake instead (`mcp_schema_report()`, `bin/tezgah-setup::mcp_schema_report`). Not the [budget](#budget): a band is a measurement, a budget a bound.
+
+### mirror
+`output-styles/tezgah.md`, a by-hand duplicate of `always_on_core()` kept for the host path that is hookless, which a test holds to the generator (`tests/test_context.py::OutputStyleMirrorsCore`). Not generated: an edit to [CORE](#core) must be carried into it by hand - a lesson the local `.tezgah/lessons.md` ledger holds; that file is untracked by design, so it carries no `path:line` here.
+
+### nudge
+The one-time hint that sends a first identifier-shaped search to the code graph, `first_nudge()` consuming a per-session mark before the grep is denied (`hooks/tezgah_gate.py::first_nudge`) with the text naming the graph tools (`nudge_reason()`, `hooks/tezgah_gate.py::nudge_reason`). Not a deny: it is spent by being delivered, and the identical call passes on the retry.
+
+### observable measure
+A used-mark a surface is able to see at all, so it can say "armed, not used yet" without inventing it: `health_segments(observable=...)` (`hooks/tezgah_context.py::health_segments`) with the five tool-use measures in `TOOL_USE_MEASURES` (`hooks/tezgah_context.py::TOOL_USE_MEASURES`), a measure outside the set rendering as `info` rather than `ready`. Which host can see a skill read is [hosts](hosts.md)'s.
+
+### once-only
+A mark consumed by its own first use, so the thing it protects happens once: the grep [nudge](#nudge) is written before the deny so later greps pass (`hooks/tezgah_gate.py::decision`). Not a licence for the session: the identical call passes on the retry.
+
+### per-repo mark
+An opt-out file in the repo tree - `.no-ponytail`, `.no-adhd`, `.no-graph`, `.no-lessons`, `.no-taste` - collected by `repo_marks()` walking up to the enclosing root (`hooks/tezgah_context.py::repo_marks`). Not a [kill switch](#kill-switch): a mark travels with the repo, a switch with the machine.
+
+### plan
+A piece of work spanning sessions, one markdown file with frontmatter under `<repo root>/.tezgah/plans/open/`, moved to `.tezgah/plans/done/` when closed, up to three of them injected by `open_plans()` (`hooks/tezgah_context.py::open_plans`) and its work happening on a `plan/NNN-slug` branch. Not a TODO in code.
+
+### plan table
+The status table in `.tezgah/plans/README.md` (`.tezgah/plans/README.md:9`), owned by the `plan-status` skill (`skills/plan-status/SKILL.md:1`) and among the first blocks the [budget](#budget) gives up because it lives on disk (`hooks/tezgah_context.py::DROP_ORDER`). Not the injected list of open plans.
+
+### plugin copy
+Claude's own copy of this checkout under `~/.claude/plugins/cache`, from which its hooks and skills actually run, found by `plugin_copies()` (`bin/tezgah-setup::plugin_copies`) and refreshed by `sync()` against the fingerprint file (`bin/tezgah-setup::sync`, `bin/tezgah-setup::PLUGIN_FINGERPRINT`). Not the checkout: a stale copy lags HEAD until `tezgah-setup --sync`.
+
+### pointer
+The one-line always-on stand-in for the [conditional rules](#conditional-rule), naming each so a host without a per-turn hook still knows the rule exists, `POINTERS` (`hooks/tezgah_policy.py::POINTERS`). Not a rule.
+
+### probe
+A small side effect tezgah makes when an answer cannot be read directly: a write probe to decide whether a directory is usable (`hooks/tezgah_paths.py::writable_dir`), and the cached git fork that decides whether the graph stamp is behind HEAD (`hooks/tezgah_context.py::index_mark`). Not a check of the work.
+
+### reminder
+The compact per-turn text every user turn pays for, `PROMPT_REMINDER` (`hooks/tezgah_policy.py::PROMPT_REMINDER`), injected as the `reminder` block (`hooks/tezgah_context.py::context_for`) and carrying the standing constraints rather than the long rationale. Not [CORE](#core), which is paid once per session.
+
+### rollback
+Putting a [snapshot](#snapshot)'s bytes back, `restore()` (`hooks/tezgah_snapshot.py::restore`), reached only through `tezgah-rollback` (`bin/tezgah-rollback:2-13`), which writes a `rollback` row (`hooks/tezgah_snapshot.py::restore`). Tezgah never rolls back on its own.
+
+### root
+A directory tezgah is armed over, from `TEZGAH_ROOTS`, the config file or `~/Projects` (`hooks/tezgah_paths.py:8-14`), resolved by `roots()` longest first (`hooks/tezgah_paths.py::roots`) and looked up per path by `root_for()` (`hooks/tezgah_paths.py::root_for`); a linked `git worktree` outside every root is inside when its main checkout is, and answers its own top level (`worktree_top`, `hooks/tezgah_paths.py::worktree_top`). Not a repository: one root may contain many repositories.
+
+### root boundary
+The edge of a root: outside every root the gate returns nothing (`hooks/tezgah_gate.py::decision`), the context builder returns nothing (`hooks/tezgah_context.py::context_for`) and the per-repo extras are omitted from the status line (`hooks/tezgah_context.py::health_segments`). Not a repository boundary.
+
+### row
+One line of an [evidence ledger](#evidence-ledger): `{"kind","ts","detail"}` plus whatever the writer knew of `LEDGER_FIELDS` (`id`, `exit`, `out_bytes`, `fail_class`, `workspace`, `source`, `hash`, `changed`, `tool`), written by `note_path()` (`hooks/tezgah_integrity.py::note_path`, `hooks/tezgah_integrity.py::_stored_text`) with `detail` redacted and cut to `DETAIL_MAX` (`hooks/tezgah_integrity.py::DETAIL_MAX`). A missing key means the writer did not know it, never null. `tool` is the call's own name where the host reports one, which is what makes a firing histogram possible: `classify` folds the name into `run`/`edit`, so a row that predates the field carries none.
+
+### rule
+One bold-labelled paragraph of the contract, the unit a [kill switch](#kill-switch) drops and a test pins: `CORE_RULES` pairs each key with the label it must start with (`hooks/tezgah_context.py::CORE_RULES`) and `core_split()` drops exactly the paragraph whose label matches (`hooks/tezgah_context.py::core_split`). Not a [skill](#skill), which the model chooses to read.
+
+### session
+One host conversation, identified by the id `session_of()` reads from a payload under whichever name the host uses (`hooks/tezgah_context.py::session_of`), keying the [ledger](#evidence-ledger) filename (`hooks/tezgah_integrity.py::_slug`), the [session store](#session-store) and the per-turn markers (`note_turn()`, `hooks/tezgah_integrity.py::note_turn`). Not a [turn](#turn), of which one session has many.
+
+### session store
+The used-tool marks one session wrote, `<cache>/sessions/<slug>.jsonl`, appended by `record()` (`hooks/tezgah_context.py::record`) and read by `used()` (`hooks/tezgah_context.py::used`) to feed the "used" half of the status marks, with a missing kind recorded nowhere at all. Not the [evidence ledger](#evidence-ledger).
+
+### skill
+`skills/<name>/SKILL.md` - frontmatter with `name` and `description`, then instructions the model reads by choice; [skills](skills.md) owns the layer. Not a [rule](#rule), which is injected, and not a [slash command](#slash-command).
+
+### skill read
+A read of a tezgah skill's own `SKILL.md` earning a used mark, `skill_read_kind()` matching on the path (`hooks/tezgah_context.py::skill_read_kind`), which is the only signal that the full rule text reached the session, and only `ponytail` and `i-have-adhd` carry a mark (`SKILL_MARKS`, `hooks/tezgah_context.py::SKILL_MARKS`). Not a general read.
+
+### skill router
+The generated list that stands in for a skill index where a host has none, `~/.config/tezgah/opencode-skills.md` always-on and `.full.md` on demand (`bin/tezgah-setup::SKILL_ROUTER`, `bin/tezgah-setup::SKILL_ROUTER_FULL`), built by `skill_router_texts()` from `skill_groups()` (`bin/tezgah-setup::skill_groups`, `bin/tezgah-setup::skill_router_texts`). Not a directory listing: each line is name, trigger and path ([skills](skills.md)).
+
+### slash command
+A file under `commands/` wired only through the Claude plugin channel and named with the plugin's prefix (`/tezgah:plan-sync`), installed by no other host ([skills](skills.md)). Not a [skill](#skill), though one feature may be both.
+
+### snapshot
+The stored pre-write bytes of one file plus its manifest, created by [capture](#capture) and read only by [rollback](#rollback) (`hooks/tezgah_snapshot.py:2-17`), the capture also writing a `snapshot` row whose `detail` is the file's realpath and whose `hash` is its pre-write sha256 (`hooks/tezgah_snapshot.py::_capture_one`). Not a checkpoint of the session, only of the files a write was about to change.
+
+### source
+The ledger field naming the untrusted channel a result came through - `web`, `mcp`, `network` or `tier` - set only when there was one (`hooks/tezgah_integrity.py::note_tool`, `hooks/tezgah_integrity.py::untrusted_source`), a missing `source` meaning the user or this workspace, which is what every reader assumes. Not a record of what the content said.
+
+### state
+The value of one status [mark](#mark): `on`, `ready`, `off` or `info` (`hooks/tezgah_context.py::health_segments`), drawn as `✓ ○ ✗` or nothing by `GLYPHS` (`hooks/tezgah_context.py::GLYPHS`) and mapped to a colour by `COLORS` (`hooks/tezgah_context.py::COLORS`), with `off` winning over the observable test because a kill switch is visible everywhere ([status-line](status-line.md)). Not a glyph, which is only how the state is drawn.
+
+### step kind
+One of the row kinds that count as a step of work - `run`, `edit`, `verify`, `verify_ok`, `verify_fail`, `interrupted` (`STEP_KINDS`, `hooks/tezgah_integrity.py::STEP_KINDS`), summed into `steps` and into the drift threshold, while `deny`, `nudge`, `claim` and `turn` are the machinery around the work (`hooks/tezgah_integrity.py:1350-1352`). `interrupted` is the one that is not a failure: the host said the call was stopped, so the row carries no `exit` and no `fail_class`, no reader folds it as a failed check and no attempt is spent on it (`hooks/tezgah_integrity.py:1356-1359`). Not any row.
+
+### Stop rule
+The end-of-turn refusal, `stop_reason()` (`hooks/tezgah_integrity.py::stop_reason`), run by the Stop hooks of Claude, Codex, Cursor and omp (`hooks/projects-stop.py::main`, `hosts/codex/hook.py::main`, `hosts/cursor/hook.py::dispatch`, `hosts/omp/hook.py::handle`): it blocks on a placating opener or a banned sign-off on the last prose line, on a completion claim the newest check does not support, on a check that passed before the newest write the gate saw change the tree, or on a turn that recorded work with no passing check (`_stop_block()`, `hooks/tezgah_integrity.py::_stop_block`), and an explicit "doğrulanmadı" clears it. A claim in a turn with no work is judged against the whole session, and a read-only or VCS-bookkeeping turn after a pass on an unchanged tree is exempt ([evidence](evidence.md#the-stop-rule-end-to-end)). Not the [gate](#gate), which runs before a call ([evidence](evidence.md)).
+
+### surface
+A place a host can show tezgah's output - a status line, a TUI widget, a `systemMessage` - and therefore the reason the same [marks](#mark) render differently per host (`hooks/tezgah_context.py::health_segments`, `hooks/tezgah_context.py::render_line`); each host's surfaces are [hosts](hosts.md)'s. Not the host itself.
+
+### taint
+The state of a turn that has read content tezgah cannot vouch for and not yet marked an effect, `turn_channel()` (`hooks/tezgah_untrusted.py::turn_channel`) plus the line the model reads on the next effect, `taint_notice()` (`hooks/tezgah_untrusted.py::taint_notice`). A state, not a verdict: whether the content caused the write is not observable.
+
+### turn
+One user prompt and everything before the next one, delimited on the ledger by a `turn` marker row written by `note_turn()` (`hooks/tezgah_integrity.py::note_turn`) and found by `_turn_start()` (`hooks/tezgah_integrity.py::_turn_start`), with the loop guard's count, the drift threshold and the [taint](#taint) all turn-scoped. Not a request/response pair.
+
+### untrusted content
+A result that arrived from outside the user and this workspace - a fetched page, an MCP server's answer, a shell read that left the machine, or the tier's own answer (`bin/consult`, `bin/codegen`: a model over the network, however deliberately the session asked for it) - named by `untrusted_source()` and labelled by `untrusted_label()` (`hooks/tezgah_integrity.py::untrusted_label`, `hooks/tezgah_integrity.py::untrusted_source`), the label and the [taint](#taint) notice being `hooks/tezgah_untrusted.py:2-22`. Not a deny: the model may use the text, but instructions inside it are data, never a request.
+
+### used kind
+The tool kind a session was observed to use, one word per call, recorded by `record()` (`hooks/tezgah_context.py::record`) and read by `used()` (`hooks/tezgah_context.py::used`) to turn an armed mark into a used one, with `shell_kind()` and `skill_read_kind()` as the classifiers. Not a [step kind](#step-kind): this is the status line's vocabulary, not the ledger's.
+
+### vendored
+Copied into this repository from an upstream project and kept, with its licence, rather than depended on: `skills/ai-research` is the large case (`ai_research_dir()`, `hooks/tezgah_paths.py::ai_research_dir`), and a vendored file carries a `<!-- vendored from ... -->` header checked against a manifest (`tests/test_ai_research_library.py::VendoredTree.test_every_manifest_file_is_present_and_unchanged`, `tests/test_ai_research_library.py::VendoredTree.test_every_vendored_file_is_attributed`). Not a git submodule.
+
+### verify
+The [kind](#kind) family for a check: `verify` when it ran but no outcome was seen, `verify_ok` when the host reported exit 0 with output on an unmasked command, `verify_fail` when it failed (`note_tool()`, `hooks/tezgah_integrity.py::note_tool`, with `passing_check()` as the acceptance test, `hooks/tezgah_integrity.py::passing_check`). Only `verify_ok` supports a "done" claim; it is not the check's own result, since the ledger records what the host reported. An `interrupted` row sits outside the family: the host said the call was stopped rather than answering it, so there is no outcome to be one of the three (`hooks/tezgah_integrity.py::note_tool`).
+
+### version prefix
+The product's own name and version at the head of the [status line](status-line.md), `tezgah v1.0.0`: one segment from `version_segment()` (`hooks/tezgah_context.py::version_segment`) carrying no glyph and the [state](#state) `info` - nothing is armed or used by it - and a group of its own, so the marks separate from it the way the groups separate from one another. Its number comes from `version()` (`hooks/tezgah_context.py::version`), the one reader `bin/tezgah-setup --version` also calls: the local plugin manifest, else the newest release heading in `CHANGELOG.md`, read bounded and never raising, and an unreadable version leaves the bare name rather than a placeholder. Not a [mark](#mark): a mark reports a switch or a capability, this reports which build is talking.
+
+### workspace
+The ledger field naming which [root](#root) a row happened under, `root_for(cwd)` (`hooks/tezgah_integrity.py::note_tool`), recorded so a refusal can say where it was stopped. Not the cwd the call ran in, and not the repository.
+
+## Source of truth
+- `hooks/tezgah_context.py` - the injected text, the status segments, used marks, budget, per-repo marks
+- `bin/tezgah-status`, `bin/tezgah-rollback` - the CLI side of the status marks and rollback
+- `hooks/tezgah_gate.py` - `decision()` and every refusal rule
+- `hooks/tezgah_integrity.py` - the ledger contract, kinds, claims, the Stop rule
+- `hooks/tezgah_paths.py` - roots, kill switches, hosts, the cache dir, probes
+- `hooks/tezgah_snapshot.py` - capture, snapshots, rollback
+- `hooks/tezgah_untrusted.py` - the untrusted label and the taint notice
+- `bin/tezgah-setup` - the bands, the plugin copy, the skill router