specs/tools: the tri CLI and the MCP servers as first-class .t27 specs (layer 5)

docs/now/2026-09-09-the-tri-cli-and-mcp-servers-as-t27-specs.md

@@ -0,0 +1,13 @@
+# NOW -- The tri CLI and the MCP servers as first-class .t27 specs (2026-09-09)
+
+## The tri CLI and the MCP servers as first-class .t27 specs (Closes #3547)
+
+- `specs/tools/tri/` (52) and `specs/tools/mcp/` (10): layer five of the ladder Specs -> Skills -> Crons -> Agents -> Tools -- the tools every agent should know. One `.t27` module per variant of the clap `Commands` enum in `cli/tri/src/main.rs` (`tool_tri_<command>`: COMMAND, VARIANT, SOURCE, ENTRY, ABOUT + ABOUT_SOURCE, ACTIONS/ACTIONS_ABOUT, ARGS, AGENTS/AGENTS_NOTE, WHEN_TO_USE, WITNESS, ENABLED) and one per MCP server (`tool_mcp_<server>`: SERVER, SERVER_VERSION, TRANSPORT, LAUNCH, ENV, CONFIG, REPO, SOURCE, ABOUT, TOOLS/TOOLS_ABOUT/TOOLS_INPUTS, RESOURCES, TOOLS_NOTE, EXTERNAL, AGENTS, WITNESS). The schema is in `specs/tools/README.md`; the three older files at the top of `specs/tools/` (`registry.t27`, `schema.t27`, `tri_to_t27_converter.t27`) are ordinary corpus specs and are not tool cards.
+- Nothing is typed by hand. `cargo` was not run: the enum and its `///` docs were read from the source at commit `3cb7a4352492`, so every tri card carries `WITNESS = "source-parse"` (52/52; `help-output`, the label for a list diffed against `tri --help`, is 0/52 until someone runs it). A variant with no doc comment quotes the source it borrows from in ABOUT_SOURCE (e.g. `tri cell` quotes the `tri-mcp` tool descriptions). 124 nested actions across 52 commands. MCP: 5 servers from gHashTag/t27 (`tri-mcp` crate, `tri-ssot` manifest, `t27-traceability`, and two `.mcp.json` entries), 5 from gHashTag/trinity (`trinity`, `needle` Zig servers and three `.mcp.json` entries), 235 tools listed with their input-schema keys; 5 servers are `EXTERNAL = true` (published packages whose tool list is not in either repository) and say so in TOOLS_NOTE. `tri-mcp` is not registered in `.mcp.json` at this commit (`CONFIG = ""`); `tri-ssot`'s manifest names a module the tree does not contain -- recorded, not resolved.
+- Two CLIs are two lists. gHashTag/trinity has no `tri` binary at the pinned commit (`build.zig` defines none; `.claude/skills/tri/SKILL.md` is a skill and is already in the skills catalog), so its tools are its MCP servers only, under `REPO = "gHashTag/trinity"`; nothing from the two repositories is merged into one list.
+- Agent binding is evidence-gated in both directions. A tool names the letters that own it (`AGENTS`) only where a source line does (AGENTS_NOTE cites it: `docs/agents/AGENTS_ALPHABET.md`, `.claude/agents/*.md`); today five commands are bound -- `tri/gen` (C, T), `tri/test` (T, V), `tri/verdict` (V), `tri/experience` (E), `tri/cell` (W) -- and the matching `specs/agents/{c,e,t,v,w}.t27` gain `TOOLS`; the other 22 letters carry `TOOLS = []` with a `TOOLS_NOTE`, and 57 of 62 tools carry `AGENTS = []` with an AGENTS_NOTE naming the sources checked. The site's generator fails the build on an unknown letter, an unknown tool ID, or a binding stated on one side only.
+- The site (gHashTag/trinity, Tool Explorer at `#/tools`, Queen module TOOLS on key `0`) vendors a byte-identical copy under `apps/website/public/t27/files/specs/tools/` and generates `public/tools/spec-tools.json` through the compiler wasm at build time -- no regex over `.t27`. Measured under the vendored wasm (sha256 `4d9c0447b5ca2887...`): **62/62** typecheck ok, nothing discarded; as for skills, crons and agents, `typecheck.ok` is lenient and the generator's field schema is the gate. Skills are cross-linked when a skill spec's own COMMAND or SUMMARY_EN names a tri command: 5 today (`t27/tri` for gen, test, verdict, experience, skill).
+- Language: English-only files (LANG-EN), ASCII only. RU summaries travel through the existing contract: `specs/i18n/agents-ru.t27` `SCOPE` gains `specs/tools` (`[4]str`) and the bundle `trinity:apps/website/i18n/agents.ru.json` gains 62 entries keyed by tool ID. Coverage measured on the site: ru 62/62, 0 orphans.
+- No absolute developer home path appears in any file; where a config names one, the prefix is written as `<checkout>`, and the t27 checkout is referred to as `T27_ROOT` or `git rev-parse --show-toplevel`.
+- Not claimed: no server is launched or command executed by a spec; no `tri --help` was diffed; `gate-topology` and `untrusted-input` still fail on `master` for already-merged PRs and are not addressed here.
+- `specs/OWNERS.md` gains the row `tools/` -> **T-Queen**.

