From dbade304bbda486df7169b89e9e017afa2ea1c37 Mon Sep 17 00:00:00 2001 From: yai_mac_big Date: Mon, 18 May 2026 14:54:57 +0700 Subject: [PATCH] docs: rewrite adoption entrypoint bilingual --- README.md | 282 +++++++++++++++++++++++++----- WHY_TRINITY.md | 121 +++++++++++++ WHY_TRINITY_TH.md | 120 +++++++++++++ docs/VERSION_LINEAGE.md | 13 +- docs/VERSION_LINEAGE_TH.md | 51 ++++++ docs/specs/00_BLUEPRINT.md | 96 ++++++++-- docs/specs/01_TOOL_CONTRACT.md | 45 ++++- docs/specs/INDEX.md | 8 +- docs/specs/en/00_BLUEPRINT.md | 94 ++++++++-- docs/specs/en/01_TOOL_CONTRACT.md | 36 +++- docs/specs/en/INDEX.md | 6 +- 11 files changed, 772 insertions(+), 100 deletions(-) create mode 100644 WHY_TRINITY.md create mode 100644 WHY_TRINITY_TH.md create mode 100644 docs/VERSION_LINEAGE_TH.md diff --git a/README.md b/README.md index 5fe4c99..1ef9027 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,234 @@ -# Trinity v2 +# Trinity Protocol -> CLI-native AI microkernel — Coordinator + Judge for vendor AI harnesses. +Language: English | [ไทย](#ภาษาไทย) -**One-liner:** ai-docs is the knowledge brain, vendor AI is the reasoning engine, CLI tools are organs, verifier is the judge, artifacts are truth. +AI agents can claim work is done. Trinity makes them prove it. + +Trinity is a CLI-first control layer for AI coding agents. It coordinates +vendor AI harnesses, verifies their work, and records decisions as auditable +artifacts. + +Core rule: + +```text +No artifact = no trust. +No verification = no completion. +No authority = no transition. +``` --- -## Operator Guides +## Why Trinity? + +AI coding agents are powerful, but their claims are not reliable evidence. + +They may say: -- **Operator Guide (English):** [`docs/operator-guide-en/00_README.md`](docs/operator-guide-en/00_README.md) -- **คู่มือใช้งานภาษาไทย:** [`docs/operator-guide-th/00_README.md`](docs/operator-guide-th/00_README.md) +- tests pass, but no test artifact exists +- a bug is fixed, but no reproduction was verified +- a deploy is safe, but no rollback path was recorded +- a file was changed correctly, but no diff was inspected -English | Thai: -[`English`](docs/operator-guide-en/00_README.md) | -[`ไทย`](docs/operator-guide-th/00_README.md) +Trinity turns AI-assisted work into an evidence-driven workflow: + +```text +Human intent + | + v +AI proposes / executes within scope + | + v +Trinity captures artifacts + | + v +Verifier checks evidence + | + v +Policy / Human decides promotion +``` + +Read the one-page explanation: + +- [`WHY_TRINITY.md`](WHY_TRINITY.md) +- [`WHY_TRINITY_TH.md`](WHY_TRINITY_TH.md) --- -## Workflow +## 60-Second Example + +Before Trinity: + +```text +User: Fix the login bug. +Agent: Done. Tests pass. +``` + +Problem: there is no trustworthy evidence. + +After Trinity: + +```text +User: Fix the login bug. +Trinity requires: +1. a scoped plan +2. bounded execution +3. diff and test artifacts +4. verifier verdict +5. explicit promotion authority +``` + +If the agent cannot produce the artifact, the work cannot be promoted. + +--- + +## Current Status + +- Architecture generation: Trinity v2 +- Runtime release: v0.1.0 +- Public Tool Contract: v1.0 freeze candidate; working spec is `v1.1.0-draft` +- Kernel CLI: verified v0.1.0 runtime included in this repository +- Release evidence: [`docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md`](docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md) + +Behavioral proof, not just test count: + +- State machine safety +- Gate enforcement +- Audit chain integrity +- Tool contract compliance +- Verifier verdict behavior +- Ritual command flow +- Human approval requirements for risky transitions + +Latest verified test evidence: + +```text +Source checkout: 1862 passed, 6 skipped +Clean export without optional sibling tools: 1860 passed, 8 skipped +``` + +--- + +## Architecture ```text Human Owner | v -sss -> vvv -> nnn -> gogogo -> ddd -> rrr -> close - | | | | | | | - | | | | | | +-- final manifest / archive - | | | | | +---------- retro + memory-cli index - | | | | +----------------- Release Gate / human decision - | | | +------------------------- bounded execution + verifier - | | +---------------------------------- plan + acceptance artifacts - | +----------------------------------------- scope / risk / acceptance - +------------------------------------------------ session capsule - -Artifact Truth +Trinity Control Layer + | + +-- Intent / Scope / Constraints + +-- Session capsule + state machine + +-- Bounded AI execution + +-- Artifact capture + +-- Verifier + policy gates + +-- Audit chain + | + v +Promotion only with evidence +``` + +Worker layer: + +```text +Claude Code / Codex / Cursor / Gemini | - +-- THINK/plan + DO evidence + CAPTURE logs - +-- Verifier verdicts - +-- Audit Chain (.ai/audit/events.ndjson) + v +Vendor AI proposes and executes ``` +Trinity does not replace the agent. Trinity governs the work. + --- -## Layout +## Quickstart +```bash +bash .ai/cli/ai status +bash .ai/cli/ai sss "Test Trinity with a small documentation task" +bash .ai/cli/ai vvv +bash .ai/cli/ai nnn +bash .ai/cli/ai gogogo ``` -trinity_v2/ -├── CLAUDE.md ← Claude Code entrypoint -├── AGENTS.md ← Cursor / Codex entrypoint -├── .ai/ ← Trinity runtime -│ ├── cli/ ← Python CLI (kernel commands) -│ ├── sessions/ ← session capsules -│ └── audit/ ← events.ndjson (hash-chain log) -└── docs/ - └── specs/ ← canonical implementation specs and contracts + +Run the CLI test suite: + +```bash +python3 -m pytest .ai/cli/tests -q ``` -## Start here +--- + +## Ritual Commands + +Rituals are the operator protocol. They are not the first thing to understand, +but they are how Trinity enforces the workflow once work begins. + +```text +sss -> vvv -> nnn -> gogogo -> ddd -> rrr -> close +``` +| Ritual | Purpose | +|---|---| +| `sss` | Start a session capsule and initial state | +| `vvv` | Define goal, scope, constraints, acceptance, risk | +| `nnn` | Normalize into plan, steps, and artifacts | +| `gogogo` | Explicit execution gate | +| `ddd` | Inspect diff, damage, and scope creep | +| `rrr` | Retro and memory handoff through `memory-cli index` | +| `close` | Close the session with explicit final state | + +Reference: + +- [`docs/RITUALS.md`](docs/RITUALS.md) +- [`docs/RITUALS_TH.md`](docs/RITUALS_TH.md) + +--- + +## Documentation Map + +Start here: + +- **Why Trinity:** [`English`](WHY_TRINITY.md) | [`ไทย`](WHY_TRINITY_TH.md) - **Origin story:** [`English`](docs/ORIGIN.md) | [`ไทย`](docs/ORIGIN_TH.md) - **Ritual reference:** [`English`](docs/RITUALS.md) | [`ไทย`](docs/RITUALS_TH.md) - **Getting started:** [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) - **Architecture:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - **Storage taxonomy:** [`docs/STORAGE_TAXONOMY.md`](docs/STORAGE_TAXONOMY.md) -- **Version lineage:** [`docs/VERSION_LINEAGE.md`](docs/VERSION_LINEAGE.md) -- **Operator Guide (English):** [`docs/operator-guide-en/00_README.md`](docs/operator-guide-en/00_README.md) -- **Operator Guide (Thai):** [`docs/operator-guide-th/00_README.md`](docs/operator-guide-th/00_README.md) -- **Master overview:** [`docs/specs/INDEX.md`](docs/specs/INDEX.md) -- **Vision/blueprint:** [`docs/specs/00_BLUEPRINT.md`](docs/specs/00_BLUEPRINT.md) -- **Tool contract:** [`docs/specs/01_TOOL_CONTRACT.md`](docs/specs/01_TOOL_CONTRACT.md) -- **Bootstrap a project:** [`docs/specs/00b_BOOTSTRAP_PACK.md`](docs/specs/00b_BOOTSTRAP_PACK.md) +- **Version lineage:** [`English`](docs/VERSION_LINEAGE.md) | [`ไทย`](docs/VERSION_LINEAGE_TH.md) - **GitHub-safe export:** [`docs/GITHUB_EXPORT.md`](docs/GITHUB_EXPORT.md) -## Status +Operator guides: -- Trinity v2 runtime line: v0.1.0 -- Kernel CLI: verified v0.1.0 runtime included in this repository -- Full CLI test suite: PASS (source checkout: 1862 passed, 6 skipped; clean export without optional sibling tools: 1860 passed, 8 skipped) -- Release evidence: [`docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md`](docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md) +- [`docs/operator-guide-en/00_README.md`](docs/operator-guide-en/00_README.md) +- [`docs/operator-guide-th/00_README.md`](docs/operator-guide-th/00_README.md) + +Specs: + +- [`docs/specs/INDEX.md`](docs/specs/INDEX.md) +- [`docs/specs/00_BLUEPRINT.md`](docs/specs/00_BLUEPRINT.md) +- [`docs/specs/01_TOOL_CONTRACT.md`](docs/specs/01_TOOL_CONTRACT.md) + +--- + +## Layout + +```text +trinity_v2/ +├── AGENTS.md # Generic agent entrypoint +├── CLAUDE.md # Claude Code entrypoint +├── GEMINI.md # Gemini CLI entrypoint +├── WARP.md # Warp entrypoint +├── .ai/ # Trinity runtime +│ ├── cli/ # Python CLI kernel commands +│ ├── sessions/ # Session capsules +│ └── audit/ # Hash-chain audit log +└── docs/ + ├── specs/ # Canonical implementation specs and contracts + ├── operator-guide-en/ + └── operator-guide-th/ +``` + +--- ## Version Lineage @@ -86,10 +237,45 @@ materials. From `v0.1.0` onward, the root tree is the canonical Trinity v2 executable governance kernel. Legacy materials remain available through Git history. +Version story: + +```text +Trinity Protocol v2 = architecture / constitution generation +Runtime v0.1.0 = first public executable runtime line +Tool Contract = v1.0 freeze candidate, v1.1 draft working spec +``` + See [`docs/VERSION_LINEAGE.md`](docs/VERSION_LINEAGE.md). -## Memory CLI note +--- + +## Memory CLI Note For the Trinity v0.1.0 ritual flow, `rrr` delegates to `memory-cli index`. `memory-cli learn` appears in legacy/spec materials as a historical or non-ritual memory surface and must not be used by `rrr`. + +--- + +## ภาษาไทย + +AI agent สามารถพูดได้ว่างานเสร็จแล้ว แต่ Trinity บังคับให้ต้องมีหลักฐาน + +Trinity คือ control layer แบบ CLI-first สำหรับงานที่ใช้ AI coding agent +มันไม่ได้แทน Claude Code, Codex, Cursor หรือ Gemini แต่ทำหน้าที่คุม scope, +เก็บ artifact, ตรวจ verifier, และบันทึก decision ให้ audit ย้อนหลังได้ + +หลักการหลัก: + +```text +ไม่มี artifact = ยังเชื่อไม่ได้ +ไม่มี verification = ยังถือว่างานไม่เสร็จ +ไม่มี authority = ห้ามข้าม state +``` + +อ่านต่อ: + +- [`WHY_TRINITY_TH.md`](WHY_TRINITY_TH.md) — ทำไมต้องมี Trinity +- [`docs/ORIGIN_TH.md`](docs/ORIGIN_TH.md) — ที่มาของ Trinity +- [`docs/RITUALS_TH.md`](docs/RITUALS_TH.md) — ritual reference +- [`docs/operator-guide-th/00_README.md`](docs/operator-guide-th/00_README.md) — คู่มือใช้งาน diff --git a/WHY_TRINITY.md b/WHY_TRINITY.md new file mode 100644 index 0000000..d68acd0 --- /dev/null +++ b/WHY_TRINITY.md @@ -0,0 +1,121 @@ +# Why Trinity? + +Language: English | [ไทย](WHY_TRINITY_TH.md) + +AI coding agents are powerful, but their claims are not reliable evidence. + +They can say "done" without proving that the work is done. + +They may say: + +- tests pass, but no test artifact exists +- a bug is fixed, but no reproduction was verified +- a deploy is safe, but no rollback path was recorded +- a file was changed correctly, but no diff was inspected + +Trinity exists to make AI-assisted work evidence-driven. + +--- + +## Before Trinity + +```text +User: Fix the login bug. +Agent: Done. Tests pass. +``` + +The problem is not that the agent is always wrong. + +The problem is that the claim is not enough. + +There is no trustworthy proof: + +- no scoped plan +- no diff summary +- no test log +- no verifier verdict +- no audit event +- no promotion decision + +--- + +## After Trinity + +```text +User: Fix the login bug. +Trinity: +1. Requires a scoped plan artifact +2. Allows execution only within approved boundaries +3. Captures diffs, logs, test output, screenshots, or other evidence +4. Runs verifier rules against the evidence +5. Allows promotion only after the evidence passes +``` + +If there is no artifact, there is no trust. + +If verification does not pass, the work is not complete. + +If no authorized layer approves the transition, the work cannot move forward. + +--- + +## Core Principle + +```text +Trust artifacts, not claims. +``` + +An AI agent can propose. It can execute within scope. It can write artifacts. + +But it should not be the final authority that decides its own work is complete. + +Trinity uses a simple judgment order: + +```text +Deterministic verifier + -> Policy / rules + -> LLM judge only when gated + -> Human authority +``` + +--- + +## What Trinity Is + +Trinity is a CLI-first control layer for AI coding agents. + +It coordinates vendor AI harnesses, verifies their work, and records decisions +as auditable artifacts. + +It is designed for developers and technical operators who already use tools +like Claude Code, Codex, Cursor, or Gemini, but do not want to trust agent +claims without evidence. + +--- + +## What Trinity Is Not + +Trinity is not: + +- another chatbot +- another general agent framework +- an MCP-first tool registry +- a memory app +- a generic orchestrator +- a replacement for vendor AI harnesses + +Trinity is the control plane between human intent and AI execution. + +--- + +## The Short Version + +Trinity does not make AI smarter. + +Trinity makes AI work accountable. + +```text +No artifact = no trust. +No verification = no completion. +No authority = no transition. +``` diff --git a/WHY_TRINITY_TH.md b/WHY_TRINITY_TH.md new file mode 100644 index 0000000..d0a0fc2 --- /dev/null +++ b/WHY_TRINITY_TH.md @@ -0,0 +1,120 @@ +# ทำไมต้องมี Trinity? + +ภาษา: [English](WHY_TRINITY.md) | ไทย + +AI coding agent เก่งขึ้นมาก แต่คำพูดของมันยังไม่ใช่หลักฐาน + +มันสามารถบอกว่า "เสร็จแล้ว" ได้ โดยที่ยังไม่มีอะไรพิสูจน์ว่างานเสร็จจริง + +ตัวอย่างปัญหา: + +- บอกว่า test ผ่าน แต่ไม่มี test artifact +- บอกว่า bug แก้แล้ว แต่ไม่มี reproduction ที่ verify แล้ว +- บอกว่า deploy ปลอดภัย แต่ไม่มี rollback path +- บอกว่าแก้ไฟล์ถูกแล้ว แต่ยังไม่มี diff ให้ตรวจ + +Trinity ถูกสร้างมาเพื่อเปลี่ยนงานที่ใช้ AI ให้เป็น evidence-driven workflow + +--- + +## ก่อนมี Trinity + +```text +User: แก้ login bug ให้หน่อย +Agent: เสร็จแล้วครับ test ผ่านแล้ว +``` + +ปัญหาไม่ใช่ว่า agent ต้องผิดเสมอ + +ปัญหาคือคำพูดนั้นยังไม่พอ + +ยังไม่มีหลักฐานที่ตรวจได้: + +- ไม่มี scoped plan +- ไม่มี diff summary +- ไม่มี test log +- ไม่มี verifier verdict +- ไม่มี audit event +- ไม่มี promotion decision + +--- + +## หลังมี Trinity + +```text +User: แก้ login bug ให้หน่อย +Trinity: +1. บังคับให้มี plan artifact ที่ระบุ scope +2. อนุญาตให้ execute เฉพาะใน boundary ที่ผ่าน gate +3. เก็บ diff, log, test output, screenshot หรือ evidence อื่น +4. ให้ verifier ตรวจหลักฐาน +5. อนุญาตให้ promote เฉพาะเมื่อ evidence ผ่าน +``` + +ถ้าไม่มี artifact ก็ยังเชื่อไม่ได้ + +ถ้า verification ไม่ผ่าน ก็ยังถือว่างานไม่เสร็จ + +ถ้าไม่มี authority ที่ถูกต้อง ก็ห้ามข้าม state + +--- + +## หลักการหลัก + +```text +Trust artifacts, not claims. +``` + +AI agent เสนอได้ ลงมือได้ใน scope ที่กำหนดได้ และเขียน artifact ได้ + +แต่ไม่ควรเป็นผู้ตัดสินสุดท้ายว่างานของตัวเองเสร็จแล้ว + +Trinity ใช้ลำดับการตัดสินแบบนี้: + +```text +Deterministic verifier + -> Policy / rules + -> LLM judge เฉพาะเมื่อถูก gate + -> Human authority +``` + +--- + +## Trinity คืออะไร + +Trinity คือ control layer แบบ CLI-first สำหรับ AI coding agent + +มันประสาน vendor AI harness, ตรวจงานจากหลักฐาน, และบันทึก decision เป็น +auditable artifact + +มันเหมาะกับ developer หรือ technical operator ที่ใช้ Claude Code, Codex, +Cursor หรือ Gemini อยู่แล้ว แต่ไม่อยากเชื่อคำกล่าวอ้างของ agent โดยไม่มี evidence + +--- + +## Trinity ไม่ใช่อะไร + +Trinity ไม่ใช่: + +- chatbot อีกตัว +- agent framework ทั่วไป +- MCP-first tool registry +- memory app +- generic orchestrator +- ตัวแทนของ vendor AI harness + +Trinity คือ control plane ระหว่าง human intent กับ AI execution + +--- + +## สรุปสั้นที่สุด + +Trinity ไม่ได้ทำให้ AI เก่งขึ้น + +Trinity ทำให้งานของ AI ตรวจสอบและรับผิดชอบได้ + +```text +ไม่มี artifact = ยังเชื่อไม่ได้ +ไม่มี verification = ยังถือว่างานไม่เสร็จ +ไม่มี authority = ห้ามข้าม state +``` diff --git a/docs/VERSION_LINEAGE.md b/docs/VERSION_LINEAGE.md index 7d9e08a..d86f2d8 100644 --- a/docs/VERSION_LINEAGE.md +++ b/docs/VERSION_LINEAGE.md @@ -1,5 +1,16 @@ # Version Lineage +Language: English | [ไทย](VERSION_LINEAGE_TH.md) + +Trinity uses separate version lines for architecture, runtime, and tool +contracts. They should not be collapsed into one number. + +```text +Trinity Protocol v2 = architecture / constitution generation +Runtime v0.1.0 = first public executable runtime line +Tool Contract = v1.0 freeze candidate, v1.1 draft working spec +``` + ## v0.1.0 Trinity v0.1.0 is the first stable-ready public release line for the @@ -29,7 +40,7 @@ Clean export without optional sibling tools: 1860 passed, 8 skipped ## Lineage -- Source family: `TRINITY_LEGACY` kernel lessons and migration evidence. +- Source family: `TRINITY_ULTIMAT` kernel lessons and migration evidence. - Current repo: `trinity_v2`, clean public bootstrap/runtime target. - Public export: generated with `scripts/export_github.sh` and `scripts/package_github_zip.sh`. diff --git a/docs/VERSION_LINEAGE_TH.md b/docs/VERSION_LINEAGE_TH.md new file mode 100644 index 0000000..e1075a1 --- /dev/null +++ b/docs/VERSION_LINEAGE_TH.md @@ -0,0 +1,51 @@ +# Version Lineage (ไทย) + +ภาษา: [English](VERSION_LINEAGE.md) | ไทย + +Trinity แยก version line ของ architecture, runtime และ tool contract ออกจากกัน +ไม่ควรเอาทุกอย่างไปรวมเป็นเลขเดียว + +```text +Trinity Protocol v2 = architecture / constitution generation +Runtime v0.1.0 = first public executable runtime line +Tool Contract = v1.0 freeze candidate, v1.1 draft working spec +``` + +## v0.1.0 + +Trinity v0.1.0 คือ public runtime line แรกที่พร้อมใช้สำหรับ repository +`trinity_v2` + +repository นี้เคยมีวัสดุทดลองของ Trinity Protocol รุ่นก่อนหน้าอยู่ก่อนแล้ว +ตั้งแต่ `v0.1.0` เป็นต้นไป root tree นี้ถือเป็น canonical Trinity v2 +executable governance kernel ส่วน legacy materials ยังดูย้อนหลังได้จาก Git +history + +Release evidence: + +- [`docs/releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md`](releases/TRINITY_V0_1_0_RELEASE_EVIDENCE.md) + +คำสั่งที่ใช้ verify: + +```bash +python3 -m pytest .ai/cli/tests -q +``` + +ผลที่ verify แล้ว: + +```text +Source checkout: 1862 passed, 6 skipped +Clean export without optional sibling tools: 1860 passed, 8 skipped +``` + +## Lineage + +- Source family: บทเรียนจาก `TRINITY_ULTIMAT` kernel และ migration evidence +- Current repo: `trinity_v2`, clean public bootstrap/runtime target +- Public export: สร้างด้วย `scripts/export_github.sh` และ + `scripts/package_github_zip.sh` + +## Release Discipline + +Stable tag ต้องชี้ไปที่ commit ที่ผ่าน verification จริง ห้าม tag dirty +worktree และห้าม tag commit เก่าด้วย evidence จากไฟล์ใหม่ diff --git a/docs/specs/00_BLUEPRINT.md b/docs/specs/00_BLUEPRINT.md index c74eeaa..11eac8d 100644 --- a/docs/specs/00_BLUEPRINT.md +++ b/docs/specs/00_BLUEPRINT.md @@ -312,28 +312,90 @@ Schema = ABI --- -## 9. MCP Stance — LOCKED +## 9. MCP Stance — CLI-first, MCP-optional ```text -Core protocol = CLI-first ONLY -External MCP servers = ❌ ไม่ใช้ (Playwright/Morphllm/Sequential ตัด) -Vendor built-in tools = ✅ ใช้ตามปกติ (Read/Write/Edit/Bash ของ Claude Code) -HTTP/API = optional bridge (อนาคต) +Default path: +CLI tool -> Tool Contract -> Audit Chain + +Optional bridge: +MCP capability -> MCP adapter -> Tool Contract -> Audit Chain ``` -### Replacement Mapping (committed) +Trinity is CLI-first by default. + +This is not because MCP is bad. It is because Trinity optimizes for token +economy, observability, composability, vendor portability, and auditability. + +### 9.1 Token Economy + +MCP tool descriptions consume context window every session. + +As the number of MCP servers grows, the model receives more tool descriptions +before useful work begins. CLI tools invoked through the vendor harness shell +have near-zero marginal token overhead because the shell tool is already +available. + +Trinity can run 1 or 100 CLI tools without injecting 100 tool descriptions into +the model context. + +### 9.2 Observability + +Trinity's core principle is: + +```text +Trust artifacts, not claims. +``` + +CLI tools expose their boundary through stdin, stdout, stderr, exit code, +files, and NDJSON logs. Those boundaries can be captured, hashed, audited, and +replayed. + +MCP servers may hide behavior behind host-managed tool calls, schema handling, +retry behavior, internal process state, or server-side side effects. For +Trinity, opaque tool boundaries weaken the audit chain. + +### 9.3 Composability + +CLI tools follow Unix composition. They can be scripted, tested, mocked, +diffed, logged, and replayed outside any single vendor runtime. -| MCP เดิม | แทนด้วย | -|---------|---------| -| `mcp__playwright__*` (13 tools) | `browser-cli` | -| `mcp__morphllm-fast-apply__*` (8 tools) | Vendor's Read/Write/Edit/Glob | -| `mcp__sequential-thinking__*` | ai-docs workflow + Trinity loop | -| `mcp__ide__executeCode` | คงไว้ (vendor IDE bridge) | +Trinity prefers tools that can be tested with: + +```bash +./tool < input.json > output.json +``` + +### 9.4 Vendor Surface Area + +MCP introduces protocol and host compatibility concerns. Different vendors may +support different MCP behaviors, versions, permission models, and invocation +semantics. + +CLI tools remain portable across Claude Code, Codex, Cursor, Gemini CLI, shell +scripts, and CI environments. + +### 9.5 Governance Boundary + +Vendor harnesses are hosts selected by the operator. External MCP servers are +runtime dependencies that may be injected into the session outside Trinity's +default control path. + +Trinity accepts vendor harnesses as execution hosts. It does not accept opaque +tool injection as the default control surface. + +### 9.6 MCP Is Not Banned + +MCP may be supported as an optional bridge. + +If a capability is MCP-only and valuable, Trinity can wrap it through a Tool +Contract envelope: + +```text +MCP capability -> adapter -> input/output envelope -> artifacts -> audit +``` -### เหตุผล -- ใช้ Playwright MCP — แต่ browser-cli replace ได้เกือบ 100% -- CLI-first = tool-agnostic จริง (Claude/Codex/Gemini/Cursor ใช้ตัวเดียวกัน) -- MCP ผูกกับ Claude Code อย่างเดียว — ขัด vision +MCP is an adapter, not the core. --- @@ -703,5 +765,5 @@ Audit = NDJSON logs ## Changelog -- **v2.0.0 (2026-04-28)** — Major revision: 10 decisions committed, vocabulary locked, 5 critical fixes integrated (Brain redefined, Verifier rules introduced, Goal tree mandated, Graph authority enforced, Bootstrap Pack added). MCP stance hardened to "CLI-first only". +- **v2.0.0 (2026-04-28)** — Major revision: 10 decisions committed, vocabulary locked, 5 critical fixes integrated (Brain redefined, Verifier rules introduced, Goal tree mandated, Graph authority enforced, Bootstrap Pack added). MCP stance clarified as CLI-first by default, MCP-optional through Tool Contract adapters. - **v1.0.0 (2026-04-28)** — Initial draft based on user's blueprint synthesis diff --git a/docs/specs/01_TOOL_CONTRACT.md b/docs/specs/01_TOOL_CONTRACT.md index d41666a..6a8f48a 100644 --- a/docs/specs/01_TOOL_CONTRACT.md +++ b/docs/specs/01_TOOL_CONTRACT.md @@ -6,7 +6,7 @@ status: revised last-updated: 2026-04-28 applies-to: All CLI tools in Trinity OS userland reference-implementation: browser-cli -revision-notes: "v1.1 — added Action Namespace, Contract Compliance Test, MCP stance hardened" +revision-notes: "v1.1 — added Action Namespace, Contract Compliance Test, MCP stance clarified as CLI-first default with optional bridge" --- # Trinity Tool Contract v1.1 @@ -18,6 +18,34 @@ revision-notes: "v1.1 — added Action Namespace, Contract Compliance Test, MCP --- +## Public Freeze Status + +Public ecosystem messaging should treat the Tool Contract as: + +```text +Tool Contract v1.0 = freeze candidate +Current working spec = v1.1.0-draft +``` + +ก่อนประกาศ stable interface ต้อง freeze อย่างน้อย 10 เรื่องนี้: + +1. Input envelope +2. Output envelope +3. Exit code meaning +4. Verdict schema +5. Artifact declaration +6. Error taxonomy +7. Retry semantics +8. Idempotency expectation +9. Audit log requirements +10. Security boundary + +จนกว่า checklist นี้จะปิดครบ ห้ามสื่อสารว่า external tool interface เป็น +stable แล้ว ให้ใช้คำว่า **v1.0 freeze candidate** หรือ **v1.1 draft working +spec** แทน + +--- + ## 0. Status & Compliance Levels | Level | Description | @@ -52,10 +80,11 @@ Tool compliance assessment ทำผ่าน `trinity tool verify ` - ❌ Programming language (Node/Python/Rust/Go ทั้งหมดได้) - ❌ External library choices - ❌ Database choice (FTS5, ChromaDB, etc.) -- ❌ **MCP protocol** — Trinity is **CLI-first ONLY**. External MCP servers ≠ core path. +- ❌ **MCP protocol as default core path** — Trinity is CLI-first by default. - Vendor harness's built-in tools (Read/Write/Edit/Bash) = ใช้ตามปกติ (ไม่กระทบ) - - External MCP servers (Playwright/Morphllm/Sequential) = ❌ ไม่ใช่ core - - Replacement: ทุก capability ทำเป็น CLI tool ตาม contract นี้ + - External MCP servers = optional bridge only, not the default control path + - MCP-only capability ต้องถูก wrap ผ่าน Tool Contract envelope ก่อนเข้า audit chain + - Default replacement: capability สำคัญควรมี CLI tool ตาม contract นี้ ### 1.3 Non-goals - ไม่ใช่ AI logic specification @@ -789,8 +818,8 @@ File: `.ai/tools.yaml` (in TRINITY kernel root) version: 1 tools: - name: browser-cli - path: /browser-cli - bin: node /browser-cli/index.js + path: ///Downloads/yai_project/browser-cli + bin: node ///Downloads/yai_project/browser-cli/index.js schema_version: "2" capabilities: [browser, navigation, dom, screenshot, assertion] policy_default: normal @@ -798,8 +827,8 @@ tools: contract_version: "1.0" - name: memory-cli - path: /memory-cli - bin: node /memory-cli/index.js + path: ///Downloads/yai_project/memory-cli + bin: node ///Downloads/yai_project/memory-cli/index.js schema_version: "1" capabilities: [search, index, recall, learn] policy_default: normal diff --git a/docs/specs/INDEX.md b/docs/specs/INDEX.md index 6debbce..710ff21 100644 --- a/docs/specs/INDEX.md +++ b/docs/specs/INDEX.md @@ -121,11 +121,11 @@ Going to migrate ? → INDEX → 10 → 09 ## 3. Project Family -`/` มีโฟลเดอร์เกี่ยวข้องดังนี้: +`///Downloads/yai_project/` มีโฟลเดอร์เกี่ยวข้องดังนี้: ```text yai_project/ -├── TRINITY_LEGACY/ ← Trinity kernel (development) +├── TRINITY_ULTIMAT/ ← Trinity kernel (development) │ ├── .ai/ ← Trinity runtime: cli, sessions, audit, policies, schemas │ ├── archive/ ← Legacy AI docs, old sessions │ ├── references/ ← External AI harness references (claw-code, openclaude, etc.) @@ -171,7 +171,7 @@ yai_project/ ### Cross-relationships ```text -TRINITY_LEGACY/ ← Source of truth for kernel + specs +TRINITY_ULTIMAT/ ← Source of truth for kernel + specs ↓ used by / ← Real production project ↓ informs @@ -796,7 +796,7 @@ Phase 10 Extension Platform 🌐 Future ## 14. FAQ ### Q: ทำไมไม่ใช้ MCP เลย? -**A:** MCP ผูกกับ Claude Code อย่างเดียว — vision คือ tool-agnostic ที่ Claude/Codex/Gemini/Cursor ใช้ได้หมด ผ่าน CLI ดู [`00_BLUEPRINT.md` §9](00_BLUEPRINT.md#9-mcp-stance--locked). +**A:** Trinity ไม่ได้ ban MCP แต่ default path เป็น CLI-first เพราะต้องการ token economy, observability, composability, vendor portability และ auditability ที่ตรวจซ้ำได้ MCP ใช้ได้เป็น optional bridge เมื่อถูก wrap ผ่าน Tool Contract envelope ดู [`00_BLUEPRINT.md` §9](00_BLUEPRINT.md#9-mcp-stance--cli-first-mcp-optional). ### Q: ทำไมไม่สร้าง AI harness ใหม่ล่ะ? **A:** Anthropic ใช้ทีมหลายสิบคน + 2 ปีทำ Claude Code (98.4% harness) — เราไม่ควรทำซ้ำ ใช้ของ vendor + ทำ shim บาง ๆ ดู [`07_SHIM_SPEC.md`](07_SHIM_SPEC.md). diff --git a/docs/specs/en/00_BLUEPRINT.md b/docs/specs/en/00_BLUEPRINT.md index 93b7a7c..f0a4102 100644 --- a/docs/specs/en/00_BLUEPRINT.md +++ b/docs/specs/en/00_BLUEPRINT.md @@ -317,28 +317,90 @@ See: [`01_TOOL_CONTRACT.md`](01_TOOL_CONTRACT.md) --- -## 9. MCP Stance — LOCKED +## 9. MCP Stance — CLI-first, MCP-optional ``` -Core protocol = CLI-first ONLY -External MCP servers = ❌ NOT used (Playwright/Morphllm/Sequential removed) -Vendor built-in tools = ✅ Used normally (Read/Write/Edit/Bash from Claude Code) -HTTP/API = optional bridge (future) +Default path: +CLI tool -> Tool Contract -> Audit Chain + +Optional bridge: +MCP capability -> MCP adapter -> Tool Contract -> Audit Chain +``` + +Trinity is CLI-first by default. + +This is not because MCP is bad. It is because Trinity optimizes for token +economy, observability, composability, vendor portability, and auditability. + +### 9.1 Token Economy + +MCP tool descriptions consume context window every session. + +As the number of MCP servers grows, the model receives more tool descriptions +before useful work begins. CLI tools invoked through the vendor harness shell +have near-zero marginal token overhead because the shell tool is already +available. + +Trinity can run 1 or 100 CLI tools without injecting 100 tool descriptions into +the model context. + +### 9.2 Observability + +Trinity's core principle is: + +```text +Trust artifacts, not claims. ``` -### Replacement Mapping +CLI tools expose their boundary through stdin, stdout, stderr, exit code, +files, and NDJSON logs. Those boundaries can be captured, hashed, audited, and +replayed. + +MCP servers may hide behavior behind host-managed tool calls, schema handling, +retry behavior, internal process state, or server-side side effects. For +Trinity, opaque tool boundaries weaken the audit chain. + +### 9.3 Composability + +CLI tools follow Unix composition. They can be scripted, tested, mocked, +diffed, logged, and replayed outside any single vendor runtime. -| Old MCP | Replaced With | -|---------|---------------| -| `mcp__playwright__*` (13 tools) | `browser-cli` | -| `mcp__morphllm-fast-apply__*` (8 tools) | Vendor's Read/Write/Edit/Glob | -| `mcp__sequential-thinking__*` | ai-docs workflow + Trinity loop | -| `mcp__ide__executeCode` | Kept (vendor IDE bridge) | +Trinity prefers tools that can be tested with: + +```bash +./tool < input.json > output.json +``` + +### 9.4 Vendor Surface Area + +MCP introduces protocol and host compatibility concerns. Different vendors may +support different MCP behaviors, versions, permission models, and invocation +semantics. + +CLI tools remain portable across Claude Code, Codex, Cursor, Gemini CLI, shell +scripts, and CI environments. + +### 9.5 Governance Boundary + +Vendor harnesses are hosts selected by the operator. External MCP servers are +runtime dependencies that may be injected into the session outside Trinity's +default control path. + +Trinity accepts vendor harnesses as execution hosts. It does not accept opaque +tool injection as the default control surface. + +### 9.6 MCP Is Not Banned + +MCP may be supported as an optional bridge. + +If a capability is MCP-only and valuable, Trinity can wrap it through a Tool +Contract envelope: + +```text +MCP capability -> adapter -> input/output envelope -> artifacts -> audit +``` -### Reasoning -- used Playwright MCP — but browser-cli replaces it ~100% -- CLI-first = truly tool-agnostic (Claude/Codex/Gemini/Cursor all work) -- MCP locks to Claude Code only — contradicts vision +MCP is an adapter, not the core. --- diff --git a/docs/specs/en/01_TOOL_CONTRACT.md b/docs/specs/en/01_TOOL_CONTRACT.md index 37fbb44..8f3247b 100644 --- a/docs/specs/en/01_TOOL_CONTRACT.md +++ b/docs/specs/en/01_TOOL_CONTRACT.md @@ -16,6 +16,34 @@ note: "Translation of ../01_TOOL_CONTRACT.md (essential parts)" --- +## Public Freeze Status + +Public ecosystem messaging should treat the Tool Contract as: + +```text +Tool Contract v1.0 = freeze candidate +Current working spec = v1.1.0-draft +``` + +Before declaring a stable external tool interface, Trinity must freeze at +least these 10 surfaces: + +1. Input envelope +2. Output envelope +3. Exit code meaning +4. Verdict schema +5. Artifact declaration +6. Error taxonomy +7. Retry semantics +8. Idempotency expectation +9. Audit log requirements +10. Security boundary + +Until that checklist is complete, public docs should say **v1.0 freeze +candidate** or **v1.1 draft working spec**, not stable interface. + +--- + ## 0. Compliance Levels | Level | Description | @@ -48,7 +76,9 @@ note: "Translation of ../01_TOOL_CONTRACT.md (essential parts)" - ❌ Programming language (any works) - ❌ External libraries - ❌ Database choice -- ❌ **MCP protocol** — Trinity is **CLI-first ONLY** +- ❌ **MCP protocol as default core path** — Trinity is CLI-first by default. + MCP-only capabilities may be wrapped by an adapter, but they must enter + Trinity through the Tool Contract envelope before they reach the audit chain. --- @@ -559,8 +589,8 @@ memory-cli --cmd "helper fresh-search 'auth bug'" version: 1 tools: - name: browser-cli - path: /browser-cli - bin: node /browser-cli/index.js + path: ///Downloads/yai_project/browser-cli + bin: node ///Downloads/yai_project/browser-cli/index.js schema_version: "2" capabilities: [browser, dom, screenshot] policy_default: normal diff --git a/docs/specs/en/INDEX.md b/docs/specs/en/INDEX.md index e0e5c15..ff2c1e1 100644 --- a/docs/specs/en/INDEX.md +++ b/docs/specs/en/INDEX.md @@ -110,11 +110,11 @@ note: "Translation of ../INDEX.md — refer to Thai version for latest details" ## 3. Project Family -`/` contains: +`///Downloads/yai_project/` contains: ``` yai_project/ -├── TRINITY_LEGACY/ ← Trinity kernel (development) +├── TRINITY_ULTIMAT/ ← Trinity kernel (development) │ ├── .ai/ ← Trinity runtime: cli, sessions, audit, policies │ ├── archive/ ← Legacy AI docs │ ├── references/ ← External AI harness study @@ -493,7 +493,7 @@ kernel → mechanical ## 14. FAQ ### Q: Why don't you use MCP at all? -**A:** MCP locks to Claude Code. Trinity vision = tool-agnostic (Claude/Codex/Gemini/Cursor all work). See [`../00_BLUEPRINT.md`](../00_BLUEPRINT.md) §9. +**A:** Trinity does not ban MCP. The default path is CLI-first because Trinity optimizes for token economy, observability, composability, vendor portability, and replayable audit boundaries. MCP can be an optional bridge when wrapped through the Tool Contract envelope. See [`../00_BLUEPRINT.md`](../00_BLUEPRINT.md) §9. ### Q: Why not build a new AI harness? **A:** Anthropic uses dozens of devs × 2 years on Claude Code (98.4% harness). Don't replicate. Use vendor + thin shim.