agent-orchestration-skill 0.0.0-stage → 1.0.0

package/CATALOG.md

@@ -0,0 +1,161 @@
+# CATALOG.md — Fast Rules & CLI Cheat Sheet (1-Page Index)
+
+> **Read this file first.** It gives any agent (Claude Code, Codex CLI, Antigravity `agy`) the complete operational rules, live CLI commands, anti-hallucination evidence contract, and reference index in ~150 lines so you do not have to read all `references/*.md` files.
+
+---
+
+## 1. Twelve Golden Rules (How Agents Collaborate)
+
+1. **Delegate only when it pays:** Multi-agent runs cost ~5x–15x chat tokens; external CLI calls add ~12.5k (`codex`) to ~19.5k (`agy`) fixed overhead. Do tiny tasks (`<3` tool calls) yourself or via native subagents.
+2. **Hardware-Aware Parallel Orchestration & Specialized Skill Delegation (`batch` + `--skill`):** Any complex task is decomposed into independent sub-agents running **in parallel** with clean KV-cache context (`Zero-Prior Briefs`), shared upstream artifacts (`--context-file`), attached domain-specific skills (`--skill <skill_name>`), and—whenever files are modified—strictly disjoint `--may-write` scopes (or isolated `--worktree` / `Workspace: "branch"`). **Do not reinvent domain workflows inside orchestration:** attach installed specialized skills (`route.py --list-skills`) so workers follow domain-grade tools and instructions. **Always respect machine hardware (`ao_common.probe_hardware()`):** parallel `wip` is automatically throttled by available CPU cores, free RAM (`~1.5 GB` per worker + `2.0 GB` OS reserve), GPU VRAM, and free disk space.
+3. **Three Brief Modes (match ceremony to uncertainty):**
+   - `tight` (4 lines: Intent/Done, Context, Scope, Output) → lookups, mechanical edits, small tests.
+   - `guided` (Role lens, Intent, DoD, Context, Latitude, Finish line, Scope) → features, code review, docs.
+   - `exploratory` (Core problem, Questions/Hypotheses, full read-only freedom) → hard debugging, unfamiliar architecture, research.
+4. **Roles are lenses (a floor, never blinders):** A worker examines its role's core angles AND follows evidence trails wherever they lead, flagging cross-boundary bugs in `open_questions` or `handoff_notes`.
+5. **Premise Challenge Right (`assumptions_challenged`):** If code or data disproves an assumption in the manager's brief, the worker MUST challenge it in `assumptions_challenged` with proof (`file:line` or command output).
+6. **Anti-Hallucination Evidence Law (No Proof = No Claim):**
+   - Every conclusion in `summary`, every critique finding, and every item in `assumptions_challenged` **MUST** cite verifiable ground truth (`file:line-line`, `command -> exit/output`, or measured numbers in `evidence[]`).
+   - Unbacked skepticism is just a worry (`risks[]`), never a valid objection or blocker.
+   - `agent_run.py` automatically audits envelopes and flags `evidence_warnings` in `meta.json` when claims lack concrete anchors.
+7. **Shared Blackboard (`--context-file`) over Lossy Manager Relay:** Never summarize a 10-page upstream artifact into 3 sentences for the next agent. Pass `--context-file <path>` so downstream agents read upstream findings/diffs directly.
+8. **Dynamic Model Discovery (never rely on stale hardcoded lists):** `discover.py` probes live models across all 3 harnesses (`agy models`, `~/.codex/.codex-global-state.json`, `~/.claude/cache/model-catalog/*` & `gateway-models.json`), and `route.py` scores and selects the best live model per tier automatically (`source: live_discovered`).
+9. **Epistemic Independence = Different Model Family (or Single-Host Clean-Context + Alt Family/Lens):** An independent reviewer (`review`, `security-review`, `critique`) must come from a different model family (`openai` vs `google` vs `anthropic`) than the builder (`route.py --builder <vendor>` enforces this). If only 1 agent exists on the machine (`--single-host`), `route.py` automatically switches to an intra-host alternate model family (e.g., `agy` switching from `gemini-4-argon-high` to `claude-opus-5-5-high`) + **Zero-Prior Clean-Context Sub-Agent**.
+10. **Empirical Huddle (Spike before Debate, Synthesis Option C):** When panelists disagree on a testable fact, run a 2-minute micro-spike/command to measure the truth instead of running another prose debate round. On design trade-offs, ask panelists to synthesize a better **Option C**.
+11. **Parent-to-Child Skill Path Sharing & Ephemeral Skill Sandbox (`--skill` + `skill_sandbox.py`):**
+    - **Rule 1 — Share Parent Skill Paths First (Never Re-Install What You Can Read):** `route.py --list-skills` scans all parent/host skill directories (`~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`, `~/.gemini/config/skills`, `plugins/*/skills`, `builtin/skills`). When a parent agent has a matching skill, pass `--skill <name>` in `agent_run.py run`/`batch` (or pass the `SKILL.md` path directly in a native sub-agent's brief). `agent_run.py` automatically injects the `SKILL.md` path and mounts the skill directory (`--add-dir`) so child agents read it directly without installing anything.
+    - **Rule 2 — Ephemeral Skill Sandbox (`~/.agent-orchestration/sandbox-skills/`):** Only when NO local parent skill covers the task, run `skill_sandbox.py search <query>` to search curated high-trust registries (`anthropics/skills`, `openai/skills`, `vercel-labs/agent-skills`, `huggingface/skills`, `obra/superpowers`, or verified GitHub repos with `>= 50` stars). **Always ask the user for approval first**, then run `skill_sandbox.py install <repo> [--subpath ...] --approved-by-user`. The skill is security-scanned and stored strictly inside `agent-orchestration`'s own ephemeral sandbox memory (never touching system/global folders) and can be deleted anytime via `skill_sandbox.py remove <name>` or `skill_sandbox.py purge`.
+
+12. **Orchestration Anatomy Engine & Keyhole Interlocks — Size Gate, Truth Lock, Settle & Audit to Zero, Change-Ripple Amend, 4x Junction Check (`anatomy.py` + `batch --audit`):**
+    - **Size It First (`Micro` <=1 | `Figure` 2–4 | `Hero` 5–8 | `Epic` >8):** Name the scale up front. If `>8` packages (`Epic`), stop and propose a `Hero` slice (`<=8` packages) first unless the user explicitly approves the Epic.
+    - **Truth Lock & Keyhole Invariants (`truth_contract` + `--invariant` + `truth_hash`):** Lock user prerequisites and thresholds (`KEY=VAL`, `KEY<=VAL`, `KEY>=VAL`, `must:PAT`, `forbid:PAT`) in `.orch/truth-contract.md` and `plan.json` with a SHA-256 `truth_hash`. Workers cannot write to `truth_contract` directly.
+    - **Settle & Audit to Zero (`anatomy.py init|settle|audit` & `agent_run.py batch --audit`):** Solves topological execution waves (`Wave 0, Wave 1, ...`), wires upstream `outputs` + `result.json` into downstream `context_file` mounts, and proves **0 problems** across 8 checks (`clearance`, `cycles`, `terminals`, `support`, `stand_in_briefs`, `skill_mounts`, `truth_contract`, `interlocks`).
+    - **Change-Ripple Protocol & Anti-Silent-Conflict (`anatomy.py amend` & `batch --auto-amend`):** Prevents one worker from changing a parameter while sibling workers silently remain on the old value. After each wave, `check_invariant_drift()` and `detect_cross_package_conflicts()` halt the pipeline if any worker violates a locked threshold (`INVARIANT_DRIFT` / `THRESHOLD_VIOLATION`) or defines conflicting constants across packages (`CROSS_PACKAGE_CONFLICT`). Formal changes require `truth_amendments` with proof (`evidence`), triggering `anatomy.py amend` to increment `truth_version`, mount `.orch/truth-amendment-vN.md` into all packages' `context_file`, and flag already-run packages with the old value as `stale_packages`.
+    - **1x Macro & 4x Junction Close-Ups (`anatomy.py inspect`):** Post-flight check across every seam verifying `missing_outputs`, `invariant_violations`, `cross_package_conflicts`, `truth_amendments`, `assumptions_challenged`, `open_questions`, and `evidence_warnings`.
+
+---
+
+## 2. Fast CLI Command Matrix (All 3 Agents)
+
+Replace `<skill>` with the skill folder path (e.g. `~/.agents/skills/agent-orchestration`).
+
+### A. Zero-Token Live Model & Skill Inspection + Routing
+```bash
+# 1. Inspect ALL live available models and installed specialized skills right now (0 tokens)
+python <skill>/scripts/route.py --list-models
+python <skill>/scripts/route.py --list-skills
+
+# 2. Refresh full capability snapshot (flags, MCPs, plugins, skills, live models)
+python <skill>/scripts/discover.py --quick          # fast version check (exit 10 -> run full)
+python <skill>/scripts/discover.py                  # full live model & capability snapshot
+
+# 3. Compute optimal vendor, live-scored model, matched specialized skills & hardware-safe wip (0 tokens)
+python <skill>/scripts/route.py --task-type review --risk med --builder codex --manager claude
+python <skill>/scripts/route.py --task-type research --need arxiv --manager agy --same-model
+
+# 4. Single-Host & Same-Model Mode (when only 1 agent or only 1 model is used across all sub-agents)
+python <skill>/scripts/route.py --task-type design --manager agy --same-model
+python <skill>/scripts/route.py --task-type review --builder agy --manager agy --same-model
+python <skill>/scripts/route.py --task-type design --manager agy --single-host
+
+# 5. Orchestration Anatomy: Init Truth + Keyhole Invariants, Audit to Zero, Amend Ripple & 4x Junction Check
+python <skill>/scripts/anatomy.py init --goal "Build & verify auth" \
+       --invariant "PORT=8080" --invariant "MAX_LATENCY_MS<=200" \
+       --pkg "contract:guided::src/types.py::.orch/auth-schema.md" \
+       --pkg "impl:guided:contract:src/auth/::src/auth/handler.py" \
+       --pkg "verify:exploratory:impl" --out .orch/plan.json
+python <skill>/scripts/anatomy.py audit .orch/plan.json
+python <skill>/scripts/agent_run.py batch .orch/plan.json [--audit] [--auto-amend]
+python <skill>/scripts/anatomy.py amend .orch/plan.json --set "MAX_LATENCY_MS<=250" \
+       --reason "Measured p99 under cold start" --evidence "bench.py:42 -> 235ms"
+python <skill>/scripts/anatomy.py inspect .orch/plan.json
+
+# 6. Ephemeral Skill Sandbox (ONLY when parent agent lacks a needed skill; MUST ask user before install)
+python <skill>/scripts/skill_sandbox.py check <keyword>
+python <skill>/scripts/skill_sandbox.py search <query> --min-stars 50
+python <skill>/scripts/skill_sandbox.py install <owner/repo> [--subpath <dir>] --name <slug> --approved-by-user
+python <skill>/scripts/skill_sandbox.py list
+python <skill>/scripts/skill_sandbox.py remove <slug>
+python <skill>/scripts/skill_sandbox.py purge [--expired]
+```
+
+### B. Unified Cross-Agent Runner (`agent_run.py`)
+Works identically from **Claude Code**, **Codex CLI**, or **Antigravity (`agy`)**:
+```bash
+# Call CODEX CLI (surgical logic, deep debugging, refactoring, live web search, isolated worktree)
+python <skill>/scripts/agent_run.py run --agent codex --brief brief.md --name audit-rng \
+       --task-type review --tier frontier --mode read --context-file .orch/spec.md [--search]
+
+# Call CODEX CLI for isolated parallel writing in a Git Worktree
+python <skill>/scripts/agent_run.py run --agent codex --brief brief.md --name impl-auth \
+       --task-type implement --mode write --may-write src/auth/ --worktree
+
+# Call CLAUDE CODE CLI (`claude -p`: 1M context gateway/catalog models, bare fast start, USD budget cap, worktree)
+python <skill>/scripts/agent_run.py run --agent claude --brief brief.md --name arch-review \
+       --task-type review --tier frontier --mode read --context-file .orch/spec.md [--bare] [--max-budget-usd 0.50]
+
+# Call ANTIGRAVITY CLI (`agy -p`: broad context synthesis, Gemini 4 Argon / Claude 5.5 hosting)
+python <skill>/scripts/agent_run.py run --agent agy --brief brief.md --name broad-scout \
+       --task-type explore --tier standard --mode read
+
+# Resume any session cheaply with only the delta (keeps original scope/sandbox)
+python <skill>/scripts/agent_run.py run --agent codex --brief delta.md --resume <session_id>
+
+# Record manager verdict (feeds Earned Autonomy in ~/.agent-orchestration/ledger.jsonl)
+python <skill>/scripts/agent_run.py verdict <run_dir> accept --note "Verified with pytest"
+python <skill>/scripts/agent_run.py stats
+```
+
+### C. Power Native Commands (Direct Harness Features)
+- **Codex CLI Native:**
+  - Non-interactive diff/branch/commit review: `codex review --uncommitted` | `codex review --base main` | `codex review --commit <SHA>`
+  - Isolated worktree execution: `codex exec --worktree -s workspace-write - < brief.md`
+  - Apply latest agent diff: `codex apply`
+- **Claude Code Native & CLI:**
+  - In-session subagent: `Agent(subagent_type="Explore"|"general-purpose", model="haiku"|"sonnet"|"opus", isolation="worktree", prompt="...")`
+  - Resume/message subagent: `SendMessage(to="<agent_id>", message="...")`
+  - Cloud multi-agent PR/branch review: `claude ultrareview`
+  - Background daemon agent: `claude --bg -p "<prompt>"` → manage via `claude agents`, `claude logs <id>`, `claude attach <id>`, `claude stop <id>`
+  - Fast cold-start headless call (skips hooks/LSP/auto-discovery): `claude -p --bare --output-format json ...`
+- **Antigravity (`agy`) Native:**
+  - Spawn subagent with isolated workspace: `invoke_subagent(TypeName="self"|"research", Role="...", Prompt="...", Model="inherit"|"flash"|"pro", Workspace="inherit"|"branch"|"share")`
+  - Direct peer/subagent messaging: `send_message(Recipient="<conversationId>", Message="...")`
+
+---
+
+## 3. Result Envelope Contract (`assets/result.schema.json`)
+
+Every worker returns one JSON object:
+- **Required:**
+  - `status`: `"done" | "partial" | "blocked" | "stopped"`
+  - `summary`: Conclusion first (1–5 sentences), **citing `[E1]` / `file:line`**.
+  - `deliverables`: `["path/to/file", ...]` (never paste huge blobs inline).
+  - `evidence`: `["[E1] src/train.py:142 — RNG seeded before optional module", "[E2] pytest tests/ -> 12 passed"]` (**must contain concrete anchors**).
+  - `risks`: `["open issue or unverified worry"]`
+  - `next_action`: `"what the manager should decide or run next"`
+- **Optional (v3 cognitive & handoff fields):**
+  - `confidence`: `"low" | "med" | "high"`
+  - `assumptions_challenged`: `["Brief assumed X, but src/foo.py:88 proves Y"]`
+  - `open_questions`: `["Emergent lead found in src/bar.py:19"]`
+  - `handoff_notes`: `"Direct technical notes/invariants for the next agent"`
+  - `truth_amendments`: `[{"key": "PORT", "old_value": "8080", "proposed_value": "9090", "reason": "...", "evidence": "..."}]`
+
+---
+
+## 4. When to Read Deep Reference Files (`references/`)
+
+Only open a reference file when you need its full template or edge-case rules:
+
+| File | Open ONLY when... |
+|---|---|
+| [`SKILL.md`](SKILL.md) | You need the full orchestration loop and safety policy |
+| [`references/multi-perspective-and-single-host.md`](references/multi-perspective-and-single-host.md) | **Single-agent mode (e.g. only `agy`)**, Zero-Prior de-biasing, Orthogonal Expert Council, and the 5-stage `Diverge → Falsify → Probe → Synthesize → Plan` workflow |
+| [`references/brief-and-budget.md`](references/brief-and-budget.md) | You need copy-paste templates for `tight`, `guided`, or `exploratory` briefs |
+| [`references/roles.md`](references/roles.md) | You are picking specific examination angles for a specialized role |
+| [`references/huddle.md`](references/huddle.md) | You are calling a multi-model huddle on a Type 1 or deadlocked decision |
+| [`references/team-shapes.md`](references/team-shapes.md) | You are designing a multi-phase pipeline, competing hypotheses, or peer mesh |
+| [`references/gates-and-routing.md`](references/gates-and-routing.md) | You are overriding `route.py` or checking permission blast-radius rules |
+| [`references/verification.md`](references/verification.md) | A worker failed, challenged a premise, or triggered `evidence_warnings` / `violations` |
+| [`references/adapters/codex-cli.md`](references/adapters/codex-cli.md) | You need advanced Codex CLI flags (`codex review`, `--worktree`, `--search`, profiles) |
+| [`references/adapters/claude-code.md`](references/adapters/claude-code.md) | You need advanced Claude CLI flags (`claude -p`, `--bare`, `--worktree`, `--bg`, `ultrareview`, gateway models) |
+| [`references/adapters/antigravity-cli.md`](references/adapters/antigravity-cli.md) | You need `agy` headless permission rules or native `invoke_subagent` details |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 haulth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# agent-orchestration
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skill điều phối đa agent và sub-agent (`Claude Code`, `Codex CLI`, `Antigravity / agy`), tập trung vào chia việc chạy song song hiệu quả theo phần cứng máy, chọn model tự động, chia sẻ trực tiếp skill từ agent mẹ sang agent con, và quản lý **Skill Sandbox tạm thời** an toàn.
+
+## Điểm cốt lõi
+- **Tự động nhận diện model khả dụng (0 token):** Quét trực tiếp các model đang có trên máy (`route.py --list-models`) và chọn model phù hợp nhất theo độ khó tác vụ (hỗ trợ cả chế độ 1 agent `--single-host` hoặc cùng 1 model `--same-model`).
+- **Chia sẻ trực tiếp Skill từ Agent mẹ sang Agent con (`--skill` — có sẵn là dùng ngay, không cài thêm):** Tự động dò các skill chuyên sâu mà Agent mẹ đang có (`route.py --list-skills`) và truyền thẳng đường dẫn `SKILL.md` + quyền đọc thư mục (`--add-dir`) cho Agent con.
+- **Ephemeral Skill Sandbox (`skill_sandbox.py`):** Khi thiếu skill chuyên sâu chưa có trên máy, chỉ tìm từ các kho chính hãng/uy tín cao (`anthropics/skills`, `openai/skills`, `vercel-labs/agent-skills`, `huggingface/skills`, hoặc repo đạt chuẩn uy tín), **bắt buộc hỏi ý kiến người dùng trước khi cài (`--approved-by-user`)**, quét bảo mật tĩnh và lưu tạm vào bộ nhớ riêng (`~/.agent-orchestration/sandbox-skills/`) — xóa sạch bất cứ lúc nào (`remove` / `purge`) mà không ảnh hưởng hệ thống.
+- **Giải phẫu công việc & Chốt chặn Khóa liên động (`Orchestration Anatomy & Keyhole Interlock` — `anatomy.py` & `batch --audit`):**
+  - **Size Gate (`Micro` <=1 | `Figure` 2–4 | `Hero` 5–8 | `Epic` >8):** Định cỡ quy mô ngay từ đầu; nếu vượt quá 8 gói việc (`Epic`), tự động dừng để đề xuất lát cắt `Hero` trước.
+  - **Truth Lock & Keyhole Invariants (`truth_contract` + `--invariant` + `truth_hash`):** Khóa chặt các quy chuẩn tiên quyết và thông số ngưỡng của người dùng (`--invariant "PORT=8080" --invariant "MAX_LATENCY_MS<=200" --invariant "must:..." --invariant "forbid:..."`) kèm mã băm `truth_hash` (SHA-256) và khóa quyền ghi `truth-contract.md`.
+  - **Chống tự ý đổi ngầm & Lan truyền thay đổi (`check_invariant_drift`, `detect_cross_package_conflicts`, `anatomy.py amend`):** Chặn triệt để tình trạng *"1 ông tự ý đổi thông số, mấy ông khác nín thin dẫn đến xung đột"*. Tự động quét code/output sau mỗi đợt sóng để bắt lỗi lệch ngưỡng (`INVARIANT_DRIFT`, `THRESHOLD_VIOLATION`) hoặc lệch hằng số giữa các gói (`CROSS_PACKAGE_CONFLICT`). Khi cần đổi thông số có bằng chứng (`truth_amendments`), lệnh `anatomy.py amend` (hoặc `batch --auto-amend`) tự động nâng `truth_version`, gắn thông báo `.orch/truth-amendment-vN.md` vào mọi gói việc và đánh dấu các gói đã chạy bằng thông số cũ là `stale_packages` để buộc đồng bộ lại.
+  - **Audit to Zero (`anatomy.py audit` / `batch --audit`) & 4x Junction Check (`anatomy.py inspect`):** Kiểm toán tự động **0 lỗi ở 8 hạng mục** trước khi chạy và soi cận cảnh **4x tại các khớp nối** sau khi chạy.
+- **Điều phối song song theo phần cứng thực tế (`batch` & native sub-agents):** Tự động đo **CPU cores, RAM trống, dung lượng ổ cứng và GPU VRAM** (`probe_hardware()`) để giới hạn số luồng song song an toàn (`recommended_wip`), kết hợp ngữ cảnh sạch (`Zero-Prior Brief`), bảng đen dùng chung (`--context-file`) và khóa vùng ghi tách biệt (`--may-write` / `--worktree`).
+- **Luật bằng chứng (`No Proof = No Claim`):** Mọi kết luận và phản biện (`assumptions_challenged`) bắt buộc kèm dẫn chứng kiểm chứng được (`file:line`, `command -> output`, `DOI/arXiv/PMID/URL`).
+
+## Lệnh sử dụng nhanh
+
+```bash
+# 1. Xem model khả dụng, skill có sẵn trên Agent mẹ và gợi ý định tuyến (0 token)
+python <skill>/scripts/route.py --list-models
+python <skill>/scripts/route.py --list-skills
+python <skill>/scripts/route.py --task-type research --need arxiv --manager agy --same-model
+
+# 2. Giải phẫu công việc + Khóa ngưỡng tiên quyết (--invariant) + Audit to Zero + Amend lan truyền & Soi khớp nối 4x
+python <skill>/scripts/anatomy.py init --goal "Triển khai & kiểm chứng module X" \
+       --invariant "PORT=8080" --invariant "MAX_LATENCY_MS<=200" \
+       --pkg "contract:guided::src/types.py::.orch/contract-out.md" \
+       --pkg "impl:guided:contract:src/core/::src/core/engine.py" \
+       --pkg "verify:exploratory:impl" --out .orch/plan.json
+python <skill>/scripts/anatomy.py audit .orch/plan.json
+python <skill>/scripts/agent_run.py batch .orch/plan.json [--audit] [--auto-amend]
+python <skill>/scripts/anatomy.py amend .orch/plan.json --set "MAX_LATENCY_MS<=250" \
+       --reason "Đo thực nghiệm p99" --evidence "bench.py:42 -> 235ms"
+python <skill>/scripts/anatomy.py inspect .orch/plan.json
+
+# 3. Chạy worker đơn lẻ (chia sẻ thẳng path skill của Agent mẹ qua --skill)
+python <skill>/scripts/agent_run.py run --agent agy --brief brief.md --mode read \
+       --skill literature-search-arxiv --context-file .orch/spec.md
+
+# 4. Skill Sandbox tạm thời (chỉ dùng khi máy chưa có skill; BẮT BUỘC hỏi người dùng trước khi cài)
+python <skill>/scripts/skill_sandbox.py check <keyword>
+python <skill>/scripts/skill_sandbox.py search <query> --min-stars 50
+python <skill>/scripts/skill_sandbox.py install <owner/repo> --subpath <path> --approved-by-user
+python <skill>/scripts/skill_sandbox.py list
+python <skill>/scripts/skill_sandbox.py remove <name>
+python <skill>/scripts/skill_sandbox.py purge [--expired]
+```
+
+## Cài đặt & Sử dụng qua NPX
+
+```bash
+# Cách 1: Cài qua chuẩn Agent Skills CLI (Claude Code, Codex, Antigravity, Cursor...)
+npx skills add haulth/agent-orchestration
+
+# Cách 2: Chạy trực tiếp trình cài đặt / kiểm tra hệ thống qua NPX (0 dependencies)
+npx github:haulth/agent-orchestration
+npx github:haulth/agent-orchestration doctor
+```
+
+Hoặc cài từ bản clone nội bộ:
+```powershell
+.\install\install.ps1   # Windows (đồng bộ vào ~/.claude, ~/.agents, ~/.codex, ~/.gemini/config)
+```
+```bash
+./install/install.sh    # macOS / Linux
+```

package/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: agent-orchestration
+version: 1.0.0
+license: MIT
+description: Manage subagents like a professional manager and coordinate intelligent multi-agent collaboration with low token cost. It covers whether to delegate at all, choosing a team shape, picking the right brief mode (tight, guided, or exploratory so structure never limits agent intelligence), routing to the right model family and vendor (Claude subagents, Codex CLI, Antigravity/agy, `claude -p`), sharing context directly via a Shared Blackboard (`--context-file`) and native peer messaging, running constructive & empirical huddles, and accepting results on evidence. Use it whenever a task could be split across agents or models, whenever you consider spawning subagents, running work in parallel, handing a task to Codex, Antigravity or Claude, getting a second opinion or independent review, or coordinating a multi-step job.
+---
+
+# Agent Orchestration
+
+> **Fast Start:** Read [`CATALOG.md`](CATALOG.md) in the skill root first for the 1-page cheat sheet of all core rules, CLI invocation commands for **Codex CLI**, **Claude Code CLI**, and **Antigravity (`agy`)**, specialized skill attachment (`--skill`), the Anti-Hallucination Evidence Law, and the reference index.
+
+You are the manager and integration owner. Workers own the deliverables and investigations you assign them. You set clear goals and safety boundaries up front, empower workers to think independently and challenge flawed premises, connect them directly to upstream artifacts so nuance is never lost, and judge results once on verifiable evidence.
+
+Six principles drive every rule below:
+1. **Multi-agent work has a real token cost — delegate only where it pays.**
+   - Published figures: multi-agent systems spend ~5x–15x the tokens of single-turn chat, and external CLI calls carry fixed cold-start overhead (~12.5k tokens on `codex`, ~19.5k on `agy`).
+   - Delegate only when **parallelism**, **context protection**, **epistemic independence** (a clean-context reviewer from a different model family), or **specialized capability** beats the cost of briefing and verification.
+2. **Unleash parallel intelligence; isolate or sequence writes.**
+   - Extra agents shine at thinking, exploring unknown unknowns, testing competing hypotheses, and auditing from diverse lenses.
+   - Concurrent writes to shared files conflict over hidden style and interface assumptions. Keep writes single-threaded in a shared working tree (`agent_run.py batch`), or give parallel writers frozen interfaces and isolated workspaces (`--worktree` on Codex/Claude, Claude `isolation: "worktree"`, or Antigravity `Workspace: "branch"|"share"`).
+3. **Structure must scaffold intelligence, never suffocate it.**
+   - Over-prescribing steps or locking an agent into a narrow tunnel causes **cognitive tunneling**: the agent answers your literal question while stepping over the real bug or architectural flaw next door.
+   - Match the brief's ceremony to the task's uncertainty (**Three Brief Modes**: `tight`, `guided`, `exploratory`), treat role checklists as a **floor rather than a ceiling**, and honor every worker's **Premise Challenge Right** (`assumptions_challenged`).
+4. **Anti-Hallucination Evidence Law (No Proof = No Claim).**
+   - Every critique finding, premise challenge (`assumptions_challenged`), and final conclusion (`summary`) **MUST** carry a verifiable ground-truth anchor in `evidence[]`: exact `file:line-line` + excerpt, `command -> exit code / output`, or measured numbers.
+   - Unbacked claims or vague skepticism ("this might be slow", "this seems risky") are never accepted as verdicts or blockers—`agent_run.py` automatically audits result envelopes and flags unanchored claims in `meta.json` (`evidence_warnings`).
+5. **Orchestration Anatomy Engine & Keyhole Interlocks — Size It, Truth Lock, Settle & Audit to Zero, Change-Ripple Amend (`anatomy.py` + `agent_run.py batch --audit`).**
+   - **Size It First (`Micro` <=1 | `Figure` 2–4 | `Hero` 5–8 | `Epic` >8):** Name the scale up front. If a plan exceeds 8 packages (`Epic`), **stop and propose a `Hero` slice (`<=8` packages) first** unless the user explicitly approves the Epic (`--allow-epic`).
+   - **Truth First & Keyhole Invariant Locks (`truth_contract` + `--invariant` + `truth_hash`):** Lock user prerequisites, constants, and threshold bounds (`--invariant "PORT=8080" --invariant "MAX_LATENCY_MS<=200" --invariant "must:verify_jwt" --invariant "forbid:eval("`) in `.orch/truth-contract.md` and `plan.json` with a SHA-256 keyhole digest (`truth_hash`). Workers are write-locked out of `truth-contract.md` so no single worker can silently drift from user prerequisites.
+   - **Settle & Audit to Zero (`anatomy.py init|settle|audit`):** `ao_common.settle_plan()` solves topological execution waves (`Wave 0, Wave 1, ...`) and auto-wires `truth_contract` + upstream `outputs` into downstream `context_file` mounts. `ao_common.audit_plan()` proves **0 structural & interlock defects** across 8 checks (`clearance`, `cycles`, `terminals`, `support`, `stand_in_briefs`, `skill_mounts`, `truth_contract`, and `interlocks`).
+   - **Anti-Silent-Mutation & Change-Ripple Protocol (`truth_amendments` + `anatomy.py amend` + Wave Interlock Gate):** Never allow one worker to change a shared constant/threshold while sibling workers silently remain on the old value. After each wave/batch, `check_invariant_drift()` and `detect_cross_package_conflicts()` scan deliverables for threshold drift (`INVARIANT_DRIFT` / `THRESHOLD_VIOLATION`) and conflicting constants across packages (`CROSS_PACKAGE_CONFLICT`). When a threshold genuinely must change, a worker emits `truth_amendments` with proof (`evidence`), and `anatomy.py amend` (or `batch --auto-amend`) increments `truth_version`, broadcasts `.orch/truth-amendment-vN.md` into all packages' `context_file`, and flags already-run packages that used the old value as `stale_packages` requiring re-sync.
+   - **1x Macro & 4x Junction Close-Ups (`anatomy.py inspect`):** Post-flight inspection across every producer→consumer seam checking `missing_outputs`, `invariant_violations`, `cross_package_conflicts`, `truth_amendments`, `assumptions_challenged`, `open_questions`, and `evidence_warnings`.
+6. **De-Biased Parallel Sub-Agents, Parent-to-Child Skill Path Sharing & Ephemeral Skill Sandbox (`references/multi-perspective-and-single-host.md`).**
+   - In a single session, your own prior tokens create **autoregressive confirmation bias** (making you overconfident in your initial hunch). Even when only **one agent** or **one model** is used (`--single-host` / `--same-model`), break out of context bias by spawning **clean-context parallel sub-agents** (`invoke_subagent`, `Agent()`, or `agent_run.py batch`) with **Zero-Prior (Blinded) Briefs** (passing only verified facts, symptoms, and `file:line` pointers—never leaking your unverified hypothesis).
+   - **Share Parent Skill Paths Directly (`--skill` — never re-install readable skills):** Discover all skills readable by the parent agent via `route.py --list-skills` (or `skill_sandbox.py check <kw>`). When the parent agent already has a skill (in `~/.agents/skills`, `~/.claude/skills`, `~/.codex/skills`, `~/.gemini/config/skills`, or plugins), pass `--skill <name>` (or give its `SKILL.md` path in the sub-agent's prompt) so the child agent reads the parent's skill directly without installing a duplicate.
+   - **Ephemeral Skill Sandbox (`skill_sandbox.py`):** Only when no local skill covers the domain need, search high-trust, high-reputation sources (`anthropics/skills`, `openai/skills`, `vercel-labs/agent-skills`, `huggingface/skills`, `obra/superpowers`, or repos with `>= 50` stars) via `skill_sandbox.py search <query>`. **Ask the user for permission first**, then install into `~/.agent-orchestration/sandbox-skills/` with `skill_sandbox.py install ... --approved-by-user` (static security audit enforced; removable anytime via `remove` or `purge` with zero impact on the user's system).
+
+## The Adaptive Loop
+
+1. **Frame the goal & uncertainty.** State the desired outcome and constraints. Decide whether the problem is well-specified (`tight` or `guided` mode) or open-ended with unknown unknowns (`exploratory` mode).
+2. **Economic gate: delegate or do it yourself.** Do it yourself if the brief costs as much as the work, takes <3 tool calls, or requires synthesis only you hold.
+3. **Pick a team shape** from `references/team-shapes.md`: Solo, Scout/Explorer fan-out, Builder + Reviewer, Smart friend, Competing hypotheses, Frozen-interface pipeline, or Interactive Peer Mesh.
+4. **Split the work cleanly:**
+   - For file writes and deliverables, scopes must be MECE (disjoint `--may-write` paths or isolated worktrees).
+   - For research, debugging, and review, deliberate perspective overlap across model families is encouraged.
+5. **Pass the four gates:** Delegation & Brief Mode → Permission & Isolation → Cognitive Model Routing → Verification (`references/gates-and-routing.md`). Run `scripts/route.py` (zero tokens) to get the recommended vendor, model family, tier, brief mode, verify level, and command. Override freely when you have context it lacks—just state why in one line.
+6. **Issue work orders & connect the Shared Blackboard** (`references/brief-and-budget.md`):
+   - Pick the brief mode (`tight` 4-line brief for lookups/small edits; `guided` for standard builds/reviews; `exploratory` for debugging, research, and design).
+   - **Avoid lossy manager relays:** when Worker B builds on or reviews Worker A's work, pass Worker A's artifact/diff directly via `--context-file <path>` (or native `send_message`) instead of re-summarizing it yourself.
+7. **Run and wait (Hardware-Aware Parallelism + Specialized Skills).** Launch independent packages in parallel (`agent_run.py batch` or native sub-agents), automatically scaling concurrency (`wip`) to the machine's live CPU cores, free RAM, GPU VRAM, and disk headroom (`ao_common.probe_hardware()`). Attach domain-specific skills via `--skill <skill_name>` when a worker needs specialized tools or workflows. Use `--name <slug>` for descriptive run folders while keeping `--task-type` canonical (`review`, `implement`, `explore`, `debug`...). Never poll or fabricate results.
+8. **Accept once, on evidence & epistemic signals** (`references/verification.md`):
+   - Check `assumptions_challenged`, `open_questions`, and `handoff_notes` alongside `status` and `evidence`. If a worker disproved a flawed assumption in your brief with solid evidence, **reward that discovery** and pivot the plan.
+   - Run cheap deterministic checks (tests, lint, grep, bounded git diff) before LLM judgment.
+   - Record your verdict (`agent_run.py verdict <run-dir> accept|revise|escalate|rollback|takeover`) so the shared ledger adapts future routing.
+9. **Integrate and synthesize.** Write the final user response yourself, conclusion first.
+
+## Three Brief Modes & Premise Challenge (`references/brief-and-budget.md`)
+
+Never force an open-ended investigation into a rigid assembly-line checklist, and never write a 50-line brief for a 5-line lookup:
+
+| Brief Mode | When to use | Structure |
+|---|---|---|
+| **`tight`** | Lookups, mechanical edits, simple unit tests | 4 compact items: **Intent & Done**, **Context/Artifacts**, **Scope/Authority**, **Output**. |
+| **`guided`** | Standard implementation, focused analysis, code review | **Role lens** (`roles.md`), **Intent**, **Definition of Done**, **Context & Upstream Artifacts**, **Latitude**, **Finish line**, **Scope & Budget**. |
+| **`exploratory`** | Root-cause debugging, unfamiliar codebase sensemaking, architecture design, huddles | **Role & Lens**, **Core Problem**, **Questions / Hypotheses to Test**, **Known Facts**, **Full read-only freedom to follow evidence trails & challenge premises**. |
+
+**Roles are lenses, not blinders (`references/roles.md`):**
+- The 4–6 examination angles in a Role block are a **floor, not a fence**.
+- Replace rigid "Not your job" blinders with **Adjacent owners (flag, don't duplicate)**: if a worker spots a bug, RNG leak, or broken contract outside its write scope, it must not ignore it—it reports it in `assumptions_challenged`, `open_questions`, or `handoff_notes`.
+
+## Huddle: Constructive & Empirical Consult (`references/huddle.md`)
+
+Call a huddle when facing a hard-to-reverse (Type 1) decision, conflicting evidence, a failed escalation, or a challenged core premise. Never call one for routine work.
+
+Protocol in 5 steps:
+1. **Problem Memo (1 page):** Facts, constraints, options known, and what empirical signal would settle the question.
+2. **Independent blind round:** 2–3 panelists with distinct lenses (`Architect`, `Red team`, `Domain expert`, `Implementer`, `User advocate`) and **different model families** answer in parallel without seeing each other's responses. They are explicitly invited to challenge the memo's framing and invent a synthesized **Option C**.
+3. **Crux Map & Empirical Spike Gate:** Extract the cruxes. **Mandatory gate:** if any crux is a testable fact (e.g., "does X permute RNG?", "is Y slow?"), **do not debate it in prose**—run a 2-minute micro-spike or command to measure the truth first.
+4. **Dialectical Synthesis (optional, 1 round, unresolved trade-offs only):** Share anonymized counterarguments and spike data. Ask panelists to concede disproved points or synthesize the best of both worlds (**Option C**).
+5. **Decide & commit:** Decide on evidence (never majority vote). Record the decision, strongest dissent, and reversal trigger.
+
+## Dynamic Model Discovery & Cognitive Routing (`references/gates-and-routing.md`)
+
+**Models are dynamically discovered, never locked to stale hardcoded strings:**
+- `discover.py` probes live available models across all 3 harnesses at zero token cost (`agy models`, `~/.codex/.codex-global-state.json` & `latest-model.md`, `~/.claude/settings.json`, `gateway-models.json`, and `model-catalog/*-ccd.json`).
+- `route.py` (`ao_common.dynamic_tier_config`) analyzes and scores the live discovered models to select the best model per tier (`fast`, `standard`, `frontier`, `frontier_max`) automatically (`source: live_discovered`), using `assets/models.json` only as a fallback baseline.
+
+Match the work to the model family's cognitive strengths:
+- **OpenAI (`codex`):** surgical logic, deep debugging, methodological/statistical auditing, refactoring, non-interactive `codex review`, `--worktree`, and `--search`.
+- **Anthropic (`claude`):** architectural synthesis, 1M-context deep code/prose reasoning (`nghi/claude-opus-5[1m]`, `claude-opus-5-5`, `claude-sonnet-5-5`), fast `--bare` headless runs, `--worktree`, `--bg` daemons, and `claude ultrareview`.
+- **Google (`agy`):** broad-context synthesis, rapid multi-file exploration, multimodal/UI, plus cross-family hosting (`gemini-4-argon-*`, `claude-opus-5-5-*`).
+
+**Epistemic Independence:** An independent reviewer (`review`, `security-review`, `critique`) must use a **different model family** from the builder (`route.py --task-type review --builder <vendor>` enforces this automatically).
+
+**Channels:**
+- **Native subagents** (`Agent` in Claude, `invoke_subagent` + `send_message` in Antigravity, `spawn_agent` in Codex) for fast in-session work, context forking, and interactive peer messaging.
+- **Unified external runner** (`scripts/agent_run.py run --agent codex|claude|agy`) for cross-family reviews, huddles, and schema-enforced out-of-session execution.
+  - Supports `--worktree` (Codex/Claude isolated git worktree), `--search` (Codex live web search), `--bare` and `--max-budget-usd` (Claude fast cold-start & cost cap), `--name <slug>`, `--context-file <path>`, and `--resume <session_id>`.
+
+## Reference Map
+
+| File | Read when |
+|---|---|
+| `CATALOG.md` | **Read first:** 1-page cheat sheet of all core rules, CLI commands (`codex`, `claude`, `agy`), and Evidence Law |
+| `references/multi-perspective-and-single-host.md` | **Single-agent mode (e.g., only `agy`)**, Zero-Prior de-biasing, Orthogonal Expert Council, and the 5-stage `Diverge → Falsify → Probe → Synthesize → Plan` workflow |
+| `references/team-shapes.md` | Choosing the team structure or setting up parallel workspaces / peer mesh |
+| `references/gates-and-routing.md` | Passing the four gates, matching cognitive strengths, and picking a channel |
+| `references/brief-and-budget.md` | Writing a `tight`, `guided`, or `exploratory` work order and using `--context-file` |
+| `references/roles.md` | Assigning a role lens without creating cognitive tunneling |
+| `references/verification.md` | Judging results, handling `assumptions_challenged`, and recording verdicts |
+| `references/huddle.md` | Running an independent-first huddle with the Empirical Spike Gate & Dialectical Synthesis |
+| `references/management-models.md` | Theoretical foundations (Mission Command, Stigmergy, Sensemaking, Dialectics) |
+| `references/adapters/claude-code.md` | Using Claude Code (`Agent`, `SendMessage`, worktrees, and `claude -p`) |
+| `references/adapters/codex-cli.md` | Using Codex CLI (`agent_run.py --agent codex`, `codex_run.py`, `--worktree`) |
+| `references/adapters/antigravity-cli.md` | Using Antigravity (`invoke_subagent`, `send_message`, `Workspace: branch/share`, `agy -p`) |
+| `references/two-way.md` | Cross-agent calling matrix, Shared Blackboard handoffs, and v3 operational fixes |
+| `references/self-update.md` | Discovering new models/tools (`discover.py`) and promoting candidates |
+| `assets/models.json` | Source of truth for model families, tiers, cognitive strengths, and task routing |
+| `assets/result.schema.json` | v3 result envelope (with optional `confidence`, `assumptions_challenged`, `open_questions`, `handoff_notes`) |

package/assets/models.json

@@ -0,0 +1,105 @@
+{
+  "updated": "2026-10-25",
+  "note": "Baseline fallback tiers and task routing rules. Dynamic live discovery (`discover.py` -> `ao_common.dynamic_tier_config`) automatically scores and selects live available models from `~/.agent-orchestration/capabilities.json` (`source: live_discovered`), falling back to this file when no live snapshot is present.",
+  "tier_order": ["fast", "standard", "frontier", "frontier_max"],
+  "risk_floor": {"low": "fast", "med": "standard", "high": "frontier"},
+  "vendors": {
+    "codex": {
+      "company": "openai",
+      "cognitive_strengths": ["surgical-logic", "deep-debugging", "methodological-audit", "refactoring"],
+      "tiers": {
+        "fast": {"model": "gpt-5.6-luna", "effort": "low", "family": "openai"},
+        "standard": {"model": "gpt-5.6-sol", "effort": "medium", "family": "openai"},
+        "frontier": {"model": "gpt-6-astra", "effort": "high", "family": "openai"},
+        "frontier_max": {"model": "gpt-6-astra", "effort": "xhigh", "family": "openai"}
+      },
+      "fallback_model": "gpt-6-astra",
+      "overhead_tokens": 12500,
+      "resume_overhead_tokens": 1500,
+      "notes": [
+        "Provider 9router: accepted models can differ from local cache; on model_or_config failure use fallback_model once.",
+        "gpt-5.6-luna/low was confirmed by a real call on 2026-09-25 (14.2k tokens). gpt-6-astra is the config default. gpt-5.6-sol/medium was confirmed by a real 871 s, 73k-token code review on 2026-09-26.",
+        "A sandboxed Codex worker cannot call agy or claude (network blocked); the manager chains vendors."
+      ]
+    },
+    "agy": {
+      "company": "google",
+      "cognitive_strengths": ["broad-context-synthesis", "multi-file-exploration", "cross-family-hosting", "multimodal-and-ui"],
+      "tiers": {
+        "fast": {"model": "gemini-3.8-flash-low", "family": "google"},
+        "standard": {"model": "gemini-4-argon-medium", "family": "google"},
+        "frontier": {"model": "gemini-4-argon-high", "family": "google"},
+        "frontier_max": {"model": "claude-opus-5-5-high", "family": "anthropic"}
+      },
+      "fallback_model": "gemini-3.8-flash-high",
+      "overhead_tokens": 19500,
+      "resume_overhead_tokens": null,
+      "notes": [
+        "Updated 2026-10-24 (agy 1.4.4): gemini-3.1-pro-* was replaced by gemini-4-argon-{low,medium,high} and claude-{sonnet,opus}-5-5-{low,medium,high}.",
+        "Effort is baked into the model slug; pass --effort only if you need to override.",
+        "Review precision on flash was 2/10; use gemini-4-argon-high or claude-opus-5-5-high for high-precision review, and flash for broad scouting.",
+        "Headless print mode auto-denies tools that need confirmation and can return SUCCESS with an empty response."
+      ]
+    },
+    "claude": {
+      "company": "anthropic",
+      "cognitive_strengths": ["architecture-synthesis", "nuanced-implementation", "exploratory-reasoning", "human-alignment"],
+      "tiers": {
+        "fast": {"model": "haiku", "family": "anthropic"},
+        "standard": {"model": "sonnet", "family": "anthropic"},
+        "frontier": {"model": "opus", "family": "anthropic"},
+        "frontier_max": {"model": "opus", "effort": "max", "family": "anthropic"}
+      },
+      "fallback_model": "sonnet",
+      "overhead_tokens": null,
+      "resume_overhead_tokens": null,
+      "notes": [
+        "In-session subagents (Agent tool) have small overhead; `claude -p` from another harness starts cold.",
+        "Updated 2026-10-24: Claude Code 2.1.308 under %LOCALAPPDATA%\\Claude-Data is logged in (oauth_token). ao_common.py resolves both AppData and LocalAppData (Claude-Data / Claude-3p) paths."
+      ]
+    }
+  },
+  "tasks": {
+    "lookup":          {"base_tier": "fast",     "verify_floor": "L1",  "brief_mode": "tight",       "vendor_preference": ["native", "agy", "codex"], "independent": false, "writes": false},
+    "summarize":       {"base_tier": "standard", "verify_floor": "L1",  "brief_mode": "guided",      "vendor_preference": ["native", "agy"],          "independent": false, "writes": false},
+    "explore":         {"base_tier": "standard", "verify_floor": "L1",  "brief_mode": "exploratory", "vendor_preference": ["native", "agy", "codex"], "independent": false, "writes": false},
+    "mechanical-edit": {"base_tier": "fast",     "verify_floor": "L2",  "brief_mode": "tight",       "vendor_preference": ["native", "agy", "codex"], "independent": false, "writes": true},
+    "docs":            {"base_tier": "fast",     "verify_floor": "L1",  "brief_mode": "guided",      "vendor_preference": ["native", "agy", "claude"],"independent": false, "writes": true},
+    "implement":       {"base_tier": "standard", "verify_floor": "L2",  "brief_mode": "guided",      "vendor_preference": ["native", "codex", "claude", "agy"], "independent": false, "writes": true},
+    "system-dev":      {"base_tier": "frontier", "verify_floor": "L2",  "brief_mode": "guided",      "type1_verify": "L3", "vendor_preference": ["native", "codex", "claude", "agy"], "independent": false, "writes": true, "panel": true},
+    "test":            {"base_tier": "standard", "verify_floor": "L2",  "brief_mode": "tight",       "vendor_preference": ["native", "codex", "claude"],        "independent": false, "writes": true},
+    "refactor":        {"base_tier": "standard", "verify_floor": "L2",  "brief_mode": "guided",      "vendor_preference": ["codex", "native", "claude"],        "independent": false, "writes": true},
+    "debug":           {"base_tier": "frontier", "verify_floor": "L2",  "brief_mode": "exploratory", "vendor_preference": ["codex", "native", "claude"], "independent": false, "writes": false},
+    "design":          {"base_tier": "frontier", "verify_floor": "L2",  "brief_mode": "exploratory", "type1_verify": "L3", "vendor_preference": ["native", "codex", "claude"], "independent": false, "writes": false},
+    "review":          {"base_tier": "standard", "verify_floor": "L1",  "brief_mode": "guided",      "vendor_preference": ["codex", "agy-pro", "claude", "native"], "independent": true, "writes": false},
+    "security-review": {"base_tier": "frontier", "verify_floor": "L3",  "brief_mode": "guided",      "vendor_preference": ["codex", "claude", "native"], "independent": true,  "writes": false},
+    "critique":        {"base_tier": "frontier", "verify_floor": "n/a", "brief_mode": "exploratory", "vendor_preference": ["codex", "agy", "claude", "native"], "independent": true,  "writes": false, "panel": true},
+    "spike":           {"base_tier": "standard", "verify_floor": "L1",  "brief_mode": "exploratory", "vendor_preference": ["codex", "native"],        "independent": false, "writes": false}
+  },
+  "task_aliases": {
+    "huddle": "critique",
+    "multi-angle": "critique",
+    "council": "critique",
+    "research": "explore",
+    "investigate": "explore",
+    "sensemaking": "explore",
+    "brainstorm": "explore",
+    "plan": "design",
+    "architecture": "design",
+    "fix": "implement",
+    "code": "implement",
+    "coding": "implement",
+    "feature": "implement",
+    "build": "system-dev",
+    "develop": "system-dev",
+    "fullstack": "system-dev",
+    "system-build": "system-dev",
+    "draft": "docs",
+    "judge": "review",
+    "verify": "review",
+    "audit": "review",
+    "methodology-review": "review"
+  },
+  "vendor_aliases": {"agy-pro": {"vendor": "agy", "min_tier": "frontier"}},
+  "candidates": []
+}

package/assets/result.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "WorkerResult",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["status", "summary", "deliverables", "evidence", "risks", "next_action"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["done", "partial", "blocked", "stopped"],
+      "description": "done = acceptance criteria met; partial = budget hit with useful progress; blocked = cannot proceed without a decision; stopped = andon pulled (anomaly, wrong premise, scope or safety issue)."
+    },
+    "summary": {
+      "type": "string",
+      "description": "Conclusion first, 1-5 sentences. Every key verdict or conclusion MUST cite an item in `evidence` (e.g. [E1], file:line, or command output). Unbacked claims are rejected as hallucination risk."
+    },
+    "deliverables": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "File paths, diff locations or artifact paths. Never paste large content here."
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Verifiable ground-truth proof: `file:line-line` + excerpt, `command -> exit/output`, measured numbers, or URL. One item per claim. Prose opinions without anchors do not count as evidence."
+    },
+    "risks": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Open issues, assumptions, out-of-scope observations."
+    },
+    "next_action": {
+      "type": "string",
+      "description": "What the manager should do or decide next. Empty string if nothing."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "med", "high"],
+      "description": "Optional: worker's epistemic confidence in the result based on evidence strength."
+    },
+    "assumptions_challenged": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional: premises in the manager's brief that were falsified or misframed. MUST include a verifiable citation (`file:line` or `command -> output`) or a concrete micro-spike that proves it; unbacked skepticism goes to `risks`, not here."
+    },
+    "open_questions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional: high-value questions, surprises, or emergent leads discovered during the work, with where they were seen (`file:line`)."
+    },
+    "handoff_notes": {
+      "type": "string",
+      "description": "Optional: direct technical notes, invariants, or warnings (with `file:line`) for the next agent in a pipeline or review."
+    },
+    "truth_amendments": {
+      "type": "array",
+      "description": "Optional: formal request to amend a locked prerequisite, threshold, or shared interface in the Truth Contract when empirical evidence proves the initial value is infeasible. Never mutate shared constants silently; declare amendments here with proof so all sibling/downstream packages are updated.",
+      "items": {
+        "type": "object",
+        "required": ["key", "proposed_value", "reason", "evidence"],
+        "properties": {
+          "key": { "type": "string", "description": "Invariant or shared parameter/interface name (e.g. MAX_BATCH_SIZE, PORT, API_SCHEMA)." },
+          "old_value": { "type": "string", "description": "Previous locked value in Truth Contract." },
+          "proposed_value": { "type": "string", "description": "New value proposed by this package." },
+          "op": { "type": "string", "enum": ["=", "<=", ">=", "<", ">", "must", "forbid"], "default": "=" },
+          "reason": { "type": "string", "description": "Why the amendment is necessary." },
+          "evidence": { "type": "string", "description": "Verifiable proof (`file:line` or `command -> output`) justifying the change." },
+          "affected_packages": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Other packages that must be notified or re-synced if this amendment is adopted."
+          }
+        }
+      }
+    }
+  }
+}