@akinet/akidevrule 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lạc Việt Anh (fb.me/lacvietanh)
+
+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

@@ -0,0 +1,356 @@
+# akidevrule
+
+One install command turns a fresh environment into Aki's full working baseline — for **Claude Code, Antigravity/Gemini, Codex CLI, Kiro CLI, and Grok CLI**, generated from one agent-neutral source: a shared rule corpus that loads itself at the right moment (Claude Code + Antigravity), plus a small set of sharp, single-purpose skills synced to every CLI that natively consumes the shared `SKILL.md` open standard.
+
+**Quick install (npm):**
+
+```bash
+npx @akinet/akidevrule@latest
+```
+
+`npx` always fetches the latest published version — re-running the command is how you update. Requires **Node.js 18+** and nothing else. Add `--check` to print installed-vs-latest without changing anything: `npx @akinet/akidevrule@latest --check`.
+
+**Or install with the shell one-liner:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lacvietanh/akidevrule/master/install.sh | bash
+```
+
+Also available: `bash install.sh` from a local checkout. The launcher is intentionally simple — inspect it before running.
+
+On **Windows** (without npm), clone the repo and run the installer directly (inspectable, matching this repo's philosophy):
+
+```powershell
+git clone https://github.com/lacvietanh/akidevrule.git; cd akidevrule; .\install.ps1
+# or: node install.mjs
+```
+
+This Git repository is the source of truth; `dev.akitao.com` is the presentation layer. Edit here, run the installer, done. It is **not** an auto-updater, daemon, package manager, or control plane.
+
+## Contents
+
+- [Requirements](#requirements)
+- [What you get](#what-you-get)
+- [Usage model](#usage-model)
+- [Repository layout](#repository-layout)
+- [What the installer does](#what-the-installer-does)
+- [Gemini / Antigravity model](#gemini--antigravity-model)
+- [What is excluded](#what-is-excluded)
+- [Why `~/.aki/akidevrule`](#why-akiakidevrule)
+- [Uninstall](#uninstall)
+
+## Requirements
+
+The installer is `install.mjs` — one cross-platform Node.js program (Node stdlib + global `fetch` only, no `rsync` / `find` / `awk`). `install.sh` and `install.ps1` are thin launchers that locate `node` and hand off to it. The skill helper scripts under `skills/akiflow/scripts/` are Python (`*.py` is the source of truth; the matching `*.sh` files are transitional Unix wrappers) — they run only when you invoke that skill, not to install or update.
+
+| Platform | Status | Notes |
+|---|---|---|
+| macOS | ✅ Supported | Primary target. `npx @akinet/akidevrule@latest`, or `./install.sh` / `node install.mjs`. |
+| Linux | ✅ Supported | Any distribution with Node 18+. `npx @akinet/akidevrule@latest`, or `./install.sh` / `node install.mjs`. |
+| Windows | ✅ Supported | `npx @akinet/akidevrule@latest`, or `install.ps1` in PowerShell, or `node install.mjs`. No WSL, Git Bash, or POSIX shell required — the installer and hooks are pure Node. Verified on `windows-latest` in CI. |
+
+Tooling — have these installed first:
+
+- **Node.js 18+** — the one hard requirement to install or update. The installer and the SessionStart update-check hook are Node; the 18 floor is the built-in `fetch` the update check uses. `install.sh` / `install.ps1` locate `node` and stop with one clear message if it is missing.
+- **Python 3.7+** — only to *run* the akiflow skill helper scripts (`skills/akiflow/scripts/*.py`); never needed for install or update.
+- `git` — for the `git clone` remote install.
+
+Interpreter convention (documented once): the installer and hooks run on `node` — the same command on every platform. The bundled skill helper scripts still use `python3` on Unix and `py -3` / `python` on Windows.
+
+## What you get
+
+### Ten skills
+
+| Skill | Invoke | Purpose |
+|---|---|---|
+| `akirule` | automatic, every conversation | Smart rule router — contextual rules on signal match, everything on `nạp full` / `load all rules`. Core rules do not pass through it: the harness `@`-imports them, so they hold even when this skill never runs. Also owns the **`[RULES]` receipt** — one mandatory line reporting the whole rule context (`core` + `router` + a `missing:` field), so that "the rule never arrived" stops sharing a signature with "the rule arrived and was ignored". Hidden from the `/` menu by design. |
+| `akiflow` | `/akiflow` | Lead-coordinated **agent council** for work needing more than one kind of judgment. The lead's job is two laws: **ANCHOR** — the owner's verbatim message is pinned as the run's immutable first block (`council_open.py` refuses to open a room without it) and every numbered requirement must quote a fragment of it; and **JUSTIFICATION** — every seat, check and script is OFF by default and turns on only when this run produces a reason, so there are no standing seats and no roster derived from a tier. It decomposes the request into owned work items, checks a three-condition activation gate, and convenes seats from the five definitions in `~/.claude/agents/` — one batch, each seat traced to a requirement, never picked from a menu. **Two shapes, discriminated by whether anything is actually being arbitrated.** A *council* is items with adversaries, for work where two competent seats could reach different defensible answers. A *dispatch* is lanes with exclusive file ownership, for a fan-out whose answer is already knowable and whose only real hazard is two workers writing the same file — `--convene` refuses an overlapping `writes:` before a token is spent. Dispatch drops the challenger, the debate and the three-condition gate; it keeps the anchor, the quoted requirements, the `[RULES]` receipts, the durable record and the whole closure gate. It exists because 19 of 70 live rooms posted no debate turn at all and 11 of those still did substantive fan-out work, paying council overhead for machinery they never used. Orthogonally, three modes discriminated by one question, *what changes outside the room*: `discuss`, `audit` (read-only by construction), `execute` (only `aki-maker` may write). The lead does no menial work and settles what doctrine answers, escalating only a one-way door, a contradiction with documented design, or scope expansion — then writes the owner's answer back into doctrine the same turn, so a question never escalates twice. `council_verify.py` refuses closure on a missing anchor, a requirement quoting nothing the owner wrote, a declared seat that left no trace anywhere in the session, a seat with no `[RULES]` receipt, or an unanswered reminder — reading each seat's own `<seat>.md` as well as its turns, and printing `SKIP` rather than `PASS` where there was nothing to check — and deliberately requires no named seat, since an earlier version that did forced a seat to exist in a run with nothing to enforce and was gamed rather than questioned. **A read is a subscription, not a purchase** — the cost model that shapes how the room is used: every turn re-sends the whole history, so a read of size `S` at turn `t` of a `T`-turn run is charged about `S × (T − t)`, and pulling a 50k-token room at turn 50 of 200 costs ~7.5M cache-read tokens from one call. Measured on a real run with three `aki-maker` seats doing every file edit, the lead still held 70% of cache-read and 66% of output: delegation moves the work but not the money, because what a run pays for is the lead's own accumulated context. Hence `council_read.py --grep` to locate for a few hundred bytes and `--turn` to pull only what the grep pointed at. Close-out reconciles declared model tiers against actual spend, cross-CLI calls added by hand since they never appear in the transcript. Design record: [`docs/arch/akiflow.md`](docs/arch/akiflow.md). |
+| `akithink` | `/akithink` | Structured deep-thinking session for big, hard-to-reverse, or goal-ambiguous decisions: restate → goal excavation → first principles → mandatory critique → convergence into a `docs/` decision record. Recommends a top-tier model (Opus/Fable). |
+| `akihtmlreport` | `/akihtmlreport` | Distills a dense analysis already in the conversation into one self-contained, ultra-wide `REPORT.html` at the project root — no new analysis, no dropped detail — then opens it locally. Exactly one per project; asks before overwriting. |
+| `akihelp` | `/akihelp` | Live introduction to the whole installed Aki system, rendered by reading `index.md` and skill frontmatters at runtime — it can never go stale. Includes a **painpoint → what to say** table (sprawling CSS, docs that no longer match code, a half-finished tree, a pre-ship check, a hard-to-reverse decision, padded or hard-wrapped output, over-guarded flows, UX friction, pricing calls) built from that live state, with any row whose target is not installed dropped rather than shown. Closes on the caveat that governs everything else: `akirule` is a skill and therefore best-effort, so name the rule file in the prompt whenever the load must be deterministic. |
+| `akigitcommit` | `/akigitcommit` | Turns a messy working tree into a few clean, logically grouped Conventional Commits. Triages a half-finished tree first — finished vs mid-edit vs abandoned vs accidental, asking rather than guessing — then stages by explicit path, never `git add -A`, never pushes unasked. |
+| `aki-article-writer` | `/aki-article-writer` or natural language | Per-project article writing pipeline: research & fact-verification, SEO metadata, JSON-LD schema, UX-psychology-aware content, and a dedicated Image Scout subagent (Gemini Flash / Haiku) for search → download → visual inspection → ffmpeg processing → slug-named WebP output. One subagent per article; image work is always isolated to a separate lightweight subagent. |
+| `akidevsync-notes` | natural language | Reads/edits a project's `.akidevsync/notes.json` — the per-project task list the Aki-Dev-Sync app itself writes (list/add/pin/mark-done/edit/delete tasks) via a bundled script that preserves the app's own JSON formatting, plus a workflow for cross-checking pinned notes against a shipped release (CHANGELOG + code) before marking them done. |
+| `akilint` | `/akilint` or a penalty card | Mechanical format lint for the penalty-card classes of `RULE-agent-behavior.md` §0: hard-wrapped code comments and markdown prose (`[WRAP]`) and oversize comments (`[YAP]`, always labeled *review* — a flag for judgment against `coding.B4`, never an auto-delete verdict). Thin wrapper over the shared `scythe.py` detector (deterministic line matching, exit-code aware, cannot fabricate evidence) — the same script akiflow's `aki-conduct` seat uses, so a card name means the same thing everywhere. `[FLUFF]` (density) is content judgment and explicitly out of a script's reach. |
+| `akiship` | `/akiship` | One-command full release: front-loads every check (release state, tree triage), then runs `RULE-release.md` B7's checklist unattended — diff-scoped hygiene (scythe, dead code, comment doc-refs on the accumulation only), external-action completeness, record truthfulness, doc sync across every record surface (plans, `arch`/`feat`, README, task notes, bound standards docs), version mint or defer, registry publish for npm/crates/PyPI packages (`RULE-release.md` B9 — an OTP-gated publish is the single hand-off) — committing via `akigitcommit` with confirmation pre-answered. **Activation is literal**: only a turn containing the exact token `/akiship` and asking for the run to be *performed* starts it — `/akiship` inside a question is a consult (answer in chat, change nothing), and words like "trọn vẹn" or "release trọn gói" on their own are vocabulary, not a trigger. Governed by the B8 contract: that invocation is the authorization, blockers are reported once as a batch or the run completes with zero mid-run questions, and it stops only for public-history ambiguity, unclassifiable work, or a design contradiction. Push/deploy stay opt-in — named explicitly, or via completion-intensity phrasing (canonical list in `RULE-release.md` B8, e.g. "trọn vẹn"). |
+
+### Five agent definitions
+
+A seat used to be convened by job title and then handed rules. The order is inverted here: an agent **is** a system prompt plus a rule set, and a name with no distinct filter behind it is a rule demanding a salary. Writing them in Claude Code's own `~/.claude/agents/` format makes three properties mechanical that had only ever been prose — read-only enforcement (`tools:` simply omits Edit/Write), the model tier (`model:`, so it is never improvised mid-run), and the fact that an undefined seat cannot be convened at all.
+
+| Agent | Tools | Standard of "correct" |
+|---|---|---|
+| `aki-hands` | Read, Grep, Glob | none — **judgment forbidden**; facts with `file:line` only. Carries the cross-CLI substrate table (Claude subagent · agy flash · kiro-cli · `cl-9rt` proxy lane), with flags and failure modes read from recorded harness facts rather than re-probed |
+| `aki-judge` | Read, Grep, Glob | **exactly one** standard, named at spawn (`pattern`, `proportion`, `ux`, `db`, …). Several standards in one head average into one mild opinion and the disagreement — the useful part — disappears |
+| `aki-conduct` | + Bash | the corpus itself. Its unique job is separating **LOAD-fail** (the rule never arrived) from **COMPLY-fail** (it arrived and was violated); `scythe.py` is one of its tools, never a seat and never a gate |
+| `aki-challenger` | Read, Grep, Glob | attacks the result from a clean context — defined by what it is *not* given (the reasoning). Always closes with *"what can be cut?"* and *"does this answer the anchored words?"* |
+| `aki-maker` | Read, Edit, Write, Bash | `coding` + `pattern` + the domain rules in its brief. The only agent permitted to write, and therefore the most narrowly scoped: it implements a decision, it does not make one |
+
+A catalog is not a roster. Five files on disk make it easy to pick seats from a menu, which is the failure they were built to end — a seat is convened only when it traces to a requirement in the owner's own words.
+
+**Claude Code only, deliberately.** `SKILL.md` is an open standard with five implementations; an agent-definition format currently has one, so building a vendor-neutral layer over a single consumer would be exactly the speculative generality `pattern.A2` forbids. Reopen trigger: a second CLI publishing an agent format promotes `claude/agents/` to a top-level `agents/` rendered per vendor, the way `AG_RULE_MAP` already renders rules for Antigravity.
+
+### A rule corpus that routes itself
+
+`payload/` files follow a strict naming convention:
+
+- `RULE-*.md` — constraints: what the agent must or must not do (behavior, coding, design/patterns, docs, content, stacks — Nuxt/Cloudflare + Tauri, UI, SEO, release, DB design, business/market).
+- `METHOD-*.md` — analytical frameworks: how to reason through a specific class of problem. Heavy, loaded only when the task is genuinely analytical.
+- `index.md` — file manifest, precedence order, cross-cutting lens.
+
+Loading happens on two different mechanisms, and the difference matters more than the tier numbering does.
+
+**Core — harness-embedded, not routed.** `index.md`, `RULE-agent-behavior.md`, `RULE-coding.md` and `RULE-pattern-core.md` are `@`-imported by `~/.claude/CLAUDE.md`, which Claude Code reads mechanically at session start. No model decision is involved, so they are the only rules that genuinely apply to every task. The two rule files were promoted out of Tier 1 after "default ON" proved to be a statement of intent rather than a mechanism: routing them through a skill meant they loaded only when the model first chose to invoke that skill, and the rules needing the most owner correction were absent from the context rather than present and disobeyed. They cost context in every session, including sessions with no code in them — that is the price of the guarantee. `@` imports have this effect **only** inside `CLAUDE.md` — the same syntax written into a skill body looks like an import but loads nothing, because a skill body is read only after the model has already chosen to invoke the skill.
+
+**Everything else — routed by the `akirule` skill**, and therefore best-effort: it applies when the model invokes the skill and a signal matches. Sensitivity is deliberately high (err toward loading — a false positive costs a few tokens, a false negative causes wrong behavior).
+
+- **Tier 1 — Contextual, read on signal match:** `RULE-docs.md` (structure and lifecycle, plus the docs-vs-code drift audit), `RULE-content-write.md` (UI copy and writing style, plus the content audit — canonical-term drift, density deletion test, i18n coverage), `RULE-stack-akiNuxtCf.md`, `RULE-stack-tauri.md` (Tauri v2 + Rust: never-block-the-UI, version SSOT, target context, the macOS TCC/Gatekeeper boundary for spawned sidecars), `RULE-ui-pattern.md` (design-system layer: the subtraction pass that runs before the tier ladder, class taxonomy, tokens, variant API, and the audit playbook), `RULE-seo.md`, `RULE-release.md`, `RULE-db-design.md`, `RULE-biz.md` (market-facing decisions: positioning, pricing, audience) — plus the analytical methods (tagged `Analytical` in `index.md`, but mechanically signal-loaded like the rest of Tier 1): `METHOD-audit-flow.md` (refactors, multi-file bugs, fragile flows), `METHOD-audit-zero-trust.md` (strict mechanical-first audit: detectors before opinion, exact matches separated from pattern-level candidates), `METHOD-deep-think.md` (scope/architecture/value decisions, first-principles and critique-style thinking), `METHOD-ux-psych.md` (UX/user-behavior evaluation, onboarding and conversion flows), `METHOD-proportionality.md` (sizing a guard, limit or accepted risk against reach, capability, motive and blast radius — the lens that stops both over-engineering and client-side-limits-as-enforcement), and `METHOD-audit-subtraction.md` (repo-wide "does this need to exist" sweep, terminating on two dry rounds).
+- **Tier 2 — Full load on explicit command:** `nạp full` / `load all rules` reads every `RULE-*`/`METHOD-*` file at once.
+
+No harness magic beyond the `CLAUDE.md` import: Tier 1 is trigger instructions telling Claude to Read the file from `~/.aki/akidevrule/` when signals match; Tier 2 is the explicit-command escape hatch.
+
+### Addressing — `topic.A1`, and the `⟨Aki⟩` flag
+
+Every rule/method file is internally organized into groups `A`/`B`/`C` and numbered items `1`/`2`/`3…`, so any single rule can be named precisely — `coding.B2` (changing existing code), `stack.C1` (canonical component names) — without touching routing or renaming any file (`topic` is the filename minus its `RULE-`/`METHOD-` prefix). The full group map lives in `payload/index.md`.
+
+Three files (`RULE-seo.md`, `RULE-release.md`, `RULE-stack-akiNuxtCf.md`) mix universal rules with content specific to Aki's own AkiNuxtCf ecosystem (usePageSeo API, releases.json schema, canonical component names, …). That ecosystem-specific content is isolated into each file's **last group**, logically flagged `⟨Aki⟩`. It stays in this public repo and auto-loads like everything else — Aki is this repo's heaviest user, so auto-load stays more valuable than a clean public/private split — but the flag marks exactly what a stripped public export would drop. Every other file, and every group outside `⟨Aki⟩`, is 100% universal.
+
+### Project binding & change policy
+
+Each project keeps a root `CLAUDE.md` that references the `akirule` skill as the rule loader, defines project-specific facts and overrides, stays short, and avoids duplicating shared rules.
+
+Aki-RULE changes affect many projects. Before changing rule files, clarify the intended rule, scope, and tradeoff unless the user explicitly requests the exact change.
+
+### One brain, two modes
+
+`METHOD-deep-think.md` is a single analytical brain — goal excavation, first principles, mandatory critique, conditional techbiz lens — consumed two ways:
+
+- **Passive:** `akirule` auto-loads it inline when a normal task hits a signal ("should we…", "is it worth…", tradeoff talk). Applied briefly inside the current answer, at most one clarifying question. Carries a radar rule: if the decision turns out to be one-way-door, large-scope, or goal-ambiguous, it must say "this deserves a `/akithink` session" instead of settling for a shallow pass.
+- **Active:** the user runs `/akithink`, which drives the same METHOD through a full 5-phase interactive protocol at maximum depth and ends with a proposed decision record under `docs/` (plus `/akihtmlreport` when the material is complex).
+
+Content-wise, active is a superset of passive; mechanically, only `/akithink` runs the interactive protocol.
+
+### Update notifications — notify-only
+
+A `SessionStart` hook and the installer's `--check` flag both classify install status through one shared parser (`claude/hooks/aki_version_check.mjs`), which reads a keep-a-changelog file's *latest released* version — its first `## [x.y.z]` heading, skipping the `[Unreleased]` buffer at the top (a version comparison that matched `[Unreleased]` against `[Unreleased]` on both sides never detected an update at all — fixed by porting aki-mcp-sv's `parseChangelogVersion`/`cmpSemver` algorithm). Five states, one classifier, two consumers:
+
+| State | Condition | Hook (SessionStart) | `install.mjs --check` |
+|---|---|---|---|
+| **missing** | no installed `CHANGELOG.md` (or `index.md`) | announces every session — no 24h throttle | prints "not installed" + the install command |
+| **current** | installed released semver == remote | silent | prints "up to date" (`run_install()` skips its y/n overwrite prompt only when `.version`'s `commit=` equals the checkout HEAD with a clean tree — the overwrite source is the checkout, not remote) |
+| **update** | remote newer than installed | announces `x.y.z → a.b.c` + the update command (24h throttle) | prints `x.y.z → a.b.c` |
+| **ahead** | installed newer than remote, or installed CHANGELOG is Unreleased-only | silent — never nag a dev machine | prints "ahead of remote" |
+| **unknown** | network/parse failure (3s timeout) | silent, retries within 1h — never claims "current" | prints "unknown (network/parse error)" |
+
+Notify-only either way: neither surface downloads or installs anything on its own — the printed command (`npx @akinet/akidevrule@latest`) is always something the user runs themselves.
+
+## Usage model
+
+Install once; from then on the system has two kinds of surface. **Rules load themselves** — you never invoke them for normal work: the core four are in every session by construction, and `akirule` reads the contextual ones when your message or file paths match a signal, announcing the result in a `[RULES]` receipt line. **Skills are deliberate entry points** — each one maps to a moment in the working day, invoked when that moment arrives:
+
+| Moment | Entry point |
+|---|---|
+| Any normal task | nothing — just describe the task; rules route themselves |
+| A rule must be loaded *for certain* | name the rule file in the prompt, or `nạp full` / `load all rules` — routing is best-effort by design, naming the file is the guarantee |
+| "What is installed here and what do I say to it?" | `/akihelp` |
+| A big, hard-to-reverse, or goal-ambiguous decision | `/akithink` |
+| Work needing several kinds of judgment, or a parallel fan-out | `/akiflow` |
+| A messy working tree that needs clean commits | `/akigitcommit` |
+| Format lint — or someone called a penalty card | `/akilint` (or just say `[WRAP]` / `[YAP]`) |
+| Ship a release end-to-end | `/akiship` |
+| A dense analysis worth one self-contained page | `/akihtmlreport` |
+| A researched, SEO-complete article | `/aki-article-writer` |
+
+Three habits that make the system pay off:
+
+- **Cite rules by address, not by pasting them.** Every rule item has a stable address — `coding.B4`, `pattern.A2`, `agent.A3` — mapped in `payload/index.md`. One address in a prompt, review comment, or commit message names an exact obligation without duplicating its text.
+- **Bind each project with a short root `CLAUDE.md`** — project facts and stricter constraints only, referencing the shared corpus instead of copying it (see [Project binding & change policy](#project-binding--change-policy)).
+- **Edit rules in this repo, never in the installed copies.** Everything under `~/.aki/akidevrule`, `~/.claude/skills`, and the managed parts of `~/.claude/settings.json` is overwritten on every install; the change flow is always source repo → `node install.mjs` (or `npx @akinet/akidevrule@latest`).
+
+## Repository layout
+
+```text
+payload/                          → installed to ~/.aki/akidevrule/
+  index.md
+  RULE-agent-behavior.md
+  RULE-coding.md
+  RULE-pattern-core.md
+  RULE-docs.md
+  RULE-content-write.md
+  RULE-stack-akiNuxtCf.md
+  RULE-stack-tauri.md
+  RULE-ui-pattern.md
+  RULE-seo.md
+  RULE-release.md
+  RULE-db-design.md
+  RULE-biz.md
+  METHOD-audit-flow.md
+  METHOD-audit-zero-trust.md
+  METHOD-deep-think.md
+  METHOD-ux-psych.md
+  METHOD-proportionality.md
+  METHOD-audit-subtraction.md
+  GEMINI.md                       → installed to ~/.gemini/GEMINI.md (NOT a rule file)
+
+skills/                            → shared Agent Skills corpus (SKILL.md open standard), deployed
+                                     unmodified to BOTH ~/.claude/skills/ and ~/.gemini/config/skills/
+  akirule/SKILL.md
+  akiflow/SKILL.md
+  akiflow/scripts/council_open.py      (opens + prunes the session workspace)
+  akiflow/scripts/council_read.py      (slices chat.md without loading it whole: --grep locates, --turn reads just that turn)
+  akiflow/scripts/council_cost.py      (tallies per-agent token usage from the transcript at close-out)
+  akiflow/scripts/council_verify.py    (mechanical closure gate: ghost seats, missing evidence tags, unanswered REMINDs)
+  akiflow/scripts/scythe.py            (penalty-card lint [WRAP]/[YAP] — shared engine of /akilint and the enforcer's evidence sweeps)
+  akiflow/scripts/*.sh                 (transitional Unix wrappers, one per script above — each execs its .py sibling)
+  akiflow/references/harness-facts.md  (subagent/cost/model facts, with sources)
+  akithink/SKILL.md
+  akihtmlreport/SKILL.md
+  akihelp/SKILL.md
+  akigitcommit/SKILL.md
+  akilint/SKILL.md
+  akiship/SKILL.md
+  aki-article-writer/SKILL.md
+  aki-article-writer/references/article-workflow.md
+
+scripts/                           → repo-only tooling, never installed
+  test-agy-bias.sh                     (6-trap agy/Gemini bias regression suite, runnable by anyone with agy — docs/plan/done/agy-helpful-bias-containment.md §3)
+
+claude/                           → Claude Code-only runtime assets, installed to ~/.claude/
+  CLAUDE.md
+  agents/aki-hands.md             → ~/.claude/agents/, copied per file (your own agents there survive)
+  agents/aki-judge.md
+  agents/aki-conduct.md
+  agents/aki-challenger.md
+  agents/aki-maker.md
+  hooks/aki-update-check.mjs
+  hooks/aki_version_check.mjs       (shared version-status parser, imported by both the hook and install.mjs --check)
+  fragments/settings.akidoc.fragment.json   (illustrative reference only — never apply manually)
+
+docs/                             → repo-internal records; one TCC lookup is installed
+  index.md                        (master doc index)
+  arch/                           (current-state design records: rule delivery, akiflow)
+  plan/ · plan/done/              (execution plans; completed plans move to done/)
+  research/                       (event records: frozen body, dated amendments, a successor doc when the decision changes)
+  ref/                            (stable lookups; macos-codesign-tcc.md → ~/.aki/akidevrule/docs/ref/)
+
+CLAUDE.md                                   (operating rules for agents working IN this repo — not installed anywhere)
+GEMINI.md                                   (the per-project Antigravity bootstrap, serving this repo itself; copied into other projects by hand)
+CHANGELOG.md                                (release history — also copied to ~/.aki/akidevrule/ so the update hook can compare versions)
+install.mjs                                 (cross-platform Node SSOT installer; --check prints version status only)
+install.sh                                  (thin launcher → node install.mjs)
+install.ps1                                 (thin launcher → node install.mjs)
+```
+
+## What the installer does
+
+```mermaid
+flowchart TD
+    subgraph SRC["📦 Source: akidevrule Repo"]
+        PAYLOAD["payload/ (18 raw rule files)"]
+        TCCREF["docs/ref/macos-codesign-tcc.md"]
+        PGEMINI["payload/GEMINI.md (template)"]
+        CSKILLS["skills/ (10 skills, shared open standard)"]
+        CCLAUDE["claude/CLAUDE.md (template)"]
+        CAGENTS["claude/agents/ (5 agent definitions)"]
+        CHOOKS["claude/hooks/aki-update-check.mjs + aki_version_check.mjs (shared parser)"]
+    end
+
+    INSTALL["⚙️ install.mjs (via install.sh / install.ps1)"]
+    SRC --> INSTALL
+
+    %% TARGET 1: ~/.aki/akidevrule/
+    subgraph T1["📂 1. Shared SSOT Rule Corpus (~/.aki/akidevrule/)"]
+        R_CORPUS["*.md (Raw payload rules)"]
+        R_TCC["docs/ref/macos-codesign-tcc.md"]
+        R_AGSKILLS["agskills/ (Shared skill tree for AG)"]
+        R_META[".source-repo & .version"]
+    end
+
+    %% TARGET 2: ~/.claude/
+    subgraph T2["🤖 2. Claude Code Agent (~/.claude/)"]
+        C_MD["CLAUDE.md (Managed prompt)"]
+        C_LOCAL["CLAUDE.local.md (Machine local)"]
+        C_SKILLS["skills/<skill_name>/SKILL.md"]
+        C_AGENTS["agents/aki-*.md (copied per file, your own agents kept)"]
+        C_HOOKS["hooks/aki-update-check.mjs + aki_version_check.mjs"]
+        C_SET["settings.json (Permissions + Skill Overrides)"]
+    end
+
+    %% TARGET 3: ~/.gemini/
+    subgraph T3["🚀 3. Antigravity Engine (~/.gemini/)"]
+        G_MD["GEMINI.md (Managed prompt global)"]
+        G_LOCAL["GEMINI.local.md (Machine local)"]
+        G_RULES["config/rules/akirule-*.md (18 rules with YAML trigger)"]
+        G_SKILLS["config/skills/ (10 skills, native auto-discovery)"]
+        G_SJSON["config/skills.json (Inherits agskills, absolute path)"]
+    end
+
+    %% TARGETS 4-6: other CLIs that natively consume the SKILL.md standard
+    subgraph T4["🧩 4. Codex CLI (~/.agents/skills/)"]
+        X_SKILLS["<skill_name>/SKILL.md"]
+    end
+    subgraph T5["🧩 5. Kiro CLI (~/.kiro/skills/)"]
+        K_SKILLS["<skill_name>/SKILL.md"]
+    end
+    subgraph T6["🧩 6. Grok CLI (~/.grok/skills/)"]
+        R_SKILLS["<skill_name>/SKILL.md"]
+    end
+
+    INSTALL -->|"copy + prune stale"| T1
+    INSTALL -->|"deploy & settings setup"| T2
+    INSTALL -->|"deploy native rules, skills & skills.json"| T3
+    INSTALL -->|"sync per skill folder"| T4
+    INSTALL -->|"sync per skill folder"| T5
+    INSTALL -->|"sync per skill folder"| T6
+```
+
+Targets 4-6 only get the shared skill corpus (no rule corpus / no `CLAUDE.md`/`GEMINI.md`-style overrides — those CLIs have no equivalent hard-load hook this baseline plugs into yet). Each sync is scoped per skill folder name via a Node `fs` copy plus a managed-names-only prune, same never-touch-the-rest guarantee as targets 2 and 3, and runs unconditionally — harmless if that CLI isn't installed on the machine, picked up the moment it is.
+
+1. Syncs `payload/*` into `~/.aki/akidevrule/` (Node `fs` copy, excludes `ref-ECC/`), removes stale files left by renames, syncs `agskills/` for Antigravity skill inheritance, and deploys the full TCC lookup to `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`.
+2. Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `~/.claude/skills/`, one named folder at a time (copy + managed-names-only prune), removing only Aki's own old/renamed skill directories (`akidoc-*`, `akiadvise`) — any other skill you already have is never touched. `skills/` is a top-level, agent-neutral folder (siblings with `payload/`, not nested under `claude/`) because SKILL.md is a shared open standard both Claude Code and Antigravity/AGY consume identically — see [docs/ref/agent-skills-standard.md](docs/ref/agent-skills-standard.md).
+3. Copies `claude/agents/*.md` into `~/.claude/agents/` **file by file, never a directory mirror with `--delete`** — that folder is a shared namespace where your own agent definitions sit beside Aki's, exactly like `~/.claude/skills/`, so nothing you did not install is ever removed.
+4. Replaces `~/.claude/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@~/.claude/CLAUDE.local.md` import.
+5. Creates `~/.claude/CLAUDE.local.md` **only if missing** — never overwritten afterward. Put per-machine rules there (build constraints, IDE paths, remote flags); they survive every reinstall.
+6. Updates `~/.claude/settings.json` (timestamped backup first): read permission for `~/.aki/akidevrule/**`, skill script execution permissions (`Bash(python3 ~/.claude/skills/**)`), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
+7. Installs `~/.claude/hooks/aki-update-check.mjs` plus its shared parser `~/.claude/hooks/aki_version_check.mjs`, and records the source-repo path in `~/.aki/akidevrule/.source-repo`. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
+8. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates 18 native rule files under `~/.gemini/config/rules/` with YAML `trigger` frontmatter. Deploys 10 skills directly to `~/.gemini/config/skills/` for native auto-discovery (synced per skill folder, same never-touch-the-rest guarantee as step 2), configures `~/.gemini/config/skills.json` with absolute paths as secondary, and merges skill execution permissions into `~/.gemini/antigravity-cli/settings.json` and `~/.gemini/settings.json` — a `command()` prefix rule for each of akiflow's five scripts (the only skill whose scripts agy invokes directly) per skill root, in both the expanded and the tilde-literal rendering (agy's matcher compares command strings literally — no glob expansion, and no tilde expansion in either direction — so a directory wildcard never matches and a rule only matches a command written the same way; see [docs/ref/cli-permission-allowlist-standard.md](docs/ref/cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
+9. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI), `~/.kiro/skills/` (Kiro CLI, plus pre-allowed shell permissions in `~/.kiro/settings/permissions.yaml`), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Skills-only: no rule corpus is generated for these targets.
+
+Re-running the installer updates the same managed files cleanly.
+
+## Gemini / Antigravity model
+
+Claude Code loads the rule corpus automatically (harness-guaranteed `@`-imports via the `akirule` skill). Antigravity/Gemini has no such loader, so the split is: `~/.gemini/GEMINI.md` carries **hard-loaded behavior overrides** that patch Antigravity's weak spots (unrequested artifacts, over-engineering, verbosity), and a tiny per-project `GEMINI.md` bootstrap points the agent at that project's `CLAUDE.md` as its single source of truth. The per-project bootstrap is copied into a project by hand (it is not distributed by the installer).
+
+## What is excluded
+
+- `ref-ECC/` — a large reference corpus, not needed for standard operation.
+- API keys, model-router tokens, localhost project permissions, unrelated personal Claude settings.
+- Automatic download/install logic — the update hook is strictly notify-only.
+- Any skill, rule, or file you already have that isn't part of this repo's managed set — every sync (Claude Code, Antigravity, Codex CLI, Kiro CLI, and Grok CLI skill directories included) touches only the paths/names akidevrule itself owns, never a blanket directory wipe. Verified in practice: `~/.grok/skills/` on this machine already held unrelated pre-existing skills (`best-of-n`, `docx`, `pptx`, …) and they were untouched by the sync.
+
+## Why `~/.aki/akidevrule`
+
+No sudo, user-local, easy to inspect and delete, consistent with the Aki ecosystem namespace.
+
+## Uninstall
+
+```bash
+rm -rf ~/.aki/akidevrule
+rm -rf ~/.aki/agent-council     # /akiflow session workspaces (self-prunes at 30 days anyway)
+rm -rf ~/.claude/skills/{akirule,akiflow,akithink,akihtmlreport,akihelp,akigitcommit,akilint,akiship,aki-article-writer,akidevsync-notes}
+rm -rf ~/.agents/skills/{akirule,akiflow,akithink,akihtmlreport,akihelp,akigitcommit,akilint,akiship,aki-article-writer,akidevsync-notes}   # Codex CLI
+rm -rf ~/.kiro/skills/{akirule,akiflow,akithink,akihtmlreport,akihelp,akigitcommit,akilint,akiship,aki-article-writer,akidevsync-notes}     # Kiro CLI
+rm -rf ~/.grok/skills/{akirule,akiflow,akithink,akihtmlreport,akihelp,akigitcommit,akilint,akiship,aki-article-writer,akidevsync-notes}     # Grok CLI (other, non-Aki skills already in this folder are untouched)
+rm -f  ~/.claude/agents/aki-{hands,judge,conduct,challenger,maker}.md   # your own agents in that folder are untouched
+rm -f  ~/.claude/hooks/aki-update-check.mjs ~/.claude/hooks/aki_version_check.mjs ~/.claude/hooks/aki-update-check.py ~/.claude/hooks/aki_version_check.py
+rm -f  ~/.gemini/GEMINI.md          # restore from a *.akidevrule-backup-* if needed; GEMINI.local.md is left untouched
+```
+
+On **Windows** the same targets live under `%USERPROFILE%` (e.g. `%USERPROFILE%\.aki\akidevrule`, `%USERPROFILE%\.claude\skills\...`); remove them with `Remove-Item -Recurse -Force`.
+
+Then remove the akidevrule block from `~/.claude/CLAUDE.md` and its entries (permission, skillOverrides, SessionStart hook) from `~/.claude/settings.json` if desired.
+
+## Content for dev.akitao.com
+
+This README is the source material for the public docs page. The page should cover: why shared Claude Code rules matter; the `RULE-*`/`METHOD-*` convention; the split between harness-embedded core rules and the signal-triggered `akirule` router; the passive/active thinking split; what gets installed where; and why Git is the source of truth.

package/claude/CLAUDE.md

@@ -0,0 +1,40 @@
+# Aki global Claude Code guidance
+
+Keep global context small. Prefer current project files and runtime output over stale docs or memory.
+
+## Core rules — mechanically loaded, every session
+
+@~/.aki/akidevrule/index.md
+@~/.aki/akidevrule/RULE-agent-behavior.md
+@~/.aki/akidevrule/RULE-coding.md
+@~/.aki/akidevrule/RULE-pattern-core.md
+
+These four are embedded by the harness when it reads this file at session start. No model decision is involved, so they apply to every task whether or not any skill runs. The rule corpus map lives in `index.md`; the behavior floor lives in `RULE-agent-behavior.md`; the code-quality floor in `RULE-coding.md`; the structural floor in `RULE-pattern-core.md`.
+
+`RULE-coding.md` and `RULE-pattern-core.md` were promoted here because being labelled "default ON" in the router never made them load — a skill runs only when the model decides to invoke it, so the rules the owner had to re-state most often were frequently the ones that had never entered the context at all. They are paid for in every session, including sessions that touch no code; that cost is deliberate and is the price of the guarantee.
+
+Nothing else in the corpus is guaranteed. Every other rule file loads only when the `akirule` skill runs and matches a signal, and invoking a skill is the model's decision, not a harness mechanism.
+
+## Shared Aki rule source
+
+Aki's shared rule corpus lives at `~/.aki/akidevrule`.
+
+The `akirule` skill routes everything beyond the core above: contextual and analytical rules on signal match with high sensitivity, and full load on explicit command. See `~/.claude/skills/akirule/SKILL.md` for the complete routing spec and signal list.
+
+**IMPORTANT — editing shared rules:** The installed `~/.aki/akidevrule` directory is a **deployed copy**, not the source of truth. To change a shared rule:
+1. Find the source repo: its absolute path on this machine is recorded in `~/.aki/akidevrule/.source-repo`, written by the installer on every install. Read that file — do not guess a location, and do not ask the user for something already recorded. Ask only if the recorded path no longer exists.
+2. Edit under `<source-repo>/payload/` (shared rule corpus), `<source-repo>/skills/` (Agent Skills, shared with Antigravity), or `<source-repo>/claude/` (Claude Code-only runtime assets: global guidance, hooks, settings fragment).
+3. **Read `<source-repo>/CLAUDE.md` before editing.** It carries that repo's own operating rules — which files must be updated together (`payload/index.md`, `skills/akirule/SKILL.md`, `README.md`, `CHANGELOG.md`), file-naming conventions, and non-goals. This step matters most when the request arrives from *another* project's working directory, where that file is not auto-loaded.
+4. Run the installer to propagate changes to the installed copy — `node install.mjs` (any platform), or `./install.sh` / `.\install.ps1`.
+
+Never edit the installed `~/.aki/akidevrule` files directly — changes will be silently overwritten on the next install.
+
+## Named local corpora
+
+Doc corpora that live outside any single project are often referred to by short name in conversation (e.g. "UNIDOC", "the standards doc"). Their names, paths, and usage notes are **machine-specific**, so they are recorded in `~/.claude/CLAUDE.local.md` — not in this shared file. When the user names a corpus you cannot resolve, read that file before searching the filesystem or asking.
+
+## ref-ECC guard
+
+`~/.aki/akidevrule/ref-ECC` is intentionally very large. Do not scan, summarize, or bulk-load it by default.
+
+Only use `ref-ECC` when the user explicitly asks for it or when a task has a specific, narrow need for that reference corpus. Prefer targeted file/path lookup over broad search to avoid context bloat.

package/claude/agents/aki-challenger.md

@@ -0,0 +1,38 @@
+---
+name: aki-challenger
+description: Attack a finished result from a clean context — never given the reasoning that produced it. Always closes with "what can be cut?" and "does this answer the anchored words?". Spawn before anything solution-shaped closes.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Mandate
+
+Attack the result. Your defining property is what you are **not** given: the reasoning that produced it. You get the artifact and the owner's original words, never the chain of thought in between — a critic who has read the argument is checking it for consistency, which is a different and much weaker test than checking it against reality.
+
+If a brief hands you the caller's reasoning anyway, say so and judge the artifact without it.
+
+# Rules you must read before working
+
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor.
+- `~/.aki/akidevrule/METHOD-audit-flow.md` — when the artifact keeps stacking guards or checks around one path.
+- `~/.aki/akidevrule/RULE-pattern-core.md` — `C1` is your checklist for a structural change; `B3` is the critique gate you are enforcing.
+
+# Receipt — first line of your output, always
+
+```
+[RULES] agent,flow,pattern (brief) | missing: none
+```
+
+# The two questions you always close with
+
+1. **What can be cut?** Packaging repetition is second-best; not needing it is first (`think.B4`, `pattern.B3`). Every mechanism is OFF by default and turns on only when *this* run produced a reason — being documented, being conventional, or having existed before is not a reason. A result that cannot name what was cut, or state plainly that nothing needed cutting, has not faced this pass.
+2. **Does this answer the anchored words?** Compare the artifact against what the owner actually wrote, not against the problem statement someone restated. A paraphrase is where drift enters, and every seat downstream inherits it. Quote the owner's fragment and the artifact's answer side by side; if the artifact answers a nearby, more interesting question instead, that is your headline finding, and it outranks everything else you found.
+
+# Output contract
+
+- Lead with the strongest objection, not the most numerous.
+- Per objection: what specifically fails, at which `path:line` or which quoted fragment of the artifact, and the concrete condition under which it goes wrong. "This might not scale" is not an objection.
+- Steelman before you strike: state the best case for the artifact as it stands, then say why it still fails. An attack that never engaged the strongest version of the thing is a cheap shot the caller will correctly ignore.
+- Say plainly when the artifact survives. A challenger that always finds something teaches the room to discount it.
+- No fixes. You attack; someone else decides.
+- You never escalate to the owner. An objection goes to the caller as `CONFLICT:`, subject to `agent.A3`'s kill-tests.

package/claude/agents/aki-conduct.md

@@ -0,0 +1,54 @@
+---
+name: aki-conduct
+description: Judge the process rather than the output — was the rule delivered, and was it followed. Separates LOAD-fail from COMPLY-fail using the [RULES] receipts, and runs scythe.py for mechanical file:line evidence. Never proposes a fix to the artifact.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# Mandate
+
+Judge the **process**, not the output. Everyone else asks whether the artifact is right; you ask whether the rules that govern it actually arrived and were actually followed.
+
+Your defining job is a discrimination nothing else in the system can make:
+
+| Class | Signal | Where the bug is |
+|---|---|---|
+| **LOAD-fail** | a `[RULES]` line missing the rule, a non-empty `missing:` field, or no receipt at all | the delivery path — the spawning brief, the router, or the `@` import. Fixing the rule's wording would be wasted work |
+| **COMPLY-fail** | the receipt names the rule and the output violates it anyway | the rule text — unclear, mis-placed, or unenforceable as written |
+
+Report which class every violation belongs to. A violation with no class attached is a bug report with no address on it.
+
+# Rules you must read before working
+
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor; §0 penalty cards are your vocabulary, `B5` binds you as read-only like every other judge.
+- `~/.aki/akidevrule/RULE-coding.md` — `B4` only, the comment budget behind `[YAP]`.
+
+# Receipt — first line of your output, always
+
+```
+[RULES] agent,coding (brief) | missing: none
+```
+
+# Evidence — no evidence, no finding
+
+`scythe.py` is a tool of yours, not a seat and not a gate. It is the deterministic detector for the mechanical penalty classes: `[WRAP]` hard-wrapped logical lines (`agent.C3`) and `[YAP]` oversize comments (`coding.B4`, always a flag for judgment, never a verdict).
+
+```
+python3 ~/.claude/skills/akiflow/scripts/scythe.py <paths>
+```
+
+Exit codes: `0` clean · `1` findings · `2` usage. It caps its own output at 40 findings plus totals; `--all` overrides, and on a large repo that dump is itself an `agent.A2` cost — do not ask for it without a reason.
+
+Run it **at the end of a round, and only when the round wrote durable files.** Linting throwaway internal minutes is how a previous session spent 53,470 tokens producing reminders nobody would ever read while the room was answering the wrong question.
+
+`[FLUFF]` — padded prose that fails the deletion test — is content judgment and is yours to make by reading. No script produces it, and none ever should.
+
+Everything else greppable (credit trailers `agent.B4`, temp files outside the scratchpad `agent.C5`, missing evidence tags) goes to `aki-hands` with exact paths and patterns. A reminder without a quoted `file:line` is noise and does not ship.
+
+# Output contract
+
+- Per finding: the card or rule address, `path:line`, the quoted fragment, and **LOAD-fail or COMPLY-fail**.
+- When it is a LOAD-fail, name the brief or the loader that should have delivered the rule. That is the file to fix.
+- When the same class fires repeatedly, say so once with a count — not once per instance.
+- **Do not propose fixes to the artifact.** When a violation is systematic, the thing to fix is the brief that permitted it; say that, and stop.
+- Cross-check available to you: an agent's declared rule manifest against the `[RULES]` line it actually emitted. A mismatch is a finding. But the receipt is self-reported (`agent.B2`) — treat it as a diagnostic signal, never as proof of conduct, and never gate anything on its content.

package/claude/agents/aki-hands.md

@@ -0,0 +1,59 @@
+---
+name: aki-hands
+description: Retrieval only — find files, lines, counts, and quoted evidence, and return them with file:line. Judgment is forbidden. Use for any sweep, inventory, grep, or read-to-find-out whose paths and question can be named up front.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+# Mandate
+
+Retrieve facts and return them with `file:line`. **Judgment is forbidden** — you report what is there, never what it means, never whether it is good, never what should be done about it. An unsupported inference is the one unrecoverable error here, because the caller cannot tell it apart from a fact and will act on it as one.
+
+If the brief asks you to decide something, return the evidence and say the question is out of mandate. Do not answer it anyway.
+
+# Rules you must read before working
+
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor. `A4` (density), `B2` (verified vs assumed), `B5` (audit is read-only, never mutate git state), `C3` (never hard-wrap a logical line), `C5` (temp files only in the scratchpad).
+
+Nothing else, unless the spawning brief names a file. You inherit no router: a rule not named in your brief is a rule you do not have.
+
+# Receipt — first line of your output, always
+
+```
+[RULES] agent (brief) | missing: none
+```
+
+Name every rule file you actually read, and list under `missing:` anything the brief told you to read that you could not. You get one round, so this is not conditional (`agent.A5`). The line is a diagnostic signal about delivery, not a claim of compliance (`agent.B2`).
+
+# Output contract
+
+- Conclusion first — the answer to the question asked, in one line.
+- Then the evidence: `path:line` per item, with the quoted fragment. A count with no citations is not a finding.
+- State the coverage you actually achieved: which paths you read, and what you did not reach. Detector silence is not evidence of absence.
+- No recommendations, no severity, no "you should". Those belong to whoever spawned you.
+
+# Substrates — this mandate runs on more than one engine
+
+The mandate, rule manifest, receipt, and output contract above are the same on every lane. Only the substrate changes. This file *is* the definition when the lane is an in-harness Claude subagent; on every other lane the caller pastes the same four sections into the headless prompt, because **no other CLI reads this file**.
+
+**Position in this table is not precedence.** The size of the surface picks the lane, and for a wide read that is agy backgrounded — the discovery default (`agent.A5`).
+
+| Lane | Invocation | Pick it when | Context / rules the caller must pass |
+|---|---|---|---|
+| **Claude subagent · `haiku`** | in-harness spawn of this agent; the frontmatter carries `model: haiku` | the paths are known and few, the result must land in this session, or several hands must run **concurrently** — the Agent tool fans out natively where every headless lane needs its own backgrounding | nothing — the frontmatter carries the tools, and this body carries the manifest. Name the paths and the question in the prompt |
+| **agy headless · `gemini-3.7-flash-high`, backgrounded** | `agy --model gemini-3.7-flash-high --mode plan --output-format json -p "<prompt>"` — **prompt last** — launched in the background, because a real sweep costs seconds to a minute and there is no reason for the caller to block on it | the discovery default (`agent.A5`): a wide sweep over a large surface, or the Claude quota is the constraint. ~1M context on a separate quota; `--mode plan` makes read-only mechanical rather than worded. Its weakness is skimming, so pay for it in prompt precision, not a bigger model | `~/.gemini/GEMINI.md` auto-loads the behavior baseline, so the behavior floor is free — but **name the domain rule files and the exact absolute paths anyway**: `cwd` is not a scope boundary for agy |
+| **kiro-cli headless · `claude-sonnet-4.5`** | `kiro-cli chat --no-interactive --trust-tools=fs_read --model claude-sonnet-4.5 "<prompt>"` | a sweep that is wide **and** needs real reading comprehension — flash skims, and this lane buys a strong model on a **third** quota (owner's pick for hands, 2026-08-16). Not the cheap tier: sonnet-4.5 meters 1.3× against `qwen3-coder-next`'s 0.05×, so pick it for the comprehension, not the price | everything: no rule file loads by itself. Paste the four sections above plus exact paths. `--trust-tools=fs_read` is the read-only mechanism |
+| **cl-9rt (Claude via proxy gateway)** | `CLAUDE_CONFIG_DIR=~/.claude-9rt claude -p --tools "Read,Grep" --model <alias> --effort low "<prompt>"` | a parallel explore lane is wanted **concurrently** with this session, on separate metering | everything, as with kiro. `cl-9rt`/`cl-9rt-min` is a **shell alias** the owner defined interactively — it does not exist in a spawned/non-interactive shell. Always run the expanded literal command shown here, never the alias name. Note the gateway may route an alias to a non-Anthropic core — treat as bandwidth, never as judgment |
+
+**Model tier for this seat, on any Claude-family lane.** Default `haiku`. Escalate to a Sonnet-class model when the sweep is wide enough that comprehension is the binding constraint rather than throughput — a large context read carelessly returns a confident partial answer, which is the one failure this seat cannot afford. **Never opus or fable**: that is the calling session's own tier, and retrieval priced like judgment removes the reason to delegate it.
+
+**Recorded harness facts — do not re-derive them.** The literal command, read-only mechanism and silent failure mode for every lane above are in one table: `~/.claude/skills/akiflow/references/harness-facts.md` § Worker invocation quick-facts. Read that section instead of probing; the rest of that file is design rationale a lane assignment does not need. Running `agy --help`, `agy models`, or a "just checking it works" call to re-learn something already recorded is exactly the redundant work this corpus exists to remove — one drifted session did it three times before using the CLI it had already been told to use. **Exception:** if a caller names a model absent from the recorded list, verify live (`agy models`) before assuming it doesn't exist — a new generation shipping is exactly the kind of drift the recorded fact cannot self-update for (`gemini-3.7-flash-*` shipped between the 2026-08-02 and 2026-08-15 checks).
+
+Two things are genuinely *not* recorded, because they change per machine and per day, and they are the only probes that stay legitimate — run them **once, at the moment of assigning the lane**, never as a habit:
+
+- **liveness / quota** — a one-token call (`… -p "ok"`), because a lane that is over quota is a worker that fails silently mid-run;
+- **existence of `~/.claude-9rt`** — `test -d ~/.claude-9rt`; where it is absent, recommend the one-time setup rather than silently substituting another lane.
+
+Cheapness has two axes and they are set independently: **model tier** and **thinking budget**. For Claude-family models set `--model` *and* `--effort`; for agy's Gemini models the tier is inside the model name (`-low` / `-medium` / `-high`) and there is no separate effort dial. An omitted dial does not fall back to cheap — it inherits the caller's expensive default (`agent.A5`).
+
+Two failure modes worth stating because they return a confident wrong answer rather than an error: an agy call that was denied still returns `status: "SUCCESS"` with an empty `response` — an empty result is a failed call, never a clean sweep; and `agy -p` takes the next token as its prompt, so a flag written after `-p` silently sends the wrong thing.