@r1z4x/tezgah 1.0.0

package/docs/skills.md

@@ -0,0 +1,236 @@
+# Skills: what ships, and how one reaches a host
+
+Read this when you are asking what a skill is in tezgah, how one reaches a [host](glossary.md#host),
+or how to add one without breaking the router or the install report. It owns the
+skill layer: the files under `skills/`, the router that lists them, and the
+install step that links them. The always-on rule text a session is told is
+[contract](contract.md)'s subject; each host's surfaces are [hosts](hosts.md)'s.
+
+## What a skill is
+
+A skill is `skills/<name>/SKILL.md`: YAML frontmatter carrying `name` and
+`description`, then a markdown body. The body is instructions for the model - the
+read tool opens it, nothing executes it. `plan-add` and `ponytail` also declare
+`argument-hint` in that frontmatter (`skills/plan-add/SKILL.md:11`,
+`skills/ponytail/SKILL.md:16`), and Claude exposes each skill as
+`/tezgah:<name>` - a bare `/plan-add` is a command that does not exist
+(`tests/test_skills.py::SkillStandards.test_slash_commands_carry_the_prefix_the_plugin_registers`).
+
+Two neighbours are not skills. A **slash command** is a file under `commands/`
+wired only through the Claude plugin channel - `commands/ponytail.md` and
+`commands/adhd.md` are shells over `tezgah-pony` and `tezgah-adhd`, and no other
+host installs them (`commands/` appears nowhere in `bin/tezgah-setup`). Its name
+is prefixed with the plugin's, so the command is `/tezgah:plan-sync` and a bare
+`/plan-sync` does not exist (`tests/test_skills.py::SkillStandards.test_slash_commands_carry_the_prefix_the_plugin_registers`). An **always-on
+rule** is text injected into every turn by the client hooks, defined in
+`hooks/tezgah_policy.py::CORE`; the model cannot choose not to load it,
+and only the on-demand tail of it points at a skill, `tezgah-contract`
+(`hooks/tezgah_policy.py::POINTERS`). A rule is disarmed with a [kill switch](glossary.md#kill-switch); a
+skill is simply not read.
+
+## The router
+
+opencode's plugin does inject prompt-time text - the builder's per-turn block,
+the conditional rules included
+(`hosts/opencode/plugins/tezgah.js:2596-2625`) - but that text names at most one
+skill (the hint), never the roster, so the installer writes one:
+`~/.config/tezgah/opencode-skills.md` always-on and
+`opencode-skills.full.md` on demand (`bin/tezgah-setup::SKILL_ROUTER`, `bin/tezgah-setup::SKILL_ROUTER_FULL`), the first
+listed in opencode's `instructions` (`bin/tezgah-setup::install_opencode`). Its native
+skill list and `skill` tool are switched off in the same pass -
+`permission.skill = "deny"` (`bin/tezgah-setup::install_opencode`) - so the generated file is
+the only list that host has.
+
+The router is generated, not written: `skill_groups()` walks the installed skill
+directories in precedence order - this checkout's `skills/`, then opencode's,
+Claude's and `~/.agents/skills` - takes the first directory that defines a name,
+buckets each by `skill_category()` and returns the groups
+(`bin/tezgah-setup::skill_groups`). Buckets are `tezgah core`, `code & host tooling`,
+`research & papers`, `AI research & engineering`, `marketing & growth`; the first
+two are listed always-on and the rest collapse to a count line pointing at the
+full file (`bin/tezgah-setup::ROUTER_ALWAYS`, `bin/tezgah-setup::skill_router_texts`). `ai-research` is the one
+exception: it stays named in the always-on file under `research (tezgah's own)`
+because a library a session is never told about is one it answers from memory -
+measured on a live opencode turn that read nothing and answered anyway
+(`bin/tezgah-setup::skill_router_texts`).
+
+Each line is `name - trigger - path`, and the trigger is one sentence pulled from
+the frontmatter `description` by `skill_description()` (`bin/tezgah-setup::skill_description`,
+`bin/tezgah-setup::_router_section`). **The sentence carrying the `Use when ...` trigger wins over the
+opening one.** A line built from the first sentence is what shipped, and it
+stripped `tezgah-contract` and `ponytail` of every word a session matches on -
+`tezgah-contract`'s description opens with "The full tezgah working contract." -
+leaving both unroutable. The rule is pinned on a synthetic `SKILL.md`, not only on
+the two shipped ones (`tests/test_setup.py::SkillTriggerLine`), and the live router's own
+lines are asserted to carry their trigger words (`tests/test_setup.py::SkillRouterTriggers.test_core_skill_lines_carry_their_trigger`).
+A line is cut at 140 characters with a trailing `...`; a description with no
+trigger sentence keeps its first sentence.
+
+The on-demand file also carries a **collision table**: the pairs among tezgah's
+own skills whose descriptions share three or more subject words, computed from
+the router lines themselves (`skill_collisions()`, `bin/tezgah-setup::skill_collisions`).
+It rides `opencode-skills.full.md` and never the always-on file, because it is
+read when a session is about to choose, not every turn. It is a view, not a
+rename: it names `plan-add` / `plan-status` / `plan-sync` and
+`design-contract` / `design-library` side by side, and leaves the choice to the
+session. `tests/routing-fixtures.md` is the other half - situation to skill, with
+the word the router line has to keep - and
+`tests/test_setup.py::RoutingFixtures` fails when a reworded description drops
+one, or when a shipped skill has no fixture at all.
+
+Every other host gets the same idea natively: the skills are linked into the
+directory that host reads, and the host lists `name` + `description` itself -
+which is why the installer counts that metadata as an always-on cost
+(`bin/tezgah-setup::context_budget`).
+
+## How a skill reaches a host
+
+`SKILLS` in `bin/tezgah-setup::SKILLS` is the shipped list, and it is the single
+definition of "a tezgah skill": the router, the per-host linking, the uninstall
+and the context budget all read it. Each install function links those
+directories into the host's own skill directory - Codex
+(`bin/tezgah-setup::install_codex`), opencode (`bin/tezgah-setup::install_opencode`), Cursor (`bin/tezgah-setup::install_cursor`), dsh
+(`bin/tezgah-setup::install_dsh`), omp (`bin/tezgah-setup::install_omp`). Claude is the exception: it installs from a
+plugin, so the skills arrive in the COPY at
+`~/.claude/plugins/cache/<marketplace>/tezgah/<version>/` that `--sync` refreshes
+and `--install` re-refreshes when it is stale (`bin/tezgah-setup:26-29`,
+`bin/tezgah-setup::sync`, `bin/tezgah-setup::refresh_plugin_copy`). On Claude the plugin name prefixes the skill name -
+`Skill(tezgah:ponytail)` (`hooks/tezgah_policy.py::PONYTAIL`).
+
+The install report checks the file, not the link. `skills_linked()` requires
+every name in `SKILLS` to resolve to a readable `SKILL.md` under the host
+directory (`skills_linked()`, `bin/tezgah-setup::skills_linked`), and it is used for every host row
+(`bin/tezgah-setup::host_checks_codex`, `bin/tezgah-setup::host_checks_opencode`, `bin/tezgah-setup::host_checks_cursor`, `bin/tezgah-setup::host_checks_dsh`, `bin/tezgah-setup::host_checks_omp`). It was
+`islink()` once, and a link to nothing is a link: a name whose `SKILL.md` was
+never written reported as linked on every host at once while no host could read
+it (`tests/test_skills.py::SkillStandards`).
+
+## The shipped skills
+
+| Skill | What it is for, and when it fires |
+|---|---|
+| `harness` | Picks and runs the right multi-agent harness on top of the code graph; fires on an audit, "every call site", "what breaks if", or a task too wide for one context window. |
+| `tezgah-contract` | The full contract behind the always-on core - graph rule, harnesses, orchestration, codegen, consult, kill switches; loads when the core points here or a task needs that detail. |
+| `ponytail` | Forces the laziest solution that works, in levels lite/full/ultra; fires on any coding task, or "be lazy", "yagni", "shortest path". |
+| `i-have-adhd` | Shapes output for a reader who acts on it - action first, numbered steps, errors as location/cause/fix; fires on any answer the reader must act on, not on code, commits or docs. |
+| `no-ai-slop` | Edits a draft sharper and more human without losing the voice, or flags slop; fires on a draft review, on a draft in a language other than English, on text that must keep terms, identifiers or unit symbols verbatim, and before publishing English prose tezgah writes itself. |
+| `analyze-app` | Inspects and drives a running web or mobile app from its accessibility / DOM / view tree, its rendered screen (screenshots, blur and grayscale tests, breakpoints) and measurements taken in the page; fires when a task must verify behaviour or read the UI, not just read source. |
+| `plan-add` | Creates a plan under `.tezgah/plans/open/` with its own `allowed_paths:` scope, bootstraps the `.tezgah/plans/` layer if missing, commits it in the private `.tezgah` repository (`git -C .tezgah`, never the project's git); fires on `/tezgah:plan-add`, "track this as a plan". |
+| `plan-status` | Reads every open plan, enriches rows with live PR state from `gh`, rewrites the README table (committed in the private `.tezgah` repository) and recommends the next plan; fires on `/tezgah:plan-status` or "what plans are open". |
+| `plan-sync` | Closes finished plans whose PR merged or closed through `tezgah-task close`, which moves a plan to `.tezgah/plans/done/` as done only when it records an approving `review:`; commits one message per plan in the private `.tezgah` repository; fires on `/tezgah:plan-sync`, "sync plans". |
+| `research` | Runs an auditable research line - two loops, protocol before run, six-dimension review, provenance; fires when the deliverable is evidence: a lit review, a hypothesis, a benchmark or ablation. |
+| `product-analysis` | Runs a product analysis across five axes - value (HEART), usability (heuristics, the cognitive walkthrough, WCAG 2.2, axe-core, the running app read through `analyze-app` down to component x state, tree and image both), feasibility (a cited `path:line`), competition (a dated teardown) and triage (keep/fix/cut/bet) - with one named evidence class per finding, executed as a research line; fires on a product, feature, retention or roadmap question rather than a code change. |
+| `pm-frameworks` | The two vendored product methods the analysis skill defers to - intended-vs-implemented and the Opportunity Solution Tree - kept offline so an offline session reads the method instead of citing its name. |
+| `feature-audit` | Audits ONE feature across every layer it is spread over - the surfaces a person uses (a control, a list or table, a detail view, a filter, a picker, a step flow, a notification), the route, the authorization, the service and the data - by filling the capability, field-contract, flow/step and interaction-dependency matrices, where a disagreement between layers is a finding and a fix needing an absent capability becomes a capability-change proposal; fires on an admin screen, CRUD, form, wizard, data table, filter or permission question about an existing feature. |
+| `design-contract` | The artifact shape of the per-repo `.tezgah/design-contract.md` - colour roles, type scale, spacing unit and rhythm, the component inventory, the state set every interactive control and data view owes - the derivation rule that reads it out of the repository's own tokens, and the rules `bin/tezgah-design check` fails on; fires on a UI or component turn that needs a floor, a token, a state set, or the design check itself. |
+| `design-library` | The vendored MC Dean design/UX subset - 39 skills in the `cognitive-accessibility`, `adaptive-interfaces`, `inclusive-interaction`, `visual-critique` and `design-research` plugins - read one entry at a time through its own `INDEX.md`, never the tree; fires when a UI or product turn needs a cognitive-load, inclusive-interaction or visual-critique method tezgah has no counterpart for. |
+| `ai-research` | The vendored 98-skill library for AI/ML machinery - training and serving a model, benchmarks, interpretability, retrieval pipelines; read one entry, never the tree. |
+| `rl-env` | The vendored FineEnvs skill set for authoring an RL environment from a description - OpenEnv, OpenReward/ORS, Verifiers and NeMo Gym, plus the orchestrator that ports one description across all four; read one entry, never the tree. |
+
+## Vendored material
+
+`NOTICE` records every third-party skill and its terms: it opens by saying the
+root MIT LICENSE covers tezgah's own files while these copies keep their
+original terms ([NOTICE:1-2]), and an adapted entry adds what the adaptation
+changed. A test fails if the adapted upstream or its licence stops being named
+(`tests/test_skills.py::SkillStandards.test_notice_records_the_adapted_upstream_and_its_licence`). `skills/no-ai-slop`, `skills/ponytail`,
+`skills/i-have-adhd`, `skills/research`, `skills/product-analysis`,
+`skills/pm-frameworks` and `skills/ai-research` are MIT; `skills/rl-env` is
+Apache-2.0 and keeps that repository's terms.
+`i-have-adhd` is adapted (the ten rules kept, two rewritten, the user-invocation
+frontmatter dropped so the router can reach it); `research` adapts the
+orchestration layer of Orchestra Research's AI-research-SKILLs library and copies
+nothing verbatim; `ponytail`'s origin was not recorded at vendoring time. In
+every case the entry names the upstream, and an adapted entry says what the
+adaptation changed - the same record an added adaptation is expected to carry.
+
+`skills/ai-research` is the large vendored tree: 98 upstream skills in 23
+categories, bodies byte-for-byte upstream including frontmatter and `author`
+lines, at revision `773a52944ba4747a18bd4ae9ade53fff041adcbc`
+([skills/ai-research/SOURCE:1-20]). No machine-scraped reference dumps and no
+LaTeX template trees were copied, and every drop is named in that file.
+`bin/tezgah-import-ai-research --check` verifies the tree against its manifest.
+
+`skills/rl-env` is the Apache-2.0 one: the five FineEnvs environment-authoring
+skills - `rl-env-from-description` plus the four framework ports - and every
+reference file they ship, 14 bodies byte-for-byte from
+`adithya-s-k/FineEnvs` at revision `26ab9c6` ([skills/rl-env/SOURCE:1-6]),
+under `skills/rl-env/<skill>/` at their upstream path. Nothing is adapted.
+Upstream's own install route is not used here: `npx skills add
+adithya-s-k/FineEnvs` writes into a host's skill directory, which the router
+does not read, the install report does not list and `SOURCE` cannot vouch for -
+the vendored copy is what the router reaches. The entry point
+`skills/rl-env/SKILL.md` is tezgah's own and is not in the manifest, and it is
+the file that says what the vendored bodies cannot: this repository runs no
+trainer, so an environment they build needs a machine that does.
+
+`skills/pm-frameworks` is the small one: two product-management methods -
+`intended-vs-implemented` and `opportunity-solution-tree` - byte-for-byte from
+`phuryn/pm-skills` at revision `8607e3b077817f89bf4a9b623246219734ac3be0`
+([skills/pm-frameworks/SOURCE:1-5]). Its manifest is the table in `SOURCE`, and
+`tests/test_skills.py` hashes each listed body and fails on an unlisted directory
+beside them; the entry point `SKILL.md` is tezgah's own and is not in it.
+
+`skills/design-library` is the adapted one: 39 skills from two Owl-Listener
+repositories - `inclusive-design-skills` at `6e0740f` (the whole
+cognitive-accessibility, adaptive-interfaces and inclusive-interaction plugins)
+and `designer-skills` at `9a6930c` (visual-critique, and two design-research
+skills) - both MIT, vendored at the upstream path under those five plugin
+directories, with `INDEX.md` as the routing surface and `EVALS.md` as the three
+trap cases the library is scored against. Two bodies depart from upstream, and
+`skills/design-library/SOURCE` and `NOTICE` name both: the touch-target entry
+paired `44x44 CSS pixels` with `WCAG 2.2 Level AA`, where SC 2.5.8 is Level AA at
+24x24 and SC 2.5.5 is Level AAA at 44x44 - 24 is the floor `bin/tezgah-design`
+enforces - and `adaptive-personalisation/SKILL.md` carried the sibling
+`contextual-help-design` skill's `name`, which a host that loads a skill from its
+directory skips. `tests/test_skills.py` hashes every listed body, fails on an
+unlisted directory, and fails on a body that pairs 44x44 with Level AA again.
+
+## Adding a skill
+
+1. Write `skills/<name>/SKILL.md` with frontmatter carrying `name` and a
+   `description` whose **later** sentence begins `Use when ...` - that sentence
+   is the router line, and it must carry the words a session would match on
+   (`bin/tezgah-setup::skill_description`).
+2. Add the name to `SKILLS` (`bin/tezgah-setup::SKILLS`). `SKILLS` drives the
+   router, the linking, the uninstall and the budget; a name without a
+   `SKILL.md`, or a directory without a `SKILLS` entry, is not a shipped skill.
+3. Expect `tests/test_skills.py::SkillStandards` to fail if the two disagree, and
+   `tests/test_setup.py::SkillRouterTriggers.test_core_skill_lines_carry_their_trigger` to fail if the generated router line lost its
+   trigger words. Re-run `--install` (or opencode's `--refresh`,
+   `bin/tezgah-setup::refresh_contract`) so the written routers pick the skill up.
+4. Add a row to `tests/routing-fixtures.md`: situation, the skill, and the word
+   the router line has to keep. `RoutingFixtures` fails on a shipped skill with
+   no row, and on a row whose word a reworded description dropped. The
+   frontmatter lint in `tests/test_skills.py::Frontmatter` then holds the entry
+   point itself: name equals directory, kebab-case, a `Use when` sentence, a
+   description under the metadata cap, every backticked cross-reference
+   resolving. Vendored trees are exempt there - their frontmatter is upstream's
+   bytes, pinned by that library's own hash test.
+5. Quote examples in a form the tests accept: no floating `@latest` package tag
+   and any pinned package spec must match the one tezgah wires
+   (`tests/test_skills.py::SkillStandards`); slash commands carry the `tezgah:` prefix
+   (`tests/test_skills.py::SkillStandards.test_slash_commands_carry_the_prefix_the_plugin_registers`); no unrendered placeholder such as
+   `<repo slug>` (`tests/test_skills.py::SkillStandards.test_no_unrendered_placeholder_reaches_the_injected_text`); every kill switch named in
+   `CORE` appears in `tezgah-contract` (`tests/test_skills.py::SkillStandards`); a rule
+   added to the contract must also reach the skill
+   (`tests/test_setup.py::ContractParity.test_every_rule_and_heading_in_the_contract_reaches_the_skill`).
+
+## Source of truth
+
+- `bin/tezgah-setup` - `SKILLS`, `skills_linked()`, `skill_description()`,
+  `skill_category()`, `skill_groups()`, `skill_router_texts()`, the collision
+  table (`skill_collisions()`), the per-host `install_*` linking, `--sync`, the
+  report rows
+- `skills/*/SKILL.md` - the shipped skills and their frontmatter
+- `commands/ponytail.md`, `commands/adhd.md` - the Claude-only slash commands
+- `NOTICE`, `skills/ai-research/SOURCE`, `bin/tezgah-import-ai-research`
+- `skills/design-library/SOURCE`, `INDEX.md`, `EVALS.md` - the adapted library,
+  its index and its three trap cases
+- `skills/rl-env/SOURCE` - the vendored FineEnvs environment-authoring set, its
+  upstream revision and the per-file sha256
+- `hooks/tezgah_policy.py` - the always-on rule text and the Claude skill name
+- `tests/test_setup.py`, `tests/test_skills.py` - the router-line, name
+  resolution, frontmatter, collision and skill-standard tests
+- `tests/routing-fixtures.md` - situation to skill, with the word the router line
+  has to keep

package/docs/status-line.md

@@ -0,0 +1,315 @@
+# Status line: what each mark means and how it is drawn
+
+Every [host](hosts.md) shows one line: what tezgah has armed, what this session
+has used, and what this repo adds. Read it when you add a
+[mark](glossary.md#mark), when no line is drawn, or when a mark shows a state you
+cannot explain. As this repository prints it:
+
+    tezgah v1.0.0  ·  pony○ exec✓ adhd○  ·  consult○ research○ graph○ orch○ judge○  ·  idx✓  ·  plans 1
+
+## Shape: segments, groups, separator
+
+One mark is one segment — `{"key", "state", "glyph", "text", "group"}` — built
+host-neutrally by `health_segments()` (`hooks/tezgah_context.py::health_segments`).
+`render_line()` joins segments with one space inside a group and `  ·  ` between
+groups (`hooks/tezgah_context.py::render_line`). The group is *data on each segment*: a renderer building its
+own line from `--json` separates on `seg.group` and matches `render_line()`
+without a second copy of the partition (`hooks/tezgah_context.py::health_segments`) — opencode and dsh do exactly
+that (hosts/opencode/tui/tezgah-tui.tsx:108-111,
+hosts/dsh/statusline/lib/client.js:86-90).
+
+| group | members | why together |
+|---|---|---|
+| -1 | the version prefix | the product itself, before any mark |
+| 0 | `pony`, `exec`, `adhd` | the always-on switches |
+| 1 | `consult`, `research`, `graph`, `orch`, `judge` | the on-demand capabilities |
+| 2 | `idx` | a per-repo fact: code-graph readiness |
+| 3 | `plans` | a per-repo fact, its own group |
+
+Groups 0 and 1 come from `_GROUP` (`hooks/tezgah_context.py::_GROUP`); the prefix
+carries -1 and `idx` and `plans` carry 2 and 3 where they are appended (`hooks/tezgah_context.py::version_segment`, `hooks/tezgah_context.py::health_segments`). Outside every
+[root](glossary.md#root) the checklist still prints — tezgah loads globally on
+opencode, so the indicator must not go silent — and only the per-repo extras are
+omitted (`hooks/tezgah_context.py::health_segments`, `tests/test_statusline.py::test_outside_roots_still_shows_segment`).
+
+### The version prefix
+
+The line opens with `tezgah v1.0.0` (`version_segment()`, `hooks/tezgah_context.py::version_segment`): not a [mark](glossary.md#mark) — no glyph, and `info`, the state that reports none — with a group of its own, so the marks separate from it the way the groups separate from each other; its segment carries the number as `version` for a program reading `--json`.
+The number is the one reader `bin/tezgah-setup --version` also calls (`version()`, `hooks/tezgah_context.py::version`, `bin/tezgah-setup::plugin_version`): the local plugin manifest, else the newest `CHANGELOG.md` release, read bounded and never raising; unreadable, the prefix keeps the bare name rather than a placeholder.
+
+When a newer release is out, a `↑X.Y.Z` chip follows the version in the same group. So it stays beside the logo at every width tier (`with_update_notice()`, `notice_segments()` in `hooks/tezgah_update.py`). It is drawn in the `ready` color and its segment carries the number as `version`. A redraw reads a cached answer and never the network. A detached check refreshes that answer at most once a day. `tezgah update` takes the release, and `update-check-off` turns the chip and the check off.
+
+## States
+
+`LEGEND` (`hooks/tezgah_context.py::LEGEND`) is the source for this table; run
+`tezgah-status --legend` to print it verbatim.
+
+| state | glyph | color | asserts |
+|---|---|---|---|
+| `on` | `✓` | green | armed and in force this session (or always-on) |
+| `ready` | `○` | yellow | armed, on demand — not used yet this session |
+| `off` | `✗` | red | turned off by a [kill switch](glossary.md#kill-switch) or a per-repo `.no-*` mark |
+| `info` | none | dim | no state: `idx` n/a or uncomparable, no blocked plan, or a measure this surface cannot report |
+
+Glyphs are `GLYPHS`, colors `COLORS` (green 32, yellow 33, red 31, dim 2; `hooks/tezgah_context.py::GLYPHS`, `hooks/tezgah_context.py::COLORS`).
+The whole `text`+`glyph` chip is colored, and the glyph is drawn in every state:
+color is additive, never the only carrier of the state — the accessibility rule
+(`_seg_text()`, `hooks/tezgah_context.py::_seg_text`). `idx` is the one exception: its glyph *is* the index's
+state, mapped back by `IDX_STATE` (`hooks/tezgah_context.py::IDX_STATE`).
+
+On a colored surface the line opens with the logo (`LOGO`): three upper half
+blocks draw the amber worktop of `assets/logo/tezgah-logo.svg` (#FFC55C) and the
+middle one's background is its single support in the logo's teal accent
+(#17A18C - its slate faces, #2A4657, are a dark terminal's own background), so it
+reads as the logo's `t`. The logo names the product, so a colored head carries
+only the version, dim; the plain line keeps `tezgah vX.Y.Z`. The same half-block mark heads the line on every
+terminal; an inline-image logo is not drawn. On a light background the bright
+pair washes out, so the logo takes its darker faces (#B8761C worktop, #0E7C6B
+support) and the version drops the dim: omp's widget reads the theme's
+`isLight`, the other surfaces read `COLORFGBG` (a background index of 8 or more
+is light, the rule omp uses). While the omp agent works the T itself is the
+motion - a sheen sweeps its worktop left to right and runs down the support -
+with the running tool and its seconds right after it; a line without colors
+keeps the braille spinner. Each other chip leads with its icon
+(`ICONS`): `✂` pony, `▶` exec, `◎` adhd, `⚖` consult, `⚗` research, `⌬` graph, `⎇` orch,
+`⚑` judge, `⌕` idx, `⋮` plans. Every icon is a text-presentation symbol of East
+Asian width Neutral or Ambiguous (`▶`, `◎`), never Wide and never an emoji, so a
+terminal draws it one cell wide and the line does not overflow (a CJK terminal
+that draws Ambiguous two cells wide is the exception). `☰` was the plans icon
+until Unicode 16 (Python 3.14) made it Wide. The plain line
+(pipes, `--status`, Codex's `systemMessage`, omp's `setStatus` fallback) carries
+no icons and keeps its exact shape.
+
+## Per mark
+
+Flips come from the flag table and the resolution after it, both in
+`health_segments()` (`hooks/tezgah_context.py::health_segments`): `off` is decided first and always wins, then a
+measure the surface cannot see, then armed-and-used or armed-not-used.
+
+| mark | goes `on` when | goes `off` when |
+|---|---|---|
+| `pony` | the full ponytail skill text was read this session | `ponytail-auto.off`, or `.no-ponytail` |
+| `exec` | never used-gated: `on` as soon as armed | `exec-mode.off` |
+| `adhd` | `skills/i-have-adhd/SKILL.md` was read this session | `adhd-off`, or `.no-adhd` |
+| `consult` | a shell command really ran `consult` | `consult-off`, or no consult option: no agent CLI it can ask (omp, claude, codex, opencode, cursor-agent) and no OpenRouter/DeepSeek/Inception key |
+| `research` | a command really ran the research CLI | `research-off`, or `orx` not installed |
+| `graph` | a code-graph tool call (an `mcp__…codegraph…` tool) | `.no-graph` — a missing binary is `idx`'s report, not this mark's |
+| `orch` | a delegate call (`Task`/`Agent`/`spawn_agent`) or a subagent start | `orchestrate-off` |
+| `judge` | a shell command really ran `tezgah-triage` or `tezgah-docs` | `judge-off`, or no credential: no `TYPESAFE_API_KEY` and no non-empty `~/.config/typesafe/key`, and neither the fallback's `OPENROUTER_API_KEY` nor its `~/.config/openrouter/key` |
+| `gate` | never `on`: shown only as `gate✗`, right after the version, in two cases. One: the prompt hook found at least 3 gated calls in this session's transcript since its first turn: write and shell calls, every one of which the gate answers with a `began` or a `deny` row (Bash/PowerShell/Edit/Write/MultiEdit/NotebookEdit on Claude, `exec_command`/`shell`/`apply_patch` on Codex). Over the same span the ledger holds no row from the gate. A PostToolUse row is no proof: that hook keeps writing while a broken PreToolUse lets every call through. The same prompt carries the line "tezgah gate inactive on this host: ...". Two: a kill switch appeared after the session's first prompt; the prompt hook writes one `disarm` row naming it (`disarmed`, baseline `<cache>/switches/<session>.json`). Mark file `<cache>/gate-inactive/<session>` (`gate_inactive`, audit Phase 1.3) | a row from the gate appears and no switch armed mid-session is still armed |
+| `drift` | never `on`: shown as `drift✗` when a session start found tezgah's own hook entries changed since install (`hooks/tezgah_attest.py::run`). One mark per session and host, `<cache>/harness-drift/<session hash>.<host>`; the session's `attest` row names what drifted | the next clean start of that host in that session |
+| `crash` | never `on`: shown as `crash✗` when a hook of this session could not import its core and ran without tezgah (`hooks/tezgah_guard.py::import_failed`, mark `~/.cache/tezgah/import-crash/<session hash>`). When `tezgah_context` itself is the module that failed, `statusline.py` prints `tezgah ✗ core import failed` instead of the line | never by itself: the mark stays for the session |
+
+Read `on` for `consult`/`research`/`judge` as "installed and usable", not "you
+must use it": a missing key or binary reads the same red as a kill switch
+(`consult_options()`, `orx_bin()`, `have_judge_key()`: `hooks/tezgah_paths.py::consult_options`,
+`hooks/tezgah_paths.py::orx_bin`, `hooks/tezgah_paths.py::have_judge_key`). `judge` is the seam
+behind `bin/tezgah-triage`, `bin/tezgah-docs` and the skill picker
+([judge](judge.md)), and its credential is the seam's own two channels, never
+omp's login store. `graph` and `orch` are the two switch-only marks: nothing at
+arming time asks whether their toolchain is on the machine, because neither rule
+leaves the text when it is missing - the graph-first rule ships whether or not
+codegraph is installed, and the graph's own absence is `idx`'s report
+(`–` from the same check, `_index_mark()`, `hooks/tezgah_context.py::_index_mark`) beside the
+note that names the missing MCP (`hooks/tezgah_context.py::context_for`). Their `○` says
+the rule is armed, never that a graph or a delegate surface answers.
+`exec` has no used channel — its `meas` is `None` — so it can never be `ready`
+(`hooks/tezgah_context.py::health_segments`). The per-repo `idx`: ✓ indexed, ↻ indexed but HEAD moved since the
+stamp, ✗ not indexed yet, ? the index cannot be compared to HEAD (no stamp, or
+an unreadable HEAD), – n/a (outside a root, codegraph absent, or
+`.no-graph`); its probe forks git twice, so it is memoised per `(cwd, base)`
+(`index_mark()`, `hooks/tezgah_context.py::index_mark`) and `idx_override` lets a redraw send the glyph back
+instead of forking (`hooks/tezgah_context.py::health_segments`). `plans` is `plans N` plus `(M blk)` when M open
+plan files carry `status: blocked` in their first 400 bytes — `ready` with a
+blocked plan, else `info` (`plan_mark()`, `hooks/tezgah_context.py::plan_mark`).
+
+### The two skill-read marks, and `--observable=`
+
+`pony` and `adhd` mean "the full skill text reached the session" — the only signal
+separating a real rule read from the always-on summary. They are earned by a read
+of `skills/<name>/SKILL.md`, matched on the path suffix, so any other read costs
+nothing (`SKILL_MARKS`, `skill_read_kind()`, `hooks/tezgah_context.py::SKILL_MARKS`, `hooks/tezgah_context.py::skill_read_kind`).
+
+A read is not observable at an acceptable price everywhere: it needs Claude's
+transcript, opencode's in-process classification, or omp's extension filter before
+python is asked (`hooks/tezgah_context.py::skill_read_kind`). A surface that cannot see one must not say "the skill
+was never opened", so it declares what it can see and those marks render `info`
+(dim, no glyph) instead of `ready` (`observable`, `hooks/tezgah_context.py::health_segments`; the set constant
+`TOOL_USE_MEASURES`, `hooks/tezgah_context.py::TOOL_USE_MEASURES`). The `--observable=` flag carries it on the CLI
+(`bin/tezgah-status::main`). Two callers pass the tool-use set: Cursor's
+status line (statusline.py:117-121) and Codex, which renders the line plain into
+`systemMessage` (`hosts/codex/hook.py::main`); dsh passes the literal flag
+string (hosts/dsh/statusline/lib/index.js:16-19,84,96), which names the five marks its
+own hook can record - `judge` included, since dsh wires the same PostToolUse hook
+every other host does. The set is what a host can write, not what it happens to
+have written: a mark the literal omits reads `info` there rather than a claim.
+
+## The used-kinds channel
+
+A used measure is one append to the session store,
+`<cache_dir>/sessions/<slug(session_id)>.jsonl`, one `{"kind": …}` per line
+(`record()`, `hooks/tezgah_context.py::record`; `used()` reads it back, `hooks/tezgah_context.py::used`).
+`cache_dir()` is `~/.cache/tezgah` with a temp fallback for sandboxed hosts
+(`hooks/tezgah_paths.py::CACHE`, `hooks/tezgah_paths.py::fallback_cache`, `hooks/tezgah_paths.py::cache_dir`); a missing kind is not an event, so only
+the five kinds are ever written (`hooks/tezgah_context.py::record`).
+
+Writers: the shared PostToolUse hook `hooks/projects-posttooluse.py` — `graph` from
+an MCP tool name, else the shell tokenizer's answer, which counts a tool only when
+the command really ran it (34-38,84) and is the one writer that can earn `judge`
+(a run of `bin/tezgah-triage` or `bin/tezgah-docs`, `shell_kind`, `hooks/tezgah_context.py::shell_kind`)
+— plus `hooks/projects-auto-init.py::main`
+(`orch` on subagent start), `hosts/codex/hook.py::main`,
+`hosts/cursor/hook.py::dispatch`, hosts/opencode/plugins/tezgah.js:2123-2130,
+hosts/opencode/plugins/tezgah.js:2669, `hosts/omp/hook.py::handle`. Both Claude (hooks/hooks.json) and dsh
+(hosts/dsh/hooks.json) wire PostToolUse to that one shared hook, which is how dsh
+gets any used mark at all: with no local transcript, the store is the only channel
+its line has (hooks/projects-posttooluse.py:33-37).
+
+Claude's line never reads the store: it parses `tool_use` blocks out of
+`payload["transcript_path"]` plus the subagent transcripts under it, which is how
+it sees the skill reads the store cannot carry (`statusline.py::claude_used`).
+Every other surface reads the store.
+
+## Surfaces
+
+- **Claude / Cursor** — `statusline.py` reads the host's session JSON on stdin,
+  picks the host from `--cursor` or `TEZGAH_STATUS_HOST`, renders
+  `render_line(segs, color=color_default())`, and joins Orca's own status line to
+  the tezgah segment with `  |  `; `TEZGAH_STATUS_LEGEND=1` appends the legend
+  (31-34,40-48,116-122). ANSI is dropped under `NO_COLOR` or
+  `TEZGAH_STATUS_COLOR=0` (`color_default()`, `hooks/tezgah_context.py::color_default`).
+- **omp** — hosts/omp/tezgah-hook.ts.in: `draw()` prefers
+  `ctx.ui.setWidget("tezgah", [line], {placement: "belowEditor"})`, which renders
+  the colored string as-is; `setStatus` is the fallback for a build without
+  `setWidget`, and it is plain because omp strips ANSI (12-29). `status_line()`
+  builds the line and carries `idx_override`, so a per-tool redraw forks no git
+  (`hosts/omp/hook.py::status_line`); it redraws on session start, session switch, turn end
+  and each watched tool result (hosts/omp/tezgah-hook.ts.in:541-569,607-612,653-678).
+  **Motion:** while the agent runs (`agent_start` until an `agent_end` whose
+  `isTerminal` is not `false`) the widget leads with a braille spinner, the tool
+  in flight (`tool_execution_start`/`_end`, "thinking" between tools) and the
+  run's seconds, then the marks. The frames (`FRAME_MS` = 100 ms) run on omp's
+  isolated `ctx.setInterval`, repaint the line the extension already holds and
+  never ask the hook; they stop at the terminal end, a session switch and
+  `session_shutdown`. No widget (the `setStatus` fallback) means no motion, and
+  `TEZGAH_STATUS_ANIMATE=0` keeps the colors and drops the motion.
+  **Width:** the hook answers every width tier (`render_tiers`: the full line;
+  no version; icons standing for names; the logo alone at the head, groups
+  split by a space) with the cells each takes, and the widget is a component
+  whose `render(width)` draws the widest tier that fits beside the busy prefix -
+  which shrinks to the spinner alone when it would leave the marks under 24
+  cells - and cuts the narrowest with `…` when nothing fits. A narrow terminal
+  gets a shorter line, never a second row.
+- **opencode** — hosts/opencode/tui/tezgah-tui.tsx: a local TUI plugin
+  (`tui.json`'s `plugin` array, not the server plugin) registering an `app_bottom`
+  slot, shelling out to `tezgah-status <dir> --json <sessionID>`, coloring each
+  segment from the active theme and rebuilding the separator from `seg.group`
+  (56-88,hosts/opencode/tui/tezgah-tui.tsx:108-111). Its `tezgah: status legend` command opens a dialog running
+  `--legend` (141-147).
+- **dsh** — hosts/dsh/statusline/lib/index.js serves `GET /api/tezgah.status`
+  behind the Web UI's own authenticated fetch fence, so the browser fetches it
+  same-origin with no extra token handling (14,34-38); it always passes
+  `--observable=consult,research,graph,orch,judge` (18,47-48) and returns `{segments,
+  legend}` for `?format=json`, plain text otherwise (49-56,63). Its client half
+  (hosts/dsh/statusline/lib/client.js) renders the marks in the session header in
+  fixed light/dark colors, polls every 10 s while the tab is visible, and shows the
+  legend on hover, pins it on click (16-19,35,47-52,63-64).
+- **Codex** — hosts/codex/hook.py puts the plain line in `systemMessage`
+  (182-184,195-198).
+
+## Seeing and debugging the line
+
+`bin/tezgah-status` is the CLI every surface above shells out to, and the way to
+see a line by hand:
+
+```sh
+tezgah-status /path/to/repo <session-id>     # the line for one repo and session
+tezgah-status /path/to/repo <id> --json      # segments: key/state/glyph/text/group
+tezgah-status /path/to/repo <id> --counters  # the evidence ledger's counters
+tezgah-status --legend                       # what each mark means
+tezgah-status --rule-yield                   # live gate rules that stopped firing
+tezgah-status --enforcers                    # what enforces each always-on rule
+```
+
+The session id is the second positional argument or `TEZGAH_SESSION`; without it
+the used marks cannot light up (`bin/tezgah-status::main`). `--color`/`--no-color` force ANSI or plain,
+`--observable=` narrows the measures as above, and an unknown flag exits 2 (`bin/tezgah-status::main`).
+
+`--counters` is not the marks: it prints `tezgah_integrity.counters(session)` —
+`steps`, `tool_error_rate`, `claims`, `false_completion`, `shape_blocked`,
+`denies`, `nudges`, `fanout`, `consult`, `codegen`, `codegen_failed`, `judge`,
+`replies`, `shape` and the `kinds` seen (`bin/tezgah-status::main`); with `--json`
+as JSON. `replies` counts the `shape` rows, one per reply the Stop rule judged,
+and `shape` those that carried a report-only flag - `table-open`,
+`preamble-open`, `recap-close` (`shape_flags`, `hooks/tezgah_integrity.py::shape_flags`)
+- so a flag's rate has its denominator; the row also carries the reply's
+`longest_list` and `tr_share`, the two numbers the list-cap and language blocks
+read. `shape_blocked` counts the claim rows refused for their shape rather than
+their evidence, which `false_completion` leaves out. `judge` is the seam's spend,
+counted on the row's **kind** and never on a `detail` substring like `consult` and
+`codegen` are, because a judgement's detail carries the caller and the model and a
+substring would also count a commit message that says "judge"
+(`hooks/tezgah_integrity.py::_counts`). It is in neither `STEP_KINDS` nor the check
+set: a judgement is a cost, and a model answer must never license a "done" claim
+(`STEP_KINDS`, `hooks/tezgah_integrity.py::STEP_KINDS`). `tezgah-setup --status <path>` prints the plain line for a
+repo (`bin/tezgah-setup::main`). A wrong or missing line usually ends in one of
+three places: no session id (used marks stay `○`), a surface that passed
+`--observable=` and so renders dim where you expected a state, or a store a
+sandboxed host could not write (`hooks/tezgah_paths.py::cache_dir`).
+
+`--rule-yield` is a corpus report, not a mark: every live gate rule - the labels
+`hooks/tezgah_gate.py` passes to `_deny`, read from the code with `ast`, so a
+removed rule drops out on its own - with its fires over the real ledgers written
+since it shipped, the exposure window (`rule_yield`, hooks/tezgah_shapes.py).
+The ship date is the commit time from which the rule has been in the gate without
+a gap, read from git history, because no ledger row names the harness revision
+that wrote it and a rule that never fired has no row to date it by. A rule older
+than the checkout's first commit dates from that commit, which only shrinks its
+window - the direction that keeps a rule; without git every date is unknown and
+no rule is marked. Fixture ledgers are left out by
+`fixture_ledger`, the same exclusion `--counters --all` applies. A rule with 0
+fires over at least `MIN_EXPOSURE` (300) real ledgers is marked
+`retire-candidate`, one with 0 fires over fewer `low-exposure`, so a rule a day
+old is not read as dead. It always exits 0 and prints the corpus it read;
+`--json` prints the whole fold.
+
+`--enforcers` reports on the rule layer, not on a session. It prints one row
+per always-on CORE rule. The row names the gate rules and Stop classes that
+refuse on the rule, each with its guards. It also names the shape flags that
+only record it. The row's status
+is `enforced`, `partial`, `records` or `prose-only`, with the record that says
+why ([contract.md](contract.md#which-mechanism-enforces-each-always-on-rule)).
+It always exits 0, and `--json` prints the rows, the enforcers tied to no rule
+and the failures.
+
+## A mark must not claim what it cannot see
+
+A mark asserting a state the surface cannot observe is a bug in this layer, so the
+honest answer is dim, never a guess. `idx` has the same rule inside its own glyph
+set: `?` means the comparison could not be made - no stamp file, or a HEAD that
+could not be read - so the mark refuses to say either fresh or stale, and
+`index_notice()` says on the turn that the graph's age is unknown. On a host that
+sandboxes hook writes (dsh) the stamp is never written, and before that state
+existed the mark read green there for good. That is why `observable` exists (`hooks/tezgah_context.py::health_segments`),
+why the skill-read check is documented as unavailable on Codex, Cursor and dsh
+(`hooks/tezgah_context.py::skill_read_kind`), why omp ignores any `idx` value that is not one of
+its five glyphs (`hosts/omp/hook.py::status_line`) - a value outside that set re-probes
+instead of being reused, one fork and never a wrong mark - and
+why `off` is decided before the visibility one - a
+kill switch is observable everywhere (`hooks/tezgah_context.py::health_segments`). Cursor's pinned plain
+line is the regression for it (`tests/test_statusline.py::CURSOR_SEGMENT`, `tests/test_statusline.py::test_cursor_mode_segment`). `judge` is
+the live case of both halves: its used-kind is written by the hosts' own hooks, so
+where that store cannot be written the mark states nothing instead of claiming
+"armed, not used yet" forever, and where the kill switch is armed `off` wins over
+that carve-out (`tests/test_statusline.py::JudgeMark`).
+
+## Source of truth
+
+- `hooks/tezgah_context.py`, `hooks/tezgah_paths.py`, `bin/tezgah-status`
+- `statusline.py`, `hooks/projects-posttooluse.py`, `hooks/projects-auto-init.py`
+- `hooks/hooks.json`, `hosts/dsh/hooks.json`
+- `hosts/omp/tezgah-hook.ts.in`, `hosts/omp/hook.py`, `hosts/codex/hook.py`,
+  `hosts/cursor/hook.py`
+- `hosts/opencode/tui/tezgah-tui.tsx`, `hosts/opencode/plugins/tezgah.js`
+- `hosts/dsh/statusline/lib/index.js`, `hosts/dsh/statusline/lib/client.js`
+- `tests/test_statusline.py`