specs/OWNERS.md

@@ -21,6 +21,7 @@
 | `isa/` | **C-Compiler** | Register alphabet |
 | `skills/`, `crons/`, `i18n/` | **T-Queen** | Agent skills and scheduled jobs as `.t27` specs, plus the per-locale translation contracts (`i18n/agents-<locale>.t27`) that point at the site's text bundles; the site (gHashTag/trinity) generates its catalogs from a vendored copy |
 | `agents/` | **T-Queen** | The 27 agents of `docs/agents/AGENTS_ALPHABET.md` as `.t27` specs (`agents/<letter>.t27`, `KIND = "agent"`): letter, domain, archetype, register, invariants, the documents that bind it (`SOUL.md`, `AGENTS.md`, the alphabet) and the skills a source evidently binds; the site joins experience by LETTER |
+| `tools/` | **T-Queen** | The `tri` CLI commands and the MCP servers as `.t27` specs (`tools/tri/<command>.t27`, `tools/mcp/<server>.t27`, `KIND = "tool"`): what a command or server is for, its actions or tools, its source and witness (`source-parse` / `help-output`), and the agent letters a source evidently binds; the three older files at the top of `tools/` are ordinary corpus specs |
 
 Each subtree with substantial churn should keep a local **`OWNERS.md`** (see below).
 

specs/agents/README.md

@@ -62,8 +62,8 @@ written by hand.
 | `CLARA_ROLE`      | `str`     | the CLARA role; `""` when the table says `—`                                              |
 | `SKILLS`          | `[N]str`  | skill IDs (`specs/skills`) the agent holds — ONLY when a source binds them (see below)     |
 | `SKILLS_NOTE`     | `str`     | where the binding comes from, or why `SKILLS` is empty; required when `SKILLS` is `[]`    |
-| `TOOLS`           | `[N]str`  | *optional, layer 5:* tool IDs (`specs/tools`) the agent owns, evidence-bound like SKILLS   |
-| `TOOLS_NOTE`      | `str`     | *optional:* source of the tool binding; required when `TOOLS` is present and `[]`          |
+| `TOOLS`           | `[N]str`  | tool IDs from `specs/tools` (`tri/<command>`, `mcp/<server>`) a source line binds to the letter |
+| `TOOLS_NOTE`      | `str`     | the source line, or why `TOOLS` is empty; required when `TOOLS` is `[]`                    |
 | `EXPERIENCE_LOG`  | `str`     | the experience directory the agent's episodes are read from, or `""`                      |
 | `ENABLED`         | `bool`    | `false` only for the reserved seat (Ti)                                                   |
 

specs/agents/a.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "TA1: AR Architecture Design - designs AR module ar
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/b.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/c.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "TA1: AR Language Implementation - implements AR la
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [1]str = ["tri/gen"];
+pub const TOOLS_NOTE : str = ".claude/agents/agent-c-compiler.md:40 names tri gen (trigger On tri gen command, line 7). Line 41 names tri seal, which is not a tri command at this commit (tri cell seal is not bound here).";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/d.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/e.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "TA2: AR Explanation & XAI - generates human-readab
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent. .claude/agents/agent-e-experience.md mentions phi-loop only as the label of the feedback field (1 = phi-loop, 0 = agent cycle); the alphabet key files point at the experience log and AR specs, not at a skill directory.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [1]str = ["tri/experience"];
+pub const TOOLS_NOTE : str = ".claude/agents/agent-e-experience.md:64 names tri experience save; lines 65-66 name tri experience query and tri notebook, which the CLI does not have at this commit. The tri-mcp server mirrors the command as tool tri_experience_save.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/f.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: the alphabet key files are conformance JSON vectors (t27/conformance/*.json) and no source names tri vectors for F.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/g.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/h.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/i.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/j.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/k.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/l.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/m.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;

specs/agents/n.t27

@@ -37,6 +37,10 @@ pub const CLARA_ROLE : str = "";
 ; cites that source or says why the list is empty.
 pub const SKILLS : [0]str = [];
 pub const SKILLS_NOTE : str = "No source binds a skill to this agent: the alphabet key files point at specs and docs, not at a skill directory, no .claude/agents file names one, and specs/OWNERS.md has no row for it.";
+; Tool IDs (specs/tools) the agent holds. Bound only where a source line names the command
+; for this letter; TOOLS_NOTE cites that line or says why the list is empty.
+pub const TOOLS : [0]str = [];
+pub const TOOLS_NOTE : str = "No source binds a tri command or MCP server to this agent: docs/agents/AGENTS_ALPHABET.md (row, key files, phase cycle), specs/OWNERS.md and .claude/agents/*.md do not name one.";
 ; Where the agent logs episodes (AGENTS_ALPHABET.md: "Logs to .trinity/experience/").
 pub const EXPERIENCE_LOG : str = ".trinity/experience/";
 pub const ENABLED : bool = true;