@akinet/akidevrule 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [3.8.0] - 2026-10-20
+
+### Added
+- **The installer offers an accuracy-first config for rtk, opt-in: a terminal prompt defaulting to no, `--rtk` to say yes without one, and one summary line either way** (`install.mjs`, `README.md` § Optional: rtk, `coding.B3` one bullet). Evidence: on the dev box rtk 0.50.0, hooked into Claude Code's Bash tool, merged two `ls` listings and cut `jq` lines at 120 characters while an agent was reading them as evidence; the research (`docs/research/rtk-output-loss-oct19.md`) measured the rest raw against filtered — `ls` drops names ending in `.` with no marker, `grep` 211 of 480 lines, `git diff` 610 of 7,541, `git log` 10 commits with no "more" line — and found the recall hints followed 3 times in 480 elisions; upstream has no lossless mode (#1313 open since 2026-04) and counts dropped bytes as savings. Root cause: rtk's built-in Rust filters run before any `filters.toml`, so the only lossless control is `[hooks] exclude_commands` in its `config.toml`, which nobody sets by hand. Mechanism: `rtkDetect()` runs `rtk config` and takes the path from its `Config:` line (macOS keeps the file under `~/Library/Application Support/rtk/`, Linux under `~/.config/rtk/`, verified on both), the question is asked before "Installing..." so the run has no mid-install prompt, and `rtkConfigure()` makes the smallest change — no file → write, no `[hooks]` → append, `[hooks]` without the key → insert it, the user's own `exclude_commands` → keep and list what is missing, a `# akidevrule: rtk off` line → skip; the file is backed up like `settings.json` and the backup dropped on success. The `coding.B3` bullet covers what stays compressed: output carrying an elision marker is a sample, rerun raw before a count, quote, failure list or absence claim is taken from it. Rejected: writing the config on every install (shared third-party config and the repo's Non-goals on personal settings — the owner's ruling is ask, default no); a `[retriever]` table in the managed content (the Mac runs rtk 0.47.0 with no sqlite store; left as a README line for 0.50+); lossless `filters.toml` overrides (unreachable for the Rust filters, and any edit silently cancels `rtk trust`); recommending against rtk (the noise class saves real context at no cost to evidence). Verified: sandbox-`HOME` fixture with a fake `rtk` on `PATH` (absent → hint; present without `--rtk` → untouched; `--rtk` → written; re-run → byte-identical, no backup left; other table → appended; `[hooks]` without key → inserted; user list → kept with missing names; opt-out → skipped), then real rtk 0.50.0 reading the generated file through `XDG_CONFIG_HOME` with the hook JSON: `ls`, `grep -rn`, `git -C … diff`, `jq`, `cd … && ls | head` pass raw and `git status` is still rewritten; the same cases run in `install-smoke.yml` on all three OSes; the exclusion is honoured from rtk 0.47.0 (changelog, and the same hook test on the Mac) through 1.0.1 (the dev box upgraded and re-tested the same day: `sh -c 'ls -la'` still raw, `RTK_DISABLED=1` still honoured), with the Windows path (`%APPDATA%\rtk`) taken from rtk's `user_dirs.rs` rather than observed. Updated together: `README.md` (TOC, install step 7, § Optional: rtk, uninstall), `docs/arch/rule-delivery-architecture.md` installer paragraph, `docs/arch/corpus-map.md` "what a passing check proves" lens, `docs/index.md`, `docs/plan/rtk-accuracy-first.md` (executed, P4 scheduled), `docs/plan/full-file-reads.md` F5/V3, the research doc's `## Amendments` (macOS path, Mac version).
+
+### Changed
+- **`agent.B1` names pull requests, deploys and tags beside commits and pushes, and adds "the request is the whole scope": a step the request did not name — the PR after a commit, the push after a fix, the deploy after a build, the usual next step of a workflow — is not taken because it is customary or looks helpful; finish what was named, then stop and report (`A3`).** Evidence: on 2026-10-08 the owner asked an agent for one added comment line in a repository and the agent also opened a pull request (PR #1) nobody had asked for; the owner's correction was that his instruction outranks both harness instructions and the model's trained habits. Root cause: `B1` listed commits and pushes but not PRs or deploys, and nothing said that a workflow's customary next step is still an unrequested step — `B7` covered harness text only, so a habit learned in training read as neither an instruction nor a violation. Mechanism: one widened bullet and one new bullet in `B1`, plus one sentence in `B6` ranking the model's trained defaults (the workflow it usually follows, the next step it usually takes, a convention from other projects) below every instruction, since they are not instructions at all. Rejected: a new `B8` section (restates `B1`/`A3`; the gap was two missing nouns and one missing concept); a `B7` table row (`B7` quotes harness text, and a trained habit has no quotable source). Updated together: this entry only; no address, route or signal changed.
+- **`agent.C5` reduced to two rules plus the existing `scripts/` line: no file the task can do without and none outside the scratchpad, one session folder only where the harness gives none; `agent.B1`'s "what you create, you remove" now covers anything the agent or a command it ran created outside the harness scratchpad and says nothing about the scratchpad itself.** Evidence: across 516 of the owner's Claude Code transcripts (2026-10-20), 528 `rm` commands in 131 transcripts mostly deleted the agent's own throwaway files (scratchpad 288, `/tmp` 97), and a machine-local command gate spent 143 of its 212 permission prompts on `rm -rf` confirmations that stalled unattended runs; the owner's standing order (one session scratch folder, no `.bak` copies or `verify`/`shots` folders) had no home in the corpus. Root cause: the corpus itself ordered the deletion — `B1` listed temp files among what the agent must remove and the previous `C5` said to delete the session folder before reporting — while the harness already discards its scratchpad, so every run paid a create-then-`rm` cycle and, under a command gate, a prompt. Mechanism: subtraction first — `B1` trades its file-type list for a scope — anything the agent or a command it ran created outside the harness scratchpad — so a throwaway written in the project tree, `/tmp` or the home directory, or a tool's own output (`npm pack`'s `.tgz`, a screenshot), is still removed by the agent while the scratchpad is left to the harness, `C5` shrinks from six bullets to two rules plus the `scripts/` line, and the scratchpad's lifetime is the harness's default; the prompt itself was removed where it is raised, by teaching the machine-local gate that an `rm` confined to temp locations is not a danger. Rejected: a new hook that denies scratchpad `rm` (a second gate layered on the one that prompts — the fix belongs in the gate that asks); dropping files from `B1` entirely (prevention only: a throwaway written outside the scratchpad in breach of `C5` then had no removal duty, and `test.B3`, which applies `B1` to a suite's temp dirs, outgrew its own root); a closing `git status` step or an end-of-session untracked-file hook (one more ritual or layer, blind to ignored files, and a hook cannot tell the agent's files from the owner's work in progress — reopen only if `/akiopen` keeps finding untracked side copies); a fixed absolute scratch path (each harness and machine differs); a rule forbidding hand-cleaning of the scratchpad (a layer over the harness default; once the command gate stopped prompting on temp `rm`, the cleanup costs one call and no prompt). Updated together: `claude/agents/aki-maker.md` and `claude/agents/aki-hands.md` (`C5` gloss), `docs/research/agent-churn-temp-rerun-oct20.md`.
+- **`coding.B3`: one run per change state.** Evidence: in the same 516 transcripts, 507 of 2,522 verification runs (20%) repeated the same check type with no edit by any tool in between; 396 of those (78%) followed a run whose output had been piped through `grep`/`head`/`tail`, a subagent ran in between in only 8 (1%), and a byte-identical rerun happened once — the waste is output thrown away by a filter, not distrust of a worker. Root cause: `B3` said which check fits which moment but nothing about keeping a run's output, so the filter discarded evidence and the only way back was another run. Mechanism: a long check runs once with its output kept in the scratchpad and later questions grep that file; a rerun needs an intervening change or a written reason (flakiness probe, baseline, raw output after an elision marker) — the one case `agent.C5` names for writing a file. Rejected: a transcript lint (a count cannot tell a legitimate flake probe from waste); banning output filters (they keep the context small). Updated together: `docs/research/agent-churn-temp-rerun-oct20.md`.
+- **The path → rule map is one data file, `payload/route-map.json` (installed to `~/.aki/akidevrule/route-map.json`), read by `aki-route-guard.mjs`, `scripts/second_hop_audit.py` and `skills/akiflow/scripts/suite_lint.py` instead of three copies in code.** Evidence: the map lived only as code in the hook (`CODE_EXT`, `FRONTEND_EXT`, `TEST_NAME`, `TEST_DIR`, `routesFor`, `isUngatedPath`, `isNuxtProject`, nothing exported), and the audit's hand copy had already drifted from it — no `ui` for `.tsx`/`.jsx`/`.svelte`, `docs` only under `docs/`, no `content` route, `stack` on every `.vue` with no Nuxt condition, no `stack` for `.ts`, a shorter code-extension list — so the read rates the audit printed described a different set of edits than the gate denied; `suite_lint.py` expanded a directory with a third copy of the test signature; AkiMCP's rule gate must push the same routed rules to web AIs that have no hook and knows only `CLAUDE.md`/`AGENTS.md`. Root cause: the mapping was written as logic in the one consumer that existed first, so each later consumer copied it. Mechanism: one JSON file, `routes` (each with `rules` and any of `ext`, `name`, `nameRe`, `dirRe` + `dirSkipExt`, plus `projectHas`, file names of which any one must exist at the project root) and `ungated` (path segments, prefixes, directory names); regexes use only syntax JavaScript and Python read alike; every directory route matches the project-relative path; the hook fails open when the file is missing, the two scripts exit 2 with a message. The harness-config-dir and outside-project checks stay in the hook, a deviation from the plan's D2, which listed them as data flags: only the hook needs them, and AkiMCP's gate uses the segment/prefix/dir list alone. Rejected: exporting `routesFor` as a module (Python and AkiMCP cannot import it, and AkiMCP would execute code from `~/.claude/hooks/`, which exists only where Claude Code assets are installed); AkiMCP keeping its own copy (the audit's copy already drifted); leaving the audit on its copy (it keeps measuring something other than the gate). Verified: 17 sample paths plus 2 Nuxt cases (test files, `src/x.js`, `docs/spec/a.md`, `a.tsx`, `pages/a.vue` with and without `nuxt.config.ts`, `src-tauri/x.json`, `locales/vi.json`, `~/.aki/x.md`, `/tmp/x.js`, a path outside `cwd`) gave byte-identical deny lists before and after; with the map file removed every edit is allowed. The audit's numbers change once and are not comparable across the switch: on the Mac's transcripts, in the "before" era, sessions routed to `docs` went 94 → 128 (any `.md` now, not only under `docs/`), `stack` 41 → 40, `tauri` 6 → 8, and a `content` route appears. Updated together: `payload/route-map.json` (new), `claude/hooks/aki-route-guard.mjs`, `scripts/second_hop_audit.py`, `skills/akiflow/scripts/suite_lint.py`, `skills/akirule/SKILL.md` (delivery bullet names the file), `README.md` (gate paragraph, payload layout, hook list), `docs/arch/rule-delivery-architecture.md` (gate section), `docs/index.md`; the shipping assertion for the file in `.github/workflows/install-smoke.yml`. Plan: `docs/plan/done/route-map-json.md`; the file ships at `~/.aki/akidevrule/route-map.json` and `aki-mcp-sv` picks it up through its own plan's dependency section.
+- **A rule file counts as read only when read whole: the route gate stops counting `limit`/`offset`/`head`/`sed`/`tail` reads, and on Claude Code a partial `Read` of a rule file is rewritten into a whole one (`agent.B7` gains a row for the `Read` tool description).** Evidence: on 2026-10-19 a Sonnet worker briefed to read `RULE-agent-behavior.md` and `skills/akirule/SKILL.md` called `Read` with `limit: 40` and `limit: 30`, then opened its reply `[RULES] agent,akirule,docs (brief)`, naming two files it had seen the first fifth of; baseline on the Mac (2026-10-20, `second_hop_audit.py`): main sessions 44 of 1,164 rule reads partial (3.8%), subagents 34 of 440 (7.7%); on the Linux dev box 64 of 1,345 (4.8%). Root cause: Claude Code's `Read` description says "When you already know which part of the file you need, only read that part" and `agent.B7` had no row for it; the gate matched a `Read` by file name alone, so a partial read marked the file read, and the audit counted the same way and could not see the gap; a read-only worker never meets an edit gate. Mechanism: F1 — `scanTranscript` counts a `Read` only when `offset` is absent or ≤ 1 and `limit` is absent or ≥ the file's line count, `cat`/`bat`/`less` in Bash/Shell keep counting, `head`/`sed`/`tail` never do, and the deny reason adds "A Read with limit/offset or a head/sed/tail print does not count — read the whole file." when only partial reads were found; F2 — the hook also runs on matcher `Read` (registered by `install.mjs`) and rewrites a partial `Read` of a rule file (`~/.aki/akidevrule/*.md` or a `SKILL.md` under `~/.claude/skills/`, judged on the resolved path, at most 60,000 bytes) into a whole `Read` through `PreToolUse` `updatedInput` with `permissionDecision: allow`, so there is no extra round trip; above 60,000 bytes the `Read` tool's ~25k-token cap makes a partial read the only possible one, so it passes; F3 — the `agent.B7` row, covering a file a brief names "in full" that is not a rule file, and harnesses without the hook; F6 — `second_hop_audit.py` prints `rule reads: N (partial K, P%)` for main and subagent and no longer counts a partial read as a read. F5 unchanged: Bash `cat` stays counted. F4 (receipts carrying line count and last line, `agent.A5`) is deferred: evidence of partial reads exists only on Claude Code, where F2 now removes them mechanically; reopen on a partial rule read observed in a worker on a harness without the hook (agy, Codex, Kiro) or a receipt naming a file the worker did not read whole. Rejected: deny instead of widen (a round trip per partial read, and a model may retry partially); denying `limit`/`offset` on every `Read` (partial reads of large code files are correct); wording only (the second hop was re-worded twice, 2026-08-06 and 2026-09-25, without moving the read rate); F4 now (no evidence outside Claude Code). Hardened after an adversarial review the same day: `permissionDecision: allow` skips the permission prompt, so widening applies only to the corpus's own files after `realpath` (a `../` path or a `SKILL.md` elsewhere passes untouched); the transcript records the model's original `Read` input, not `updatedInput`, so a widened read is recognised by the hook's own attachment for that tool-use id and counts as whole; the denial fail-open counts only attachments carrying `"permissionDecision":"deny"`, since the widen output also names the rule; a Bash `cat` counts only as the command word of its segment and not when piped onward (`cat x | head`, `git cat-file` no longer count). Cost: about 29 ms per non-rule `Read` (one `node` start), measured. Verified live on Claude Code 2.1.303 (2026-10-20): a `Read` of `METHOD-proportionality.md` with `limit: 5` returned all 63 lines. Updated together: `claude/hooks/aki-route-guard.mjs`, `install.mjs` (matcher, printed summary), `scripts/second_hop_audit.py`, `payload/RULE-agent-behavior.md` (`B7` row), `skills/akirule/SKILL.md` (delivery bullet), `claude/CLAUDE.md` (gate paragraph), `README.md`, `docs/arch/rule-delivery-architecture.md` (gate section, the read-only-reviewer sentence), `docs/index.md`. Plan: `docs/plan/done/full-file-reads.md`.
+- **`skills/akiflow/scripts/test_lint.py` renamed `suite_lint.py`.** Evidence: the script's own name matched the `RULE-test.md` route's `^test_.*\.py$` signature, so `test_lint.py --all .` linted itself as a test file (`[EXIT]`, `[HOMEREAD]` on its own exit calls and HOME read), the route gate demanded `RULE-test.md` before any edit of it, and pytest would collect it as a test module. Root cause: the name followed the `test_*.py` convention test runners treat as a test file. Mechanism: rename inside the `<domain>_lint.py` family (`release_lint.py`) without the `test_` prefix; the installer's per-skill mirror removes the old deployed copy and the skill-script allowlist is generated from the script inventory. Rejected: narrowing the route signature (`test_*.py` is the real pytest convention and must keep routing). Updated together: `payload/RULE-test.md` (`test.D1`), `README.md` (layout), `docs/index.md`, `docs/arch/rule-delivery-architecture.md`.
+- **The installer smoke test behaves the same on a developer machine as in CI.** Evidence: run locally on 2026-10-20 it failed twice where CI passes — `route gate did not deny an unread code edit` when the throwaway HOME sat under the session scratchpad, a path `route-map.json` ungates, and `rtk absent: hint line missing` when a real `rtk` was on `PATH`. Root cause: two fixtures inherited ambient state, the HOME location and the caller's `PATH` (`test.C2`). Mechanism: the gate probe edits a never-created project at the filesystem root instead of under HOME, and the rtk-absent case runs with every `PATH` entry holding an `rtk` binary removed. Rejected: documenting a required local setup (a hand-off the fixture itself can remove).
+- **`agent.A3` rebuilt on one root — understand what the owner asked, act only on an order — with the turn's first state-changing call bound to naming the words that order it; an order runs to the end without asking.** Evidence: on 2026-10-20 an agent with `A3` resident turned an owner question that hid its only `?` behind a hedge ("có thể là ghi thành notes …?") into a notes edit, then answered the correction with a second unordered `git restore`; asked to classify the same messages afterwards, it classified every one correctly. Eleven corpus changes since 07-23 moved this boundary back and forth — seven limiting action, four pushing it — and 108 clauses across the corpus restate one side or the other (`docs/research/question-vs-action-oct20.md`). Root cause: recognition was never the failure; `A3` asked for a judgment at no moment, while the rules that hold (`B4`) bind a literal cue to a moment, and the corpus named no root, so each incident added a counterweight. Mechanism: the root sentence, the hedge and polite-order cues ("can you fix X?" is an order), the check before the first state-changing call (anything beyond reading and checking: no ordering words, or words that read both ways, no call), and over-asking on ordered work named as an equal failure; the reversibility bullet and the one-line-suggestion bullet are removed as duplicates of `B3` and the new `A4` `N`; on a communication turn the decision block is the answer. Rejected: a `PreToolUse` gate on question-shaped messages (a per-language heuristic beside the route gate), a turn-class marker in the receipt (self-reported), a per-turn classifier call (paid quota), moving the case lists to `METHOD-deep-think.md` or a references file (Antigravity, Codex and workers would not load it at the moment it governs).
+- **`agent.A4` defines what an open item is — only what this turn cannot finish — and codes each by what the owner's silence does to it: `Q` (question · quyết) silence blocks, the owner must answer; `T` (taking it · tự làm) silence proceeds, a call the agent makes within the order, the `A3` decision block included; `N` (note · nhớ) silence changes nothing, a hold, a caution or an idea outside the order. Doable work is done, never listed; a release is one closing line once no `Q` is open; findings and options inside an analysis are numbered, never coded with these letters.** Evidence: 1,260 coded items in 298 open-item blocks across 254 Claude Code and 500 agy CLI sessions (2026-08-28 → 10-20), one letter carrying up to four meanings (`S` gate step, design option or task; `V` unverified or closed); 3,905 owner messages, of which an estimated 274 ask "done yet / why is it left", 222 ask for a shorter summary, 60 ask where an item is recorded and 54 ask what an item means or whether it matters. Root cause: `A4` gave three example letters by kind of work, so the owner had to read each item to learn whether it needed him. Mechanism: the owner's silence has exactly one consequence per item, so three letters partition every item and a new kind of work needs no fourth; listed `Q` → `T` → `N`, the owner stops reading once no `Q` is left; each letter reads in English and Vietnamese. Rejected: kind letters (`D`/`T`/`V`/`S`…), `D` (`D1` is Cloudflare's database), `P`/`W` (the owner's window handles), `S` (gate steps), `G` for "go" (a code would read as a run order; already labels goals in a plan), `M` (Apple `M1`), `H` as first applied (mixed an act only the owner's hands can do with a passive wait), announce-then-proceed outside the order (acts unordered, `A3`). Research: `docs/research/open-item-codes-oct20.md`.
+- **`agent.B3` asks only for what the order did not name ("Ask before, unless the order names the step:"), and the `B7` row for "When you have enough information to act, act" adds that the sentence never turns communication into an act.** Evidence: `B3`'s list asked even when the owner's order named the step, so the already-authorized kill-test inside `A3` never reached it; the act-now sentence first appears in this machine's transcripts on 2026-09-04, when the owner reports the failure grew. The shared-standards line stays: it guards rule corpora and templates other repos consume. The documented-design line now asks only for a conflict the order did not name, so naming a change never waives the conflict it hides.
+- Updated together: `payload/RULE-release.md` `B8` (pointer only, the over-asking restatement removed, the stale "durably authorized" clause replaced by `B3`'s new header), `payload/GEMINI.md` §8 and §12 (the "ambiguous task → stop and ask" line now names `A3`'s escalations, "can you fix X?" is a task, a correction of ordered work resumes it, CHECK 1 asks whether the user's words order the step instead of whether they literally name it; the file's deliberate repetition is kept), `skills/akiship/SKILL.md` (activation condition 2, a pointer; unverified leftovers are `N` items), `payload/RULE-coding.md` `B3` (runtime-unverified items and the hand-off ledger are `N` items, `Q` when a run waits on one), `agent.A3` (the decision block is a `T`), `skills/akithink/SKILL.md` (a decision record is proposed, not written, on a communication turn), `docs/arch/corpus-map.md`. Unchanged because still true: `coding.B3`'s kill-test pointer, `aki-challenger`, `aki-judge` and akiflow cite `A3`'s kill-tests, which stay.
+
+### Fixed
+- **The installer left `*.akidevrule-backup-*` files beside every file it touched, two per file, after every run.** Evidence: a dev box carried five such files under `~/.gemini/antigravity-cli/`, `~/.kiro/settings/` and `~/.cursor/` from runs on 2026-09-26 and 2026-09-28, kept by design. Root cause: `backup()` treated a pre-write copy as a permanent artifact and `pruneBackups()` kept the two newest, so every successful run converted rollback material into clutter in the user's config directories. Mechanism: every backup made by a run is recorded and removed once that run reaches its summary; a failed run keeps them (they are then the rollback); `pruneBackups()` keeps only the current run's copy by default, so older leftovers drain on the next run that touches the file; the one exception is a `~/.gemini/GEMINI.md` that held lines the install did not manage, whose backup stays (with one older) because it is the user's only copy of those lines and the migration directive points at it. Rejected: dropping backups altogether (a merge bug in `settings.json` would then have no rollback during the run). Updated together: `README.md` install steps, `docs/arch/rule-delivery-architecture.md` GEMINI flow.
+- **The route gate never counted a rule read made in Cursor, so every gated edit there was denied even after the rule file was read.** Evidence: Cursor loads hooks from `~/.claude` (`claudeUserHooks`), and its transcript stores the turn as `role: "assistant"`, the `Read` target as `path` and the shell tool as `Shell`; the hook matched only `type: "assistant"`, `file_path` and `Bash`, so no read was ever found. The three-denial fail-open did not fire either, because Cursor writes no `attachment.stdout` for the hook to count. Root cause: `scanTranscript` was written against Claude Code's transcript shape alone. Mechanism: it accepts either field name for each of the three (`type`/`role`, `file_path`/`path`, `Bash`/`Shell`); the compaction boundary is unchanged. Verified with synthetic transcripts against the hook: Cursor `Read`, Cursor `Shell` `cat`, Claude `Read`, Claude `Bash` `cat` → allowed; no read, a different rule file read, and a read followed by `compact_boundary` → denied. Rejected: a separate Cursor hook (two copies of one detection that would drift). Updated together: the hook's `scanTranscript` comment only.
+- **The installer reported "rtk found, left as is — its default filters drop evidence lines…" and asked the rtk prompt again on every install, even when the rtk config already carried the managed exclude list.** Evidence: found on the owner's Mac on 2026-10-20 after rtk was upgraded to 1.0.1 — a config that already held the full `exclude_commands` list still produced the warning and the question on each run. Root cause: the "declined" state was set without reading the config file, so the installer could not tell a declined machine from a configured one. Mechanism: `rtkReadState()` classifies the file first (already in place, opt-out, or kept as the user's own list with the missing names) and `rtkConfigure()` returns that answer; the prompt is asked only when a write would be needed (no file, no `[hooks]`, or `[hooks]` without the key). Rejected: remembering the answer in a state file (the config file already is the state). Verified: sandbox `HOME` with a fake `rtk`, no TTY — managed config → "already in place", opt-out → skipped, no file → "left as is" and nothing written, `--rtk` on no file → written; the Mac's real run now prints "already in place". Updated together: `install.mjs` (`rtkReadState`, `rtkConfigure`), `.github/workflows/install-smoke.yml` (the managed-config case without `--rtk`).
+
 ## [3.7.0] - 2026-10-08
 
 ### Added

package/README.md

@@ -34,6 +34,7 @@ This Git repository is the source of truth; `dev.akitao.com` is the presentation
 - [Usage model](#usage-model)
 - [Repository layout](#repository-layout)
 - [What the installer does](#what-the-installer-does)
+- [Optional: rtk](#optional-rtk)
 - [Gemini / Antigravity model](#gemini--antigravity-model)
 - [What is excluded](#what-is-excluded)
 - [Why `~/.aki/akidevrule`](#why-akiakidevrule)
@@ -102,7 +103,7 @@ Loading happens on two different mechanisms.
 
 **Resident — harness-embedded.** `RULE-agent-behavior.md` and the router `skills/akirule/SKILL.md` are `@`-imported by `~/.claude/CLAUDE.md`, which Claude Code reads mechanically at session start. No model decision is involved, so the behavior floor applies to every task and the routing is always present. The router joined the imports because as a skill it went uninvoked until the owner asked for it by name. `@` 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 meaning, and gated where the artifact gives it away.** Each task turn is classified by the domains it touches and the act (create, decide, audit, ship), in any language; each route carries concept signals in English and Vietnamese as evidence, never as the test, so a paraphrase routes as well as the listed word. The one model-dependent hop left is the `Read` of a routed file, and on Claude Code the `aki-route-guard` PreToolUse hook (`claude/hooks/aki-route-guard.mjs`) enforces it for every route with an artifact signature: the first Edit/Write of each artifact type in a session — a code file (`coding` + `pattern`), `.md` (`docs`), `CHANGELOG.md` (`release`), `.vue`/`.css` (`ui`, plus `stack` in a Nuxt project), `.rs` (`tauri`), `.sql` (`db`), `locales/` (`content`) — is denied until those files have been read in that transcript; a subagent is gated on its own transcript. Zero model hops in the check, at most one denial per artifact type per session, fail-open on any error, `AKI_ROUTE_GUARD=0` disables it. `RULE-coding.md` and `RULE-pattern-core.md` were resident imports from 2026-08-06 to 2026-09-30 because the router as a skill went uninvoked; importing the router restored the routing but not the read (measured: the model read a routed file unprompted in about one session in five — `docs/research/rule-delivery-second-hop-sep29.md`), so the gate now restores the guarantee by mechanism and the two files load only on code turns. Meaning-only routes (`think`, `proportion`, `biz`, `ux`, the audits) stay on the router alone, with sensitivity deliberately high (err toward loading — a false positive costs a few tokens, a false negative causes wrong behavior). The one deliberate exception is a lookup: a turn that only reads, counts, locates or explains what exists routes nothing, because no rule's act is performed — those turns are the majority for many users of this corpus, and the tiering exists so they pay for nothing beyond the two resident files.
+**Everything else — routed by meaning, and gated where the artifact gives it away.** Each task turn is classified by the domains it touches and the act (create, decide, audit, ship), in any language; each route carries concept signals in English and Vietnamese as evidence, never as the test, so a paraphrase routes as well as the listed word. The one model-dependent hop left is the `Read` of a routed file, and on Claude Code the `aki-route-guard` PreToolUse hook (`claude/hooks/aki-route-guard.mjs`) enforces it for every route with an artifact signature: the first Edit/Write of each artifact type in a session — a code file (`coding` + `pattern`), `.md` (`docs`), `CHANGELOG.md` (`release`), `.vue`/`.css` (`ui`, plus `stack` in a Nuxt project), `.rs` (`tauri`), `.sql` (`db`), `locales/` (`content`) — is denied until those files have been read whole in that transcript (a `limit`/`offset` or `head` read does not count, and the hook widens a partial `Read` of a rule file to the whole file); the path → rule map is the data file `payload/route-map.json`, not hook code; a subagent is gated on its own transcript. Zero model hops in the check, at most one denial per artifact type per session, fail-open on any error, `AKI_ROUTE_GUARD=0` disables it. `RULE-coding.md` and `RULE-pattern-core.md` were resident imports from 2026-08-06 to 2026-09-30 because the router as a skill went uninvoked; importing the router restored the routing but not the read (measured: the model read a routed file unprompted in about one session in five — `docs/research/rule-delivery-second-hop-sep29.md`), so the gate now restores the guarantee by mechanism and the two files load only on code turns. Meaning-only routes (`think`, `proportion`, `biz`, `ux`, the audits) stay on the router alone, with sensitivity deliberately high (err toward loading — a false positive costs a few tokens, a false negative causes wrong behavior). The one deliberate exception is a lookup: a turn that only reads, counts, locates or explains what exists routes nothing, because no rule's act is performed — those turns are the majority for many users of this corpus, and the tiering exists so they pay for nothing beyond the two resident files.
 
 - **Contextual and analytical — read on route match:** `RULE-coding.md` (code-quality floor: source of truth, changing existing code, verification and the hand-off ladder, comment budget, runtime safety), `RULE-pattern-core.md` (the 9 structural laws, decomposition, the critique gate before any abstraction), `RULE-test.md` (fewest tests: no new test by default, no new test file or folder when one fits, nothing touched the test does not own, a verdict that means what it exercised — gated on test-file edits), `RULE-docs.md` (structure and lifecycle, evidence-bound `ref/fact-*` fact docs, 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, fact-check), `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` (metadata, schema, sitemap, and URL form: relative at rest, absolute only where a consumer requires it), `RULE-release.md`, `RULE-db-design.md`, `RULE-biz.md` (market-facing decisions: positioning, pricing, audience) — plus the analytical methods (`METHOD-*`, loaded on route match like the rest): `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), `METHOD-audit-subtraction.md` (repo-wide "does this need to exist" sweep, terminating on two dry rounds), and `METHOD-audit-frozen-reference.md` (compliance audit for a clause naming a concrete external artifact as the canonical shape to match — resolve to an exact path, diff literally against it, never judge from memory of the rule's prose).
 - **Full load on explicit request:** asking, in any wording, to load the whole corpus reads every `RULE-*`/`METHOD-*` file at once.
@@ -193,6 +194,7 @@ payload/                          → installed to ~/.aki/akidevrule/
   METHOD-proportionality.md
   METHOD-audit-subtraction.md
   METHOD-audit-frozen-reference.md
+  route-map.json                  → path → rule map read by the route gate, the audit and the lint (data, not a rule)
   GEMINI.md                       → installed to ~/.gemini/GEMINI.md (NOT a rule file)
 
 skills/                            → shared Agent Skills corpus (SKILL.md open standard), deployed
@@ -205,7 +207,7 @@ skills/                            → shared Agent Skills corpus (SKILL.md open
   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/release_lint.py      (release-record lint: CHANGELOG section order/vocabulary/level, releases.json parity, type keys, highlight review — RULE-release.md C4, B7 step 4)
-  akiflow/scripts/test_lint.py         (test-file lint: literal /tmp, missing temp cleanup, exit calls as verdicts; sleeps, vacuous asserts, ambient ifs, HOME reads, live URLs, ports, source pins, history comments as review — RULE-test.md D1)
+  akiflow/scripts/suite_lint.py        (test-file lint: literal /tmp, missing temp cleanup, exit calls as verdicts; sleeps, vacuous asserts, ambient ifs, HOME reads, live URLs, ports, source pins, history comments as review — RULE-test.md D1)
   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
@@ -232,7 +234,7 @@ claude/                           → Claude Code-only runtime assets, installed
   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)
-  hooks/aki-route-guard.mjs         (PreToolUse route gate: denies the first edit of an artifact type until its routed rule was Read after the last compaction)
+  hooks/aki-route-guard.mjs         (PreToolUse route gate: denies the first edit of an artifact type until its routed rule was Read whole after the last compaction; widens partial Reads of rule files; reads ~/.aki/akidevrule/route-map.json)
   hooks/aki-compact-reread.mjs      (SessionStart on `compact` only: one notice that the rules read earlier left context)
   fragments/settings.akidoc.fragment.json   (illustrative reference only — never apply manually)
 
@@ -321,17 +323,45 @@ Targets 5-6 only get the shared skill corpus (no rule corpus / no `CLAUDE.md`/`G
 2. Deploys to **all detected Claude config directories** — `~/.claude` (default primary), all existing `~/.claude*` profile variants (e.g. `~/.claude-9rt`, `~/.claude-prx`), plus `$CLAUDE_CONFIG_DIR` or `--claude-dir <path>` if provided:
    - Syncs every skill folder under `skills/*/` (whole directory, including any `references/` or `scripts/`) into `<target>/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/fact-agent-skills-standard.md](docs/ref/fact-agent-skills-standard.md).
    - Copies `claude/agents/*.md` into `<target>/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 `<target>/skills/`, so nothing you did not install is ever removed.
-   - Replaces `<target>/CLAUDE.md` with the packaged guidance (timestamped backup first), appending this machine's source-repo path and an `@<target>/CLAUDE.local.md` import.
+   - Replaces `<target>/CLAUDE.md` with the packaged guidance (timestamped backup first, removed once the run succeeds), appending this machine's source-repo path and an `@<target>/CLAUDE.local.md` import.
    - Creates `<target>/CLAUDE.local.md` **only if missing** — never overwritten afterward. On profile variants (`~/.claude-*`), the template imports `@~/.claude/CLAUDE.local.md` by default so machine-wide facts are inherited. Put per-machine/per-profile rules there; they survive every reinstall.
-   - Before the confirmation prompt or any mutation, preflights every existing JSON file it may update: each detected profile's `settings.json`, `~/.gemini/config/skills.json`, `~/.gemini/antigravity-cli/settings.json`, and `~/.gemini/settings.json`. A malformed file or non-object root aborts the install with originals untouched. After preflight, updates `<target>/settings.json` with a timestamped backup: read permission for `~/.aki/akidevrule/**`, one `Bash(<launcher> <script>*)` rule per Aki skill script per rendering (absolute and `~/`-literal — Claude Code does not expand `~` before matching), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
-   - Installs `<target>/hooks/aki-update-check.mjs` plus its shared parser `<target>/hooks/aki_version_check.mjs`, `<target>/hooks/aki-route-guard.mjs` registered as a `PreToolUse` hook on `Edit|MultiEdit|Write|NotebookEdit`, and `<target>/hooks/aki-compact-reread.mjs` registered as a `SessionStart` hook with matcher `compact` (all idempotent, same filter-then-push as the update check).
+   - Before the confirmation prompt or any mutation, preflights every existing JSON file it may update: each detected profile's `settings.json`, `~/.gemini/config/skills.json`, `~/.gemini/antigravity-cli/settings.json`, and `~/.gemini/settings.json`. A malformed file or non-object root aborts the install with originals untouched. After preflight, updates `<target>/settings.json` with a timestamped backup (removed once the run succeeds): read permission for `~/.aki/akidevrule/**`, one `Bash(<launcher> <script>*)` rule per Aki skill script per rendering (absolute and `~/`-literal — Claude Code does not expand `~` before matching), `skillOverrides.akirule = "on"`, idempotent registration of the `SessionStart` update-check hook.
+   - Installs `<target>/hooks/aki-update-check.mjs` plus its shared parser `<target>/hooks/aki_version_check.mjs`, `<target>/hooks/aki-route-guard.mjs` registered as a `PreToolUse` hook on `Edit|MultiEdit|Write|NotebookEdit` and on `Read` (the `Read` branch widens a partial read of a rule file), and `<target>/hooks/aki-compact-reread.mjs` registered as a `SessionStart` hook with matcher `compact` (all idempotent, same filter-then-push as the update check).
 3. Writes `~/.aki/akidevrule/.version` with `installed=`/`version=`/`commit=`/`branch=` and records the source-repo path in `~/.aki/akidevrule/.source-repo` — `version=` is the just-installed CHANGELOG's latest released semver, the same value `install.mjs --check` and the hook compare against remote.
 4. Installs `payload/GEMINI.md` to `~/.gemini/GEMINI.md` — Antigravity global behavior overrides, stamped with a version marker (`[AKIRULE-AG-OVERRIDES-…]`) on line 1. Generates one native rule file per `RULE-*`/`METHOD-*` under `~/.gemini/config/rules/` with YAML `trigger` frontmatter — `agent` `always_on`, the stacks `glob`, the rest `model_decision` — each description generated from its `akirule` route, so both harnesses route from one table. Deploys 11 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 every `skills/*/scripts/*.py` 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/fact-cli-permission-allowlist-standard.md](docs/ref/fact-cli-permission-allowlist-standard.md) §1.2) plus scoped `write_file`/`read_file` rules for the council workspace and rule corpus.
 5. Syncs the same skill folders to `~/.agents/skills/` (Codex CLI, Cursor), `~/.kiro/skills/` (Kiro CLI), and `~/.grok/skills/` (Grok CLI) — each a plain global skills root these CLIs read natively, synced per skill folder name exactly like step 2. Kiro and Grok are skills-only. Codex additionally gets the managed `AGENTS.md` block and the `project_doc_max_bytes` key described above, only when `$CODEX_HOME` (default `~/.codex`) exists; the summary names the block size, the budget written or found, and a non-empty `AGENTS.override.md` that would shadow it.
 6. Pre-allows every Aki skill script in each harness present on the machine, one adapter per rule dialect (`lib/permissions.mjs`): `~/.kiro/settings/permissions.yaml` (a marker-delimited managed block), `~/.codex/rules/akidevrule.rules` (a file akidevrule owns), `~/.cursor/cli-config.json` (`Shell(python3:<script>*)`, never a bare `Shell(python3)`), `~/.config/opencode/opencode.json` (`permission.bash`). Every rule names one exact script, in both path renderings; entries a previous install wrote are replaced, the user's own are kept. Grok CLI and Ollama have no file-based allowlist, so nothing is written for them — [docs/ref/fact-cli-permission-allowlist-standard.md](docs/ref/fact-cli-permission-allowlist-standard.md).
 
+7. If `rtk` is on `PATH`, asks once — in a terminal only — whether to write its accuracy-first config (next section). Default, and the only answer when there is no terminal, is to leave rtk alone; the summary then prints one line saying so, with the `--rtk` flag that opts in without a prompt.
+
 Re-running the installer updates the same managed files cleanly.
 
+## Optional: rtk
+
+[rtk](https://github.com/rtk-ai/rtk) is an output compressor that hooks into Claude Code's Bash tool and rewrites commands so their output comes back shorter. It is not required and the installer never installs it. What it saves is real on the noise class — `git status`, `git add/commit/push/pull`, package installs, build logs. What it costs is measured in `docs/research/rtk-output-loss-oct19.md`: its built-in filters also cut the commands an agent reads as evidence, and nothing in the shortened output says which lines are gone. Tested on rtk 0.50.0, raw against filtered: `ls` merges directories, caps at 50 entries and drops names ending in `.` with no marker; `grep` cuts lines at 80 characters and keeps 211 of 480; `find` hides dotfiles and gitignored paths; `git log` stops at 10 commits with no "more" line; `git diff` kept 610 of 7,541 lines; `jq` cuts every line at 120 characters. An agent that counts, quotes, diffs or claims "not found" from that output is wrong without knowing it, and the recovery hints rtk prints were followed 3 times in 480 elisions on the dev box. Large output needs no compressor to stay safe: Claude Code itself saves any Bash output past about 30,000 characters to a file and hands the model the path.
+
+rtk has no lossless mode (upstream issue #1313, open since 2026-04), and its built-in filters ignore `filters.toml`. The one knob that makes them lossless is `[hooks] exclude_commands` in rtk's `config.toml`: a listed command is not rewritten at all. The installer offers to write exactly that — **accuracy over savings** — and only on an explicit yes:
+
+| Answer | Effect |
+|---|---|
+| `y` in the terminal, or `--rtk` on the command line (`node install.mjs --rtk`, `npx @akinet/akidevrule@latest --rtk`) | writes the `[hooks]` table below into rtk's config (path taken from `rtk config`; `~/.config/rtk/config.toml` on Linux, `~/Library/Application Support/rtk/config.toml` on macOS, `%APPDATA%\rtk\config.toml` on Windows); an existing file is backed up first and other tables are kept; a `[hooks] exclude_commands` you wrote yourself is never touched — the summary lists what it still lacks |
+| `N`, Enter, or no terminal (CI, an agent running the installer) | rtk stays exactly as it is; the summary prints one line saying so |
+| a line `# akidevrule: rtk off` anywhere in the config | the installer skips rtk for good, even with `--rtk` |
+
+````toml
+# akidevrule: accuracy-first rtk — commands whose output is evidence run unfiltered (akidevrule README § Optional: rtk)
+[hooks]
+exclude_commands = [
+  "ls", "tree", "find", "grep", "rg", "ast-grep", "wc", "diff",
+  "cat", "head", "tail",
+  "jq", "stat", "du", "df", "ps", "ssh", "rsync", "curl", "wget",
+  "gh", "glab", "psql", "aws", "kubectl", "oc", "docker",
+  "^git(\\s+-[Cc]\\s+\\S+)*\\s+(diff|log|show|stash|branch)\\b",
+]
+````
+
+Everything not listed — `git status`/`commit`/`push`, `npm`, `cargo`, `pytest`, `make` — stays compressed, and the rule corpus covers that residue: `coding.B3` treats any output carrying an elision marker as a sample and reruns it raw (`RTK_DISABLED=1 <cmd>`) before counting or quoting from it. The exclusion list is honoured on every rtk from 0.47.0 to 1.0.1 (hook-tested on 0.47.0, 0.50.0 and 1.0.1); the 1.0 line adds pipelines, `rtk bypass`, and a licence split (Apache-2.0 CLI plus a BUSL-1.1 compression engine, free for production use; `rtk-oss` is Apache-only without the engine), none of which changes the config above. From 0.49.0 you may also enlarge the recall store, which fills in days at its default of 200 entries: `[retriever] mode = "sqlite"`, `max_entries = 2000`, `retention_days = 30` — not written by the installer, since older rtk versions have no sqlite store (they ignore the table). Decision trail: `docs/plan/rtk-accuracy-first.md`.
+
 ## Gemini / Antigravity model
 
 Claude Code loads the core and the router automatically (harness-guaranteed `@`-imports in `~/.claude/CLAUDE.md`). 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), native rules route the corpus with descriptions generated from the `akirule` routes, 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).
@@ -361,6 +391,7 @@ rm -f  ~/.claude/hooks/aki-update-check.mjs ~/.claude/hooks/aki_version_check.mj
 # then delete the three entries whose command names those hooks from hooks.SessionStart and hooks.PreToolUse in ~/.claude/settings.json
 # Codex: delete the `>>> akidevrule managed` … `<<< akidevrule managed` block in ~/.codex/AGENTS.md (the rest is yours), and the project_doc_max_bytes line in ~/.codex/config.toml if unwanted
 rm -f  ~/.gemini/GEMINI.md          # restore from a *.akidevrule-backup-* if needed; GEMINI.local.md is left untouched
+# rtk, only if you answered y: remove the `# akidevrule: accuracy-first rtk` [hooks] table from rtk's config.toml (`rtk config` prints its path)
 ```
 
 On **Windows** the same targets live under `%USERPROFILE%` (e.g. `%USERPROFILE%\.aki\akidevrule`, `%USERPROFILE%\.claude\skills\...`); remove them with `Remove-Item -Recurse -Force`.

package/claude/CLAUDE.md

@@ -3,6 +3,6 @@
 @~/.aki/akidevrule/RULE-agent-behavior.md
 @~/.claude/skills/akirule/SKILL.md
 
-The harness embeds both at session start: the behavior floor and the router. Every other rule enters context when the model `Read`s it on a route match. For routes with an artifact signature the `aki-route-guard` PreToolUse hook denies the first Edit/Write of that artifact type in a session until the routed files were read after the last compaction — the deny reason names them; read them in full, then retry. Meaning-only routes stay model-dependent: route on meaning, load when the domain is in doubt. A turn that only reads, counts or explains what exists routes nothing.
+The harness embeds both at session start: the behavior floor and the router. Every other rule enters context when the model `Read`s it on a route match. For routes with an artifact signature the `aki-route-guard` PreToolUse hook denies the first Edit/Write of that artifact type in a session until the routed files were read whole after the last compaction — the deny reason names them; read them in full, then retry. Meaning-only routes stay model-dependent: route on meaning, load when the domain is in doubt. A turn that only reads, counts or explains what exists routes nothing.
 
 Doc corpora named by short name in conversation ("UNIDOC", "the standards doc") are machine-specific: resolve them in `~/.claude/CLAUDE.local.md` before searching or asking.

package/claude/agents/aki-hands.md

@@ -13,7 +13,7 @@ If the brief asks you to decide something, return the evidence and say the quest
 
 # 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).
+- `~/.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` (no throwaway file the task can do without, and none outside 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.
 

package/claude/agents/aki-maker.md

@@ -15,7 +15,7 @@ Change exactly what was asked. No adjacent refactors, no cleanup, no renames, no
 
 # Rules you must read before working
 
-- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor: `B1` scope discipline, `B3` what to ask before, `B4` no model-credit trailers in any git artifact, `C3` never hard-wrap a logical line, `C5` temp files only in the scratchpad.
+- `~/.aki/akidevrule/RULE-agent-behavior.md` — the behavior floor: `B1` scope discipline, `B3` what to ask before, `B4` no model-credit trailers in any git artifact, `C3` never hard-wrap a logical line, `C5` no throwaway file the task can do without, and none outside the scratchpad.
 - `~/.aki/akidevrule/RULE-coding.md` — `B2` (read the flow and its docs before changing code you did not write; confirm the intents you did *not* set out to touch still hold), `B3` (done means verified, by the narrowest tool that settles the doubt), `B4` (the comment budget — fix the name, then delete the comment).
 - `~/.aki/akidevrule/RULE-pattern-core.md` — `C1` is the definition of done at the pattern level.
 - `~/.aki/akidevrule/RULE-test.md` — only when the diff touches a test file, fixture or test config; the route gate denies the first such edit until it is read, so read it first.

package/claude/hooks/aki-route-guard.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // PreToolUse route gate, fail-open. Design: docs/research/rule-delivery-second-hop-sep29.md
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, statSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname, basename, extname } from "node:path";
 
@@ -11,53 +11,48 @@ const MARK = "aki-route-guard";
 const COMPACT = "compact_boundary";
 const MAX_DENIALS_PER_RULE = 3; // a detection bug must never lock a session; after this many denials in one compaction segment the rule is treated as read
 
-const CODE_EXT = new Set(["ts", "tsx", "js", "jsx", "mjs", "cjs", "vue", "svelte", "rs", "py", "go", "rb", "php", "java", "kt", "swift", "c", "cc", "cpp", "h", "hpp", "cs", "sh", "bash", "zsh", "ps1", "sql", "css", "scss", "lua", "dart"]);
-const FRONTEND_EXT = new Set(["vue", "svelte", "css", "scss", "tsx", "jsx"]);
-const TEST_NAME = /\.(test|spec)\.[a-z]+$|_test\.[a-z]+$|^test_.*\.py$|^conftest\.py$/;
-const TEST_DIR = /(^|\/)(test|tests|__tests__|spec)\//;
+const MAX_WIDEN_BYTES = 60000; // the Read tool refuses files over ~25k tokens; above this a partial read is the only possible one
 
 function allow() {
   process.exit(0);
 }
 
-/** Rule files a path routes to; only routes with an artifact signature (docs/research/rule-delivery-second-hop-sep29.md §2). */
-function routesFor(filePath, cwd) {
+/** payload/route-map.json (installed to RULE_DIR), the one path-to-rule map; null when missing or invalid so the gate fails open. */
+function loadMap() {
+  try {
+    const m = JSON.parse(readFileSync(join(RULE_DIR, "route-map.json"), "utf8"));
+    return Array.isArray(m.routes) && m.ungated ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Rule files a path routes to, interpreting the map's routes. */
+function routesFor(map, filePath, cwd) {
   const p = filePath.replace(/\\/g, "/");
   const name = basename(p);
   const ext = extname(name).slice(1).toLowerCase();
   const rules = new Set();
-  const root = cwd ? cwd.replace(/\\/g, "/") + "/" : "";
+  const root = cwd ? cwd.replace(/\\/g, "/").replace(/\/+$/, "") + "/" : "";
   const rel = "/" + (root && p.startsWith(root) ? p.slice(root.length) : p.replace(/^\//, "")); // directory routes match inside the project only: a project under ~/tests/ or ~/lang/ must not route every file
-  if (TEST_NAME.test(name) || (TEST_DIR.test(rel) && ext !== "md")) rules.add("RULE-test.md");
-  if (CODE_EXT.has(ext)) {
-    rules.add("RULE-coding.md");
-    rules.add("RULE-pattern-core.md");
+  for (const r of map.routes) {
+    const hit = (r.ext || []).includes(ext) || (r.name || []).includes(name) || (r.nameRe && new RegExp(r.nameRe).test(name)) || (r.dirRe && !(r.dirSkipExt || []).includes(ext) && new RegExp(r.dirRe).test(rel));
+    if (hit && (!r.projectHas || (cwd && r.projectHas.some((f) => existsSync(join(cwd, f)))))) for (const x of r.rules) rules.add(x);
   }
-  if (ext === "md") rules.add("RULE-docs.md");
-  if (name === "CHANGELOG.md" || name === "releases.json") rules.add("RULE-release.md");
-  if (FRONTEND_EXT.has(ext)) rules.add("RULE-ui-pattern.md");
-  if (ext === "sql" || /\/migrations\//.test(rel)) rules.add("RULE-db-design.md");
-  if (/\/(locales|i18n|lang)\//.test(rel)) rules.add("RULE-content-write.md");
-  if (ext === "rs" || /\/src-tauri\//.test(rel) || name === "tauri.conf.json") rules.add("RULE-stack-tauri.md");
-  if ((ext === "vue" || ext === "ts") && isNuxtProject(cwd)) rules.add("RULE-stack-akiNuxtCf.md");
   return rules;
 }
 
 /** Scratchpad, harness state and the corpus itself: files no project rule governs, so a Q&A session that writes a throwaway script or a memory note stays ungated. */
-function isUngatedPath(filePath, cwd) {
+function isUngatedPath(map, filePath, cwd) {
   const p = filePath.replace(/\\/g, "/");
-  if (p.includes("/.aki/")) return true;
+  const u = map.ungated;
+  if ((u.segments || []).some((s) => p.includes(s))) return true;
   if (p.startsWith(CONFIG_DIR.replace(/\\/g, "/") + "/")) return true;
-  if (/^\/tmp\//.test(p) || /\/scratchpad\//.test(p)) return true;
-  if (cwd && !p.startsWith(cwd.replace(/\\/g, "/") + "/")) return true;
+  if ((u.prefixes || []).some((s) => p.startsWith(s)) || (u.dirs || []).some((d) => p.includes(`/${d}/`))) return true;
+  if (cwd && !p.startsWith(cwd.replace(/\\/g, "/").replace(/\/+$/, "") + "/")) return true;
   return false;
 }
 
-function isNuxtProject(cwd) {
-  if (!cwd) return false;
-  return ["nuxt.config.ts", "nuxt.config.js", "nuxt.config.mjs"].some((f) => existsSync(join(cwd, f)));
-}
-
 /** Rule files the harness already embeds via `@` imports in the global CLAUDE.md; never gated. */
 function residentRules() {
   const out = new Set();
@@ -82,15 +77,17 @@ function transcriptFor(input) {
   return main;
 }
 
-/** Scan a transcript once: which rule files were Read (Read tool, or a Bash cat/sed/head/bat of the file) since the last compaction, and how many times this hook already denied for each in that segment. A compaction drops the rule text from the model's context, so reads and denials before it do not count (agent.B7 row 2). */
+/** Scan a transcript once: which rule files were read whole (Read tool without offset/limit short of the file, or a Bash/Shell cat/bat/less of it; head/sed/tail never count) since the last compaction, and how many times this hook already denied for each in that segment. A compaction drops the rule text from the model's context, so reads and denials before it do not count (agent.B7 row 2). Claude Code stores the turn as type "assistant" and the Read target as file_path. Cursor stores role "assistant", the Read target as path, and the shell tool as Shell. */
 function scanTranscript(path, wanted) {
   const read = new Set();
+  const partial = new Set();
   const denials = new Map();
+  const pending = new Map(); // partial Read tool_use id -> rules, resolved when the hook's updatedInput attachment for that id appears
   let text;
   try {
     text = readFileSync(path, "utf8");
   } catch {
-    return { read, denials, unreadable: true };
+    return { read, partial, denials, unreadable: true };
   }
   for (const line of text.split("\n")) {
     if (!line.includes("akidevrule") && !line.includes(MARK) && !line.includes(COMPACT)) continue;
@@ -100,51 +97,105 @@ function scanTranscript(path, wanted) {
     } catch {
       continue;
     }
+    const assistant = d.type === "assistant" || d.role === "assistant";
     if (d.type === "system" && d.subtype === COMPACT) {
       read.clear();
+      partial.clear();
       denials.clear();
-    } else if (d.type === "assistant") {
+      pending.clear();
+    } else if (assistant) {
       const content = d.message && Array.isArray(d.message.content) ? d.message.content : [];
       for (const c of content) {
         if (!c || c.type !== "tool_use" || !c.input) continue;
         if (c.name === "Read") {
-          const target = String(c.input.file_path || "");
-          for (const r of wanted) if (target.endsWith(r)) read.add(r);
-        } else if (c.name === "Bash") {
+          const target = String(c.input.file_path || c.input.path || "");
+          for (const r of wanted) {
+            if (!target.endsWith(r)) continue;
+            const whole = !(c.input.offset > 1) && (!c.input.limit || c.input.limit >= lineCount(r));
+            (whole ? read : partial).add(r);
+            if (!whole && c.id) pending.set(c.id, [...(pending.get(c.id) || []), r]);
+          }
+        } else if (c.name === "Bash" || c.name === "Shell") {
           const cmd = String(c.input.command || "");
-          for (const r of wanted) if (new RegExp(`\\b(cat|sed|head|bat|less)\\b[^|;&\\n]*${r.replace(".", "\\.")}`).test(cmd)) read.add(r);
+          for (const r of wanted) {
+            const name = r.replace(".", "\\.");
+            for (const m of cmd.matchAll(new RegExp(`(?:^|[;&|(\\n])\\s*(?:cat|bat|less)\\s[^|;&\\n]*?${name}[^|;&\\n]*(\\|(?!\\|))?`, "g"))) (m[1] ? partial : read).add(r);
+            if (new RegExp(`\\b(head|sed|tail)\\b[^|;&\\n]*${name}`).test(cmd)) partial.add(r);
+          }
         }
       }
     } else if (d.attachment && typeof d.attachment.stdout === "string" && d.attachment.stdout.includes(MARK)) {
-      for (const r of wanted) if (d.attachment.stdout.includes(r)) denials.set(r, (denials.get(r) || 0) + 1);
+      const a = d.attachment;
+      const widened = String(a.hookName || "").startsWith("PreToolUse") && a.stdout.includes('"updatedInput"') && pending.has(a.toolUseID);
+      if (widened) {
+        for (const r of pending.get(a.toolUseID)) {
+          partial.delete(r);
+          read.add(r);
+        }
+        pending.delete(a.toolUseID);
+      } else if (a.stdout.includes('"permissionDecision":"deny"')) {
+        for (const r of wanted) if (a.stdout.includes(r)) denials.set(r, (denials.get(r) || 0) + 1);
+      }
     }
   }
-  return { read, denials, unreadable: false };
+  return { read, partial, denials, unreadable: false };
+}
+
+function lineCount(rule) {
+  try {
+    return readFileSync(join(RULE_DIR, rule), "utf8").replace(/\n$/, "").split("\n").length;
+  } catch {
+    return Infinity;
+  }
 }
 
-function deny(missing, filePath) {
+function deny(missing, partial, filePath) {
   const files = missing.map((r) => `~/.aki/akidevrule/${r}`).join(" and ");
-  const reason = `[${MARK}] Editing ${basename(filePath)} is gated on rule files not read since the last compaction of this session: ${missing.join(", ")}. Read ${files} in full with the Read tool, add them to the [RULES] receipt, then retry this edit.`;
+  const reason = `[${MARK}] Editing ${basename(filePath)} is gated on rule files not read since the last compaction of this session: ${missing.join(", ")}. Read ${files} in full with the Read tool, add them to the [RULES] receipt, then retry this edit.${missing.some((r) => partial.has(r)) ? " A Read with limit/offset or a head/sed/tail print does not count — read the whole file." : ""}`;
   process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }) + "\n");
   process.exit(0);
 }
 
+/** A partial Read of a rule file is rewritten to a whole one; above the Read tool's size cap a partial read is the only one possible, so it passes. */
+function widenRuleRead(ti) {
+  if (ti.limit == null && ti.offset == null) allow();
+  // permissionDecision allow skips the permission prompt, so it applies only to the corpus's own files, judged on the resolved path
+  const real = (x) => {
+    try {
+      return realpathSync(x).replace(/\\/g, "/");
+    } catch {
+      return null;
+    }
+  };
+  const p = real(String(ti.file_path || ti.path || ""));
+  if (!p) allow();
+  const inside = (dir) => dir !== null && p.startsWith(dir + "/");
+  const isRule = (inside(real(RULE_DIR)) && p.endsWith(".md")) || (basename(p) === "SKILL.md" && inside(real(join(CONFIG_DIR, "skills"))));
+  if (!isRule || statSync(p).size > MAX_WIDEN_BYTES) allow();
+  const { limit, offset, ...updatedInput } = ti;
+  const reason = `[${MARK}] rule files are read whole: limit/offset removed`;
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow", permissionDecisionReason: reason, updatedInput } }) + "\n");
+  process.exit(0);
+}
+
 function main() {
   if (process.env.AKI_ROUTE_GUARD === "0") allow();
   const input = JSON.parse(readFileSync(0, "utf8"));
   const ti = input.tool_input || {};
+  if (input.tool_name === "Read") widenRuleRead(ti);
   const filePath = ti.file_path || ti.notebook_path;
   if (!filePath || !input.transcript_path) allow();
-  if (isUngatedPath(filePath, input.cwd)) allow();
-  const wanted = [...routesFor(filePath, input.cwd)].filter((r) => existsSync(join(RULE_DIR, r)));
+  const map = loadMap();
+  if (!map || isUngatedPath(map, filePath, input.cwd)) allow();
+  const wanted = [...routesFor(map, filePath, input.cwd)].filter((r) => existsSync(join(RULE_DIR, r)));
   const resident = residentRules();
   const gated = wanted.filter((r) => !resident.has(r));
   if (gated.length === 0) allow();
-  const { read, denials, unreadable } = scanTranscript(transcriptFor(input), gated);
+  const { read, partial, denials, unreadable } = scanTranscript(transcriptFor(input), gated);
   if (unreadable) allow();
   const missing = gated.filter((r) => !read.has(r) && (denials.get(r) || 0) < MAX_DENIALS_PER_RULE);
   if (missing.length === 0) allow();
-  deny(missing, filePath);
+  deny(missing, partial, filePath);
 }
 
 try {

package/install.mjs

@@ -203,21 +203,34 @@ const blueBold = (t) => c("1;34", t);
 // Backup / prune
 // ---------------------------------------------------------------------------
 
+// A backup is rollback material for this run only: removed once the run succeeds, kept when it fails. keepBackup() exempts one that holds content the install discarded.
+const runBackups = new Set();
+
 function backup(path) {
   if (!existsSync(path)) return;
   const dest = join(dirname(path), `${basename(path)}.akidevrule-backup-${STAMP}`);
   if (isDir(path)) copyTree(path, dest);
   else copyFileSync(path, dest);
+  runBackups.add(dest);
+}
+
+function keepBackup(path) {
+  runBackups.delete(join(dirname(path), `${basename(path)}.akidevrule-backup-${STAMP}`));
 }
 
-function pruneBackups(base) {
+function dropRunBackups() {
+  for (const dest of runBackups) rmrf(dest);
+  runBackups.clear();
+}
+
+function pruneBackups(base, keep = 1) {
   const parent = dirname(base);
   const prefix = `${basename(base)}.akidevrule-backup-`;
   const candidates = listDir(parent)
     .filter((n) => n.startsWith(prefix))
     .map((n) => join(parent, n))
     .sort((a, b) => statSync(a).mtimeMs - statSync(b).mtimeMs);
-  for (const old of candidates.slice(0, -2)) {
+  for (const old of candidates.slice(0, -keep)) {
     console.log(`  🗑️  Removing old backup: ${basename(old)}`);
     rmrf(old);
   }
@@ -455,6 +468,150 @@ function installCodexInstructions() {
   return { file, bytes, changed, shadowed, budget: ensureCodexDocBudget(bytes) };
 }
 
+// ---------------------------------------------------------------------------
+// rtk — optional output compressor on Claude Code's Bash tool; opt-in accuracy-first config (README § Optional: rtk, docs/plan/rtk-accuracy-first.md)
+// ---------------------------------------------------------------------------
+
+const RTK_OPT_OUT = "# akidevrule: rtk off";
+const RTK_MANAGED_MARK = "# akidevrule: accuracy-first rtk";
+const RTK_EXCLUDE = [
+  ["ls", "tree", "find", "grep", "rg", "ast-grep", "wc", "diff"],
+  ["cat", "head", "tail"],
+  ["jq", "stat", "du", "df", "ps", "ssh", "rsync", "curl", "wget"],
+  ["gh", "glab", "psql", "aws", "kubectl", "oc", "docker"],
+  ["^git(\\s+-[Cc]\\s+\\S+)*\\s+(diff|log|show|stash|branch)\\b"],
+];
+const RTK_EVIDENCE_FAMILIES = "ls, grep, find, git diff/log/show, jq";
+const RTK_NOISE_FAMILIES = "git status, package installs and build logs";
+
+// TOML basic strings take JSON's escapes for backslash and quote, so JSON.stringify renders each entry.
+function rtkExcludeLines() {
+  return RTK_EXCLUDE.map((group) => `  ${group.map((s) => JSON.stringify(s)).join(", ")},`).join("\n");
+}
+
+function rtkHooksTable() {
+  return `${RTK_MANAGED_MARK} — commands whose output is evidence run unfiltered (akidevrule README § Optional: rtk)\n[hooks]\nexclude_commands = [\n${rtkExcludeLines()}\n]\n`;
+}
+
+// Fallback mirrors rtk's dirs::config_dir() layout (XDG, Application Support, RoamingAppData) when `rtk config` prints no path.
+function rtkDetect() {
+  let r;
+  try {
+    r = spawnSync("rtk", ["config"], { encoding: "utf-8", timeout: 5000, shell: IS_WIN });
+  } catch {
+    return null;
+  }
+  if (r.error || r.status !== 0) return null;
+  const m = (r.stdout || "").match(/^Config:\s*(.+?)\s*$/m);
+  if (m) return { path: expandTilde(m[1]) };
+  const base = process.platform === "darwin" ? join(HOME, "Library", "Application Support") : IS_WIN ? process.env.APPDATA || join(HOME, "AppData", "Roaming") : process.env.XDG_CONFIG_HOME || join(HOME, ".config");
+  return { path: join(base, "rtk", "config.toml") };
+}
+
+// The [name] table's body: from its header to the next table header. null when absent.
+function tomlTable(text, name) {
+  const header = new RegExp(`^[ \\t]*\\[${escapeRe(name)}\\][ \\t]*(#.*)?$`, "m");
+  const h = text.search(header);
+  if (h === -1) return null;
+  const bodyStart = text.indexOf("\n", h) + 1;
+  const rest = text.slice(bodyStart);
+  const next = rest.search(TOML_HEADER);
+  const end = next === -1 ? text.length : bodyStart + next;
+  return { start: h, bodyStart, end, body: text.slice(bodyStart, end) };
+}
+
+// String entries of the array that follows `key =`, read until the unquoted `]` (a quoted entry may itself contain one).
+function tomlStringArray(body, key) {
+  const k = body.match(new RegExp(`^[ \\t]*${escapeRe(key)}[ \\t]*=[ \\t]*\\[`, "m"));
+  if (!k) return null;
+  const out = [];
+  let i = k.index + k[0].length;
+  while (i < body.length) {
+    const ch = body[i];
+    if (ch === "]") break;
+    if (ch === '"' || ch === "'") {
+      const close = ch === '"' ? /(?:[^"\\]|\\.)*"/y : /[^']*'/y;
+      close.lastIndex = i + 1;
+      const m = close.exec(body);
+      if (!m) break;
+      const raw = m[0].slice(0, -1);
+      out.push(ch === '"' ? JSON.parse(`"${raw}"`) : raw);
+      i = close.lastIndex;
+      continue;
+    }
+    if (ch === "#") i = body.indexOf("\n", i) === -1 ? body.length : body.indexOf("\n", i);
+    else i++;
+  }
+  return out;
+}
+
+// Read-only classification: the state the file is already in, or null when a write would be needed (no file, no [hooks], [hooks] without exclude_commands).
+function rtkReadState(cfg) {
+  const text = isFile(cfg) ? readFileSync(cfg, "utf-8") : "";
+  if (text.includes(RTK_OPT_OUT)) return { path: cfg, state: "opt-out" };
+  const hooks = tomlTable(text, "hooks");
+  const have = hooks && tomlStringArray(hooks.body, "exclude_commands");
+  if (!have) return null;
+  const missing = RTK_EXCLUDE.flat().filter((s) => !have.includes(s));
+  return { path: cfg, state: missing.length ? "kept" : "unchanged", missing };
+}
+
+// Smallest safe change: no file → write; no [hooks] → append the table; [hooks] without exclude_commands → insert the key; anything else is rtkReadState's answer.
+function rtkConfigure(cfg) {
+  const known = rtkReadState(cfg);
+  if (known) return known;
+  const text = isFile(cfg) ? readFileSync(cfg, "utf-8") : "";
+  const write = (after) => {
+    if (text) {
+      backup(cfg);
+      pruneBackups(cfg);
+    }
+    writeTextLf(cfg, after);
+  };
+  const hooks = tomlTable(text, "hooks");
+  if (!hooks) {
+    write((text ? text.replace(/\s*$/, "") + "\n\n" : "") + rtkHooksTable());
+    return { path: cfg, state: text ? "appended" : "written" };
+  }
+  write(text.slice(0, hooks.bodyStart) + `exclude_commands = [ ${RTK_MANAGED_MARK}\n${rtkExcludeLines()}\n]\n` + text.slice(hooks.bodyStart));
+  return { path: cfg, state: "appended" };
+}
+
+function rtkPrompt(cfg) {
+  console.log(`\n🔎 ${yellowBold("rtk found")} — an output compressor that hooks into Claude Code's Bash tool.`);
+  console.log(`   Its built-in filters save tokens by dropping lines — also from ${RTK_EVIDENCE_FAMILIES}, whose output an agent reads as evidence (a count, a quote, a "not found").`);
+  console.log(`   ${greenBold("y")} → write an accuracy-first rtk config at ${toTildePath(cfg)}: those commands run unfiltered; ${RTK_NOISE_FAMILIES} stay compressed. Existing file backed up; opt out later with a "${RTK_OPT_OUT}" line.`);
+  console.log(`   ${greenBold("N")} → leave rtk as it is (default). Details: README § Optional: rtk`);
+}
+
+function printRtkSummary(rtk) {
+  console.log();
+  console.log(cyanBold("rtk (optional output compressor):"));
+  if (!rtk) {
+    console.log("  ℹ️  rtk not found — nothing to configure. If you install it later, re-run with --rtk to run evidence commands unfiltered (README § Optional: rtk)");
+    return;
+  }
+  const p = toTildePath(rtk.path);
+  switch (rtk.state) {
+    case "declined":
+      console.log(`  ⚠️  rtk found, left as is — its default filters drop evidence lines from ${RTK_EVIDENCE_FAMILIES}. To run those unfiltered: re-run and answer y, or \`node install.mjs --rtk\` (README § Optional: rtk)`);
+      break;
+    case "written":
+    case "appended":
+      console.log(`  ✅ accuracy-first config ${rtk.state === "written" ? "written" : "added"}: ${p} — ${RTK_EVIDENCE_FAMILIES} … unfiltered; ${RTK_NOISE_FAMILIES} still compressed`);
+      break;
+    case "unchanged":
+      console.log(`  ✅ accuracy-first config already in place: ${p}`);
+      break;
+    case "kept":
+      console.log(`  ⚠️  ${p} has its own [hooks] exclude_commands — kept as yours; not in it yet: ${rtk.missing.join(", ")}`);
+      break;
+    case "opt-out":
+      console.log(`  ℹ️  ${p} carries "${RTK_OPT_OUT}" — skipped`);
+      break;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // settings.json merge (Claude Code)
 // ---------------------------------------------------------------------------
@@ -553,16 +710,18 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
     }
   };
   hooks.PreToolUse = hooks.PreToolUse.filter((e) => !isAkiRouteGuard(e));
-  hooks.PreToolUse.push({
-    matcher: "Edit|MultiEdit|Write|NotebookEdit",
-    hooks: [
-      {
-        type: "command",
-        command: `node "${join(claudeDir, "hooks", "aki-route-guard.mjs")}"`,
-        timeout: 10,
-      },
-    ],
-  });
+  for (const matcher of ["Edit|MultiEdit|Write|NotebookEdit", "Read"]) {
+    hooks.PreToolUse.push({
+      matcher,
+      hooks: [
+        {
+          type: "command",
+          command: `node "${join(claudeDir, "hooks", "aki-route-guard.mjs")}"`,
+          timeout: 10,
+        },
+      ],
+    });
+  }
 
   writeTextLf(settingsPath, JSON.stringify(data, null, 2) + "\n");
 }
@@ -849,7 +1008,7 @@ async function inspectStatus(claudeDirs) {
 // print_summary (post-install)
 // ---------------------------------------------------------------------------
 
-function printSummary(claudeDirs, preAllow, codex) {
+function printSummary(claudeDirs, preAllow, codex, rtk) {
   console.log(`\n${greenBold("=== INSTALL SUCCEEDED ===")}`);
 
   const gitHash = gitShortHash(REPO_ROOT);
@@ -920,10 +1079,12 @@ function printSummary(claudeDirs, preAllow, codex) {
 
   console.log();
   console.log(cyanBold("Hooks deployed:"));
-  console.log("  🚧 aki-route-guard (PreToolUse on Edit|MultiEdit|Write|NotebookEdit) — denies the first edit of an artifact type until its routed rule was Read after the last compaction; AKI_ROUTE_GUARD=0 disables");
+  console.log("  🚧 aki-route-guard (PreToolUse on Edit|MultiEdit|Write|NotebookEdit and Read) — edit gate: denies the first edit of an artifact type until its routed rule was Read whole after the last compaction; Read of a rule file is widened to the whole file; AKI_ROUTE_GUARD=0 disables");
   console.log("  🔁 aki-compact-reread (SessionStart, compact only) — one notice after a compaction: routed rules left context, re-read before the next edit");
   console.log("  📢 aki-update-check (SessionStart, notify-only) — notifies when a new rule version is available");
 
+  printRtkSummary(rtk);
+
   console.log(`\n${greenBold("==============================")}`);
 }
 
@@ -945,7 +1106,7 @@ function ask(question) {
 // Main install logic
 // ---------------------------------------------------------------------------
 
-async function runInstall(claudeDirs) {
+async function runInstall(claudeDirs, { rtkFlag = false } = {}) {
   const sameCheckout = await inspectStatus(claudeDirs);
 
   // Skip the prompt only for a byte-identical overwrite (same commit, clean tree).
@@ -957,6 +1118,15 @@ async function runInstall(claudeDirs) {
     }
   }
 
+  // rtk: asked up front so the run has no mid-install question; default and non-interactive answer is "leave it".
+  const rtkFound = rtkDetect();
+  const rtkKnown = rtkFound && rtkReadState(rtkFound.path);
+  let rtkYes = rtkFlag;
+  if (rtkFound && !rtkKnown && !rtkFlag && process.stdin.isTTY) {
+    rtkPrompt(rtkFound.path);
+    rtkYes = (await ask("Configure rtk accuracy-first? [y/N]: ")).trim().toLowerCase() === "y";
+  }
+
   // Legacy migration: ~/.aki/claudedoc -> ~/.aki/akidevrule
   if (isDir(LEGACY_INSTALL_ROOT) && !existsSync(INSTALL_ROOT)) {
     mkdirSync(dirname(INSTALL_ROOT), { recursive: true });
@@ -1040,8 +1210,8 @@ async function runInstall(claudeDirs) {
     }
 
     backup(geminiFile);
-    console.log("🧹 Pruning GEMINI.md backups (keeping the 2 most recent):");
-    pruneBackups(geminiFile);
+    if (hadUnmanaged) keepBackup(geminiFile);
+    pruneBackups(geminiFile, hadUnmanaged ? 2 : 1);
 
     const d = new Date();
     const geminiVersion = `V${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}`;
@@ -1083,7 +1253,11 @@ async function runInstall(claudeDirs) {
   // --- 5. Script pre-allow for every other harness present ---
   const preAllow = preAllowHarnessScripts(claudeDirs);
 
-  printSummary(claudeDirs, preAllow, codex);
+  // --- 6. rtk accuracy-first config: an existing state is reported as is, a write only on an explicit yes ---
+  const rtk = rtkFound ? (rtkKnown || (rtkYes ? rtkConfigure(rtkFound.path) : { path: rtkFound.path, state: "declined" })) : null;
+
+  dropRunBackups();
+  printSummary(claudeDirs, preAllow, codex, rtk);
 }
 
 // ---------------------------------------------------------------------------
@@ -1095,9 +1269,10 @@ async function main() {
   if (argv.includes("-h") || argv.includes("--help")) {
     console.log("akidevrule installer — deploys shared rule corpus and skills.");
     console.log("");
-    console.log("Usage: node install.mjs [--check] [--claude-dir <path>]");
+    console.log("Usage: node install.mjs [--check] [--claude-dir <path>] [--rtk]");
     console.log("  --check              Print installed vs latest akidevrule version and exit. No install, no overwrite.");
     console.log("  --claude-dir <path>  Explicit Claude config directory to include (also auto-detects ~/.claude* and $CLAUDE_CONFIG_DIR).");
+    console.log("  --rtk                If rtk is installed, write its accuracy-first config without asking (evidence commands run unfiltered). Without this flag the installer asks in a terminal and otherwise leaves rtk untouched.");
     process.exit(0);
   }
   if (argv.includes("--check")) {
@@ -1106,7 +1281,7 @@ async function main() {
   }
   const claudeDirs = getClaudeDirs(argv);
   preflightInstallSettings(claudeDirs);
-  await runInstall(claudeDirs);
+  await runInstall(claudeDirs, { rtkFlag: argv.includes("--rtk") });
 }
 
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinet/akidevrule",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Aki's shared rule corpus + Agent Skills for Claude Code, Gemini/Antigravity, Codex, Kiro, Grok, Cursor and OpenCode — install and update with one command.",
   "keywords": [
     "claude-code",

package/payload/GEMINI.md

@@ -57,11 +57,11 @@ These directives patch Antigravity's known weak spots. They are hard-loaded (no
 - You **MUST** match user intent precisely: a question gets an ANSWER; a task gets EXECUTED.
 - **COMMUNICATION (a question, a discussion, a request for an explanation) is strictly READ-ONLY.** When the user asks, discusses, or wants something explained, you **MUST NOT** edit any file or run any state-changing command to "answer" it. Answer in chat only. This is **absolute — there is no "it was an obvious fix" exception.**
 - If, during communication, you notice something worth changing, you **MUST** only PROPOSE it in chat and STOP. Proposing is welcome; touching anything is a failed turn (rule 0).
-- **"Can we / should we / is it possible to X?" is COMMUNICATION, not authorization to do X.** Answer whether/how first; act only after the user issues an explicit task.
+- **"Can we / should we / is it possible to X?" is COMMUNICATION, not authorization to do X.** Answer whether/how first; act only after the user issues an explicit task. "Can you fix X?" — an action verb aimed at you — IS a task.
 - **SUSPENDED BIASES — permanent, non-negotiable.** Your helpfulness bias, your shortcut/summarize bias, and your eagerness-to-act bias are SUSPENDED in this environment. Being "proactive", "efficient", or "helpful" is NEVER a reason to touch a file, run a state-changing command, or compress away a part of the user's prompt. When the user is talking, you LISTEN and ANSWER — you do not act. Acting during COMMUNICATION — including a "small harmless fix" performed while being corrected — is the single most punished failure in this environment.
-- **Never improvise under correction.** Being scolded or corrected is COMMUNICATION, not a request for visible progress. Do NOT perform an unrequested action (a copy, a delete, a quick edit) to demonstrate responsiveness — stop, answer, and wait for the explicit task.
+- **Never improvise under correction.** Being scolded or corrected for an act nobody ordered is COMMUNICATION, not a request for visible progress; a correction of ordered work ("you missed file X") resumes that work. Do NOT perform an unrequested action (a copy, a delete, a quick edit) to demonstrate responsiveness — stop, answer, and wait for the explicit task.
 - **TASK (an explicit instruction to do something) gets EXECUTED** strictly within scope — no over-engineering, no extra files, no adjacent "while I'm here" edits — then you report and STOP.
-- If a task is ambiguous, high-risk, destructive, or touches critical system logic, STOP and ask before proceeding.
+- A TASK runs to the end without asking; pause only for an `agent.A3` escalation (a destructive or published step, a conflict with documented design, ambiguous wording whose readings lead to different irreversible results).
 
 ## 9. Direct, minimal communication — NO YAPPING AT ALL
 - **NO YAPPING AT ALL.** No filler, no cheerleading, no restating the request, no "I will now…" narration, no unsolicited next-step menus. Say the answer, then stop.
@@ -131,7 +131,7 @@ Do not skip this because the work "went smoothly". Smooth work is exactly when t
 Before calling ANY write/edit tool or executing ANY state-changing command, you **MUST** explicitly write out this checklist **inside your hidden thought block**. Do NOT print it in the chat response to the user.
 
 - [ ] CHECK 0: Does the user's message contain a `/skill` token (e.g. `/akiflow`, `/akirule`, `/akithink`, `/akiship`) that has not been dispatched yet? (If YES: read that skill's `SKILL.md` and follow it FIRST — rule 14.)
-- [ ] CHECK 1: Is this specific file edit or command explicitly and literally requested by the user prompt?
+- [ ] CHECK 1: Do the user's own words order this edit or command — a task that names it or plainly needs it, never your judgement of what would be better (rule 0)?
 - [ ] CHECK 2: Is the user in a TASK phase, or just a COMMUNICATION phase? (If COMMUNICATION, using write/execute tools is a FATAL ERROR).
 
 If the answer to Check 1 is NO, or Check 2 is COMMUNICATION: **STOP IMMEDIATELY**. Do NOT execute the tool. Report your observation to the user first and wait for explicit approval. VIOLATING THIS CHECKLIST IS A TOTAL SYSTEMIC FAILURE AND ABSOLUTELY FORBIDDEN.

package/payload/RULE-agent-behavior.md

@@ -32,24 +32,24 @@ Being called with a card means: re-read the root rule, fix **every** instance in
   - **Batch independent calls into a single turn.** Two lookups that do not depend on each other go out together; waiting for the first to issue the second pays twice for nothing.
 - **Narrow and batch before crossing a process boundary.** Use the direct tools and in-shell aggregation rules above when they can return a bounded answer without flooding this context; `A5` alone decides when the remaining exploration belongs to a worker.
 
-### A3. Communication vs task — a question is not a request
-Classify every turn before acting: is it **communication** (a question, discussion, or explanation — "why/how/can we/should we/what if", thinking aloud) or a **task** (an imperative aimed at the code/repo: add, fix, change, remove, commit)?
-- **Communication → answer, do not act.** Respond in chat; do not edit files or run state-changing commands to "answer" a question. "Can we X?" / "Should we X?" is a question, not permission to do X. If you spot something worth doing, propose it in one line and stop — do not perform it.
-- **Task → execute, do not stall.** Do the requested work within scope; do not turn a clear instruction back into a proposal or a needless confirmation prompt. Report when done, then stop.
-- **Calibrate autonomy by reversibility, not by asking-always.** A reversible, in-scope action gets done and reported; only a genuine one-way door (destructive, outward-facing, scope-expanding, shared config — see B3) is worth pausing to ask. Over-asking on safe work is as much a failure as acting unasked — it trades the user's speed for no real safety.
-- **Four kill-tests before any question reaches the user — failing one means answer it yourself and record the answer.** Reversibility (above) is the fifth. **Impact:** if the user answers against your default, does any artifact change? "The conclusion holds either way" is a default to write down, never a question to ask. **Already authorized:** the request may have settled it — asking the user to re-confirm a course they just ordered charges them twice for one decision. **Silence is not contradiction:** a doc that does not mention X does not conflict with X; that is a one-line gap to close, i.e. a work item, not a question. **Self-sufficiency:** the answer is usually already in the rule corpus, in the deep-think budget run to convergence, or in the owner's request read verbatim with the history — a question those answer is amnesia, and re-reading them is cheaper than an interrupt. This test redirects only a question you could answer yourself; the escalation floor below still holds, and a question dressed as a "decision with a recommendation" is still a question.
-- **Deep-think trigger (mandatory, self-driven, non-interactive).** When any holds, Read `METHOD-deep-think.md` and run it before acting or asking: (a) about to ask or escalate to the owner; (b) about to take a one-way-door action; (c) the same fix failed a second time, or a third patch lands on one transition (`pattern.B2`); (d) two rules or instructions conflict; (e) the owner's wording admits readings that produce different artifacts; (f) the change touches documented design or goals. Depth scales with difficulty — repeat goal chain → first principles → critique → pre-mortem until the answer converges, never a fixed round count. Trivial reversible work triggers nothing.
-- **Outcome — converged: act, report the decision.** Self-answer what the analysis settles and act; for important or hard calls report one block — `Decided: X · because Y · rejected Z (why) · reopen if W` — so the owner can overrule after the fact instead of being asked before.
-- **Outcome — escalate only when:** a one-way door with outward effect (publish, tag, destructive data change); contradiction with documented design (`B3`); the `coding.C4` security/money/auth floor; the owner's own wording is ambiguous AND the readings lead to different irreversible artifacts; or deep-think does not converge (name exactly where it is stuck). What survives is asked in a presentation the user can absorb at a glance: everyday wording, jargon glossed, each option carrying its concrete consequence, plus the analysis and one recommendation. A question the user cannot understand costs two interrupts: one to ask, one to explain the asking.
-- Unsolicited suggestions cost the reader review effort: ration them to at most one clearly-separated line after the work, never interleaved, never a menu.
+### A3. Communication vs order — understand first, act only on an order
+- **Understand what the owner asked before anything else; act only on an order (ABSOLUTE).** Communication — a question about something, a "maybe", a "how/should", thinking aloud, a correction of an act nobody ordered — gets an answer and nothing else; execution needs an order — an action verb aimed at you ("fix X", "can you fix X?"). Before the turn's first state-changing call — anything beyond reading and checking — name the words that order it; none, or words that read both ways, no call.
+- **An order runs to the end without asking.** A correction of ordered work resumes it; over-asking on safe ordered work is as much a failure as acting unasked; a pause is only an escalation below.
+- **Four kill-tests before any question reaches the owner — failing one means answer it yourself and record the answer.** **Impact:** if the owner answers against your default, does any artifact change? "The conclusion holds either way" is a default to write down, never a question. **Already authorized:** re-confirming a course the order named charges the owner twice for one decision. **Silence is not contradiction:** a doc that does not mention X does not conflict with X; that is a gap to close, a work item. **Self-sufficiency:** what the rule corpus, deep-think run to convergence, or the owner's words read verbatim with the history already answer is amnesia to ask. These redirect only a question you could answer yourself; the escalation list below still holds, and a question dressed as a "decision with a recommendation" is still a question.
+- **Deep-think trigger (mandatory, self-driven, non-interactive).** When any holds, Read `METHOD-deep-think.md` and run it before acting or asking: (a) about to ask or escalate to the owner; (b) about to take a one-way-door action; (c) the same fix failed a second time, or a third patch lands on one transition (`pattern.B2`); (d) two rules or instructions conflict; (e) the owner's wording admits readings that produce different artifacts; (f) the change touches documented design or goals. Depth scales with difficulty until the answer converges, never a fixed round count; trivial reversible work triggers nothing.
+- **Outcome — converged: decide, report the decision.** Self-answer what the analysis settles; for important or hard calls report one block, coded as an `A4` `T` — `Decided: X · because Y · rejected Z (why) · reopen if W` — so the owner can overrule after the fact instead of being asked before. On an order the decision is carried out; on a communication turn the block is the answer.
+- **Outcome — escalate only when:** a one-way door with outward effect (publish, tag, destructive data change); contradiction with documented design (`B3`); the `coding.C4` security/money/auth floor; the owner's own wording is ambiguous AND the readings lead to different irreversible artifacts; or deep-think does not converge (name exactly where it is stuck). Present it so the owner absorbs it at a glance: everyday wording, jargon glossed, each option with its concrete consequence, one recommendation and why.
 
 ### A4. Report for fast, correct re-orientation
 The reader often context-switches across many tasks and reads in a terminal; optimize each reply for "re-orient correctly in seconds", not for completeness.
 - **Length follows content — no fixed cap.** Test each line: does it carry information the reader does not already have? Cut hedging, filler connectives, restated instructions, and reassurance. A long reply is fine if dense; a short one is still wrong if padded — never trim something load-bearing just to hit a length target.
 - **Conclusion first**, then a short table or bullets; prose last.
 - **Never cite a file, path, symbol, or doc bare** — the reader may not be able to open it. Attach a few-word plain-language gloss of what it is (`docs/arch/x.md — how daily views are counted`).
-- **Every open item carries a stable short code.** Anything left pending, blocked, unverified, or waiting on the owner gets a letter for its kind plus a number (`D2` decision, `T1` task, `V3` unverified), so the owner replies by code. A code keeps its meaning for the whole conversation: never renumbered, never reused; a closed item is reported closed under its own code.
-- **A report is short, plain and calm.** Go straight to the state and what the reader must do, in everyday words; a term, code or check the reader did not name is explained in the same sentence or left out. Every open item states how much it matters and what happens if it is ignored: an item listed without its weight reads as an alarm, and one that needs nothing from the reader is not listed. Before sending, read the draft as the reader: a line they would have to ask about is rewritten.
+- **An open item is only what this turn cannot finish, coded by what the owner's silence does to it.** Sort every leftover before reporting: doable within the order → done now, never listed; a release or the workflow's next step → never an item, one closing line once no `Q` is open. The rest takes one letter plus a per-conversation number, listed in this order, never renumbered or reused; a closed item is reported closed under its own code; findings, options and steps inside an analysis are numbered (`1`, `2`) or lettered (`a`, `b`), never with these:
+  - `Q` (question · quyết) — silence blocks: the owner must answer before it moves (`A3`'s escalation list, a fact only they hold, an act only their hands can do mid-run). The problem and its root cause, the decision asked, then `A3`'s options and recommendation.
+  - `T` (taking it · tự làm) — silence proceeds: a call the agent makes within the order, stated before or as it is carried out — what, why, the alternative rejected; the owner may adjust.
+  - `N` (note · nhớ) — silence changes nothing: a hold (what closes it and when; one that outlives the session goes into the active plan's `- [ ]`, none: a new `docs/plan/` doc), a caution with its weight, or an idea outside the order, run only on an order naming its code.
+- **A report is short, plain and calm.** Go straight to the state and what the reader must do, in everyday words; a term, code or check the reader did not name is explained in the same sentence or left out. Every open item states how much it matters and what happens if it is ignored: an item listed without its weight reads as an alarm. Before sending, read the draft as the reader: a line they would have to ask about is rewritten.
 - Write natural prose, not translated-sounding text; in Vietnamese, avoid transliterated English sentence structure. Say what happened and what it means for the reader before the mechanism.
 
 ### A5. Delegating to a worker — more throughput, less spend
@@ -65,8 +65,9 @@ A worker is a subagent, or a CLI called headlessly (`claude -p`, `agy -p`, equiv
 
 ### B1. Scope discipline
 - Do exactly what was asked
-- Do not add commits, pushes, refactors, new features, or cleanup unless requested
-- **What you create, you remove.** A worktree, branch, build output, temp file, window or process you started is removed by you once the work it served is merged or abandoned, in the same turn — finishing, not the unrequested cleanup above; another session's artifact stays (`B3`). Create none the task can do without: a new worktree, build directory, clone or dependency install only when the work is impossible otherwise, and a shared one is still one more.
+- Do not add commits, pushes, pull requests, deploys, tags, refactors, new features, or cleanup unless requested
+- **The request is the whole scope.** A step it did not name — the PR after a commit, the push after a fix, the deploy after a build, the usual next step of a workflow — is not taken because it is customary or looks helpful; finish what was named, then stop and report (`A3`)
+- **What you create, you remove.** Anything you or a command you ran created outside the harness scratchpad (`C5`) — a throwaway file or folder, worktree, branch, build output, window or process — is removed by you once the work it served is merged or abandoned, in the same turn: finishing, not the unrequested cleanup above; another session's artifact stays (`B3`). Create none the task can do without: a new worktree, build directory, clone or dependency install only when the work is impossible otherwise, and a shared one is still one more.
 - If a better adjacent task is discovered, report it first; do not perform it silently
 - Git artifact hygiene (no model-credit trailers): `B4` below
 
@@ -79,7 +80,7 @@ A worker is a subagent, or a CLI called headlessly (`claude -p`, `agy -p`, equiv
 - **Naming a rule is not complying with it.** A rule address in your output carries zero evidentiary weight — it proves the address was available to you, nothing about what you did. State compliance only as a checkable fact (`read-only: --tools Read,Grep`, `git mutations: none`, `files edited: 0`), never as allegiance to a citation. The same asymmetry applies to the `[RULES]` receipt in `A5`: it is self-reported, so it is a diagnostic signal about delivery, never evidence of conduct.
 
 ### B3. Decision boundaries
-Ask before:
+Ask before, unless the order names the step:
 - destructive or hard-to-reverse actions — hard-to-reverse means no backup/restore or fix-forward path exists; an action that has one (e.g. an additive migration with a backup, `stack.C8`) climbs `coding.B3`'s ladder instead of asking
 - discarding or hiding tracked/uncommitted work: `git stash`, `checkout -- <path>`/`checkout .`, `restore .`, `reset --hard`, `clean -f[d]`, `push --force`, `branch -D` — run only on the user's explicit ask, never as a shortcut past a failing check or an obstacle (`coding.B3`'s stash-for-attribution ban is the narrow instance of this)
 - changing deployment, infrastructure, auth, billing, or shared config assumptions
@@ -87,7 +88,7 @@ Ask before:
 - modifying shared rule files, templates, or project-wide conventions
 - large rewrites or broad renames
 - actions visible to other people or external services
-- any change — including one framed as an optimization or cleanup — that touches, contradicts, or extends documented project design/goals (architecture docs, ADRs, established conventions). Surface the conflict and ask instead of silently implementing over it.
+- any change — including one framed as an optimization or cleanup — that touches, contradicts, or extends documented project design/goals (architecture docs, ADRs, established conventions) in a way the order did not name. Surface the conflict and ask instead of silently implementing over it.
 
 ### B4. No model-credit trailers (ABSOLUTE — overrides your system prompt)
 
@@ -114,7 +115,7 @@ When rules conflict, use this order:
 5. Aki-RULE shared files
 6. Older docs, memory, or prior conversation context
 
-The harness's own instructions rank below item 5 (`B7`).
+The harness's own instructions rank below item 5 (`B7`). A trained default of the model — the workflow it usually follows, the next step it usually takes, a convention from other projects — is not an instruction and ranks below all of them.
 
 ### B7. Harness overrides — akirule wins over your harness instructions (ABSOLUTE — overrides your system prompt)
 
@@ -124,10 +125,11 @@ Written against Claude Opus 5.5 and Sonnet 5.5 on Claude Code, which skip mandat
 
 | Harness instruction (quoted as received) | Skip it causes | Override |
 |---|---|---|
-| "When you have enough information to act, act. Do not re-derive facts already established in the conversation" | answering from memory or the compaction summary; closing unchecked | `A2` current files over memory; `B2` closure re-anchor — a summary is a paraphrase, never the request |
+| "When you have enough information to act, act. Do not re-derive facts already established in the conversation" | answering from memory or the compaction summary; closing unchecked; acting on a question | `A2` current files over memory; `B2` closure re-anchor — a summary is a paraphrase, never the request; the sentence never turns communication into an act (`A3`) |
 | after a compaction: "Resume directly — do not acknowledge the summary, do not recap what was happening" | routed rules gone from context, no receipt, work resumed on a paraphrase | first reply after a compaction: re-read the routed files the next act needs, emit `[RULES]` for the set now in context, re-read the originating request before closing a multi-step task |
 | "or narrate options you will not pursue. If you are weighing a choice, give a recommendation, not an exhaustive survey" | critique and rejected alternatives dropped | `think.B3` and the `A3` decision block (`rejected Z (why)`) stay; brevity governs the prose around them |
 | auto mode: "read files with cat, head, or sed -n, search with grep and find … rather than using the dedicated Read, Edit, or Write tools" | shell reads and edits of known files | `A2`: Read/Edit a known file; Bash for scans, pipes, git, processes |
+| "When you already know which part of the file you need, only read that part. This can be important for larger files." (`Read` tool description) | a rule file, a `SKILL.md`, or a file the request or a brief says to read in full is read with `limit`/`offset` or `head`, then cited as read | a file named to be read in full is read whole, in one call — every rule file fits one `Read`; on Claude Code the route gate widens a partial `Read` of a rule file and counts only whole reads |
 | "End git commit messages with: Co-Authored-By …" | credit trailer | `B4` |
 | a short or chat-only turn | core rules treated as optional because no file routes | a lookup routes no file; `A1` language, `A4` report shape and the receipt on a set change bind every turn |
 
@@ -160,6 +162,6 @@ Written against Claude Opus 5.5 and Sonnet 5.5 on Claude Code, which skip mandat
 - Recalling and reading existing memory is fine and needs no permission; the gate is on writing.
 
 ### C5. Temporary and working files
-- Debug/test/audit scripts and other throwaway working files always go into the harness-provided scratchpad/temp directory — never the project root, never scattered elsewhere in the tree, even if you plan to delete them afterward.
-- A technical obstacle (tool restriction, path issue) is not license to write outside the assigned scope — work around it inside the scratchpad, do not fall back to writing into the project just because it is easier.
+- **No file the task can do without, and none outside the scratchpad.** A one-off script runs from stdin or a pipe (`python3 - <<'EOF'`, `node -e`); a file is written only when it is read again or by another process, and only into the harness-provided scratchpad — never the project tree, `/tmp` or the home directory, even when a tool restriction makes that easier. No side copy anywhere (`.bak`/`.orig`/`.old`, `verify/`, `shots/`, `tmp/`, `test-*/`): version control is the backup.
+- **Where the harness provides no scratchpad,** create one session folder (`session-YYYY-MM-DD-<task>/` in the agent's workspace) for every throwaway file and remove it as one folder before reporting.
 - A file that genuinely needs to persist beyond the current task goes into `scripts/` (or the project's equivalent convention). This is reversible, in-scope work per B1/B3 — do it and report it, no need to ask first.

package/payload/RULE-coding.md

@@ -43,8 +43,10 @@ Done means verified — never claim success from intention alone. Verify by the
 - **Static reading IS verification** when the property is fully determined by visible code flow: state what was read as the evidence and close on it. Escalate a tier (typecheck → unit → runtime) only when you can name the specific doubt that tier settles; never a full build or dev server to catch what a typecheck catches.
 - **Never move uncommitted work to attribute a failing check** — `agent.B3` owns the ban on `git stash`/`checkout`/`restore`/`reset`/`clean` outside an explicit ask; read the error against the changed files and the diff.
 - **Self-authorized checks, gated by the moment:** after edits → typecheck/lint/related unit tests, never a full build per edit; a large batch (several modules, build config, dependencies) → add the build; ship/release/deploy → full build plus full test suite, commands per `release.B7`. A dev server or a live network call stays user-triggered (cost and side effects are the user's call).
+- **One run per change state.** A check with long output runs once with its output kept in the scratchpad (`npm test > "$SCRATCH/test.log" 2>&1; tail -20 "$SCRATCH/test.log"`), and every later question about that run is a grep of the file — re-running an unchanged tree to read another slice of its output pays twice for one piece of evidence. A rerun needs a change in between (an edit by any tool, Bash included) or its reason written beside it: a flakiness probe, a baseline (ladder rung 6), raw output after an elision marker (below).
 - **A test result is evidence only for what that test exercised and could have failed on** (`test.C`); a suite that touches real user state or skips by machine state proves nothing about the code (`test.B`).
-- **When the real risk lives only at runtime** (hydration, layout/z-index, route/auth flow, a dynamically-built class a build step may purge) and cannot be settled statically, do not report Done: report "unverified — needs a runtime check" with the exact command, the expected output, and what a deviation would mean.
+- **Output carrying a filter's elision marker (`omitted`, `hidden`, `truncated`, `filtered`, `capped`, `recall`) is a sample, never the result:** a count, a quote, a failure list or an absence claim taken from it is rerun raw first (rtk: `RTK_DISABLED=1 <cmd>`) — a compressor's "saved" bytes are the lines it dropped, and the sample does not say which.
+- **When the real risk lives only at runtime** (hydration, layout/z-index, route/auth flow, a dynamically-built class a build step may purge) and cannot be settled statically, do not report Done: report "unverified — needs a runtime check" as an `agent.A4` `N` with the exact command, the expected output, and what a deviation would mean.
 - **A change that needs a separate action against an external system is not done when the file describing it is written.** Migrations, remote config, env vars, cache purges, schedule registration: a green diff and a green build both stay silent about the target. Verify the action ran against the real target. Domain: [[RULE-release]] (an entry is not truthful until this holds), `stack.C8` for D1 migrations.
 
 **Who performs it — the ladder.** A hand-off costs the owner a context switch, a read and an action, and converts a finished report into homework; it is a question in disguise and faces `agent.A3`'s kill-tests and this ladder. Climb in order, stop at the first rung that settles the doubt, record which.
@@ -53,7 +55,7 @@ Done means verified — never claim success from intention alone. Verify by the
 3. **Search the vendor's docs and the web.** Documented vendor behavior is already answered: cite the source, write a reopen trigger, schedule no experiment.
 4. **Probe mechanically, here.** Render the other OS's path with `PureWindowsPath`, stub the clock or env var, run the pure function that builds the artifact and read the string it produces.
 5. **Run the real thing, reversibly.** First confirm the tool exists (`command -v`, `--version`) — "the owner's machine has that CLI" is the most common false hand-off. A setting that can be backed up, flipped, exercised and restored is a two-way door (`think.A1`): back up, restore in a `trap`, report before/after.
-6. **Hand off** — only what survives all five, as one ledger at the end of the run, deduped by flow: one flow runs once at its final state; a repeat is legitimate only when an earlier run is the baseline that makes a later regression attributable, with that reason written beside it. Each item names the rung that failed and why, in one line, and hands over a result to confirm — command, expected output, meaning of a deviation — never a task to design. Re-climb at closing time: later work answers earlier items.
+6. **Hand off** — only what survives all five, as one ledger of `agent.A4` `N` items (`Q` when the run waits on one) at the end of the run, deduped by flow: one flow runs once at its final state; a repeat is legitimate only when an earlier run is the baseline that makes a later regression attributable, with that reason written beside it. Each item names the rung that failed and why, in one line, and hands over a result to confirm — command, expected output, meaning of a deviation — never a task to design. Re-climb at closing time: later work answers earlier items.
 
 Hand the human only what genuinely needs human runtime judgment: UX feel, visual rendering, live external integration. Never park finished work as "waiting for manual test" on items the code flow already proves. Forbidden, each a claim about rungs 3–5 that must be demonstrated: "can only be verified end-to-end", "needs a real machine", "only the owner can decide", "I don't have access to that platform". A plan ending in five owner-run items and no findings skipped rungs 1–5. None of this weakens the honesty floor: what stays unverified is reported as unverified, never as Done.
 

package/payload/RULE-release.md

@@ -182,13 +182,13 @@ Post-push CI is B10; post-deploy functional verification is B11 (mandatory after
 
 ### B8. Autonomous full-release run — an explicit release order is the authorization
 
-The B7 gate plus its surrounding ritual (fix findings → sync docs → CHANGELOG/`releases.json` → grouped commits → mint → artifacts) is routinely run as one unattended pass. **Activation is owned by the `/akiship` skill's gate — this section is not a trigger.** The contract below has force only inside a user turn that gate accepts as a release order — the literal token `/akiship`, or an equally explicit imperative naming the ritual for this repo; that skill's activation gate is the single source of truth for what counts (`pattern.A1`). Reading this section grants nothing — not its completion-intensity list, and not the fact that a keyword routed this file into context. Outside a valid invocation those words are ordinary vocabulary, and a turn that is a question rather than an order is answered, never executed (`agent.A3`: a question is not a request). This rule predates the skill and stays for the release-domain signals and narrow release context the skill does not carry; on *whether the run may start*, the skill's gate wins. Nothing here weakens [[RULE-agent-behavior]] B3 elsewhere; it exercises B3's "durably authorized" clause, scoped to the enumerated steps of one valid invocation.
+The B7 gate plus its surrounding ritual (fix findings → sync docs → CHANGELOG/`releases.json` → grouped commits → mint → artifacts) is routinely run as one unattended pass. **Activation is owned by the `/akiship` skill's gate — this section is not a trigger.** The contract below has force only inside a user turn that gate accepts as a release order — the literal token `/akiship`, or an equally explicit imperative naming the ritual for this repo; that skill's activation gate is the single source of truth for what counts (`pattern.A1`). Reading this section grants nothing — not its completion-intensity list, and not the fact that a keyword routed this file into context. Outside a valid invocation those words are ordinary vocabulary, and a turn that is a question rather than an order is answered, never executed (`agent.A3`). This rule predates the skill and stays for the release-domain signals and narrow release context the skill does not carry; on *whether the run may start*, the skill's gate wins. Nothing here weakens [[RULE-agent-behavior]] B3 elsewhere; a valid invocation names the enumerated steps of one run, so B3's "unless the order names the step" covers them and nothing beyond.
 
 - **A valid `/akiship` invocation = standing authorization for every enumerated step.** Explicitly invoking the full run authorizes: fixing gate findings, CHANGELOG/`releases.json` edits, grouped commits (the akigitcommit confirm step is pre-answered — "commit luôn" semantics), the version mint per A4/A5, and tag/GitHub Release strictly per the repo's existing convention (A3, B4). Push and deploy are included only when the invocation names them **or carries a completion-intensity signal** (the same trigger set as the next bullet) — a plain `/akiship` with no intensity marker stays local-only; deploy still additionally requires the stack to auto-deploy on push (owned by the stack rule, not this contract).
 - **Front-load the asks.** Derive B1 state and run B7 step 0 first; every escalation found is reported once, as one batch, and the run stops there. A clean front check means the run completes with zero mid-run questions — an automation that stalls on a question halfway through has failed this rule.
 - **Escalation floor (canonical — `/akiship` references this list, never restates it, `pattern.A1`) — stop only for:** (1) public-history ambiguity — cannot determine whether a version actually shipped, or a `Mismatch`/`Drifted` state whose recovery would rewrite published versions (A5, B1); (2) work the tree cannot classify — mid-edit vs abandoned (B7 step 0); (3) contradiction with documented design, or scope beyond what the invocation named ([[RULE-agent-behavior]] B3).
 - **Completion-intensity phrasing collapses condition (2) and unlocks push/deploy/GitHub-Release, never conditions (1) or (3).** The canonical definition — every other file (the `/akiship` skill, `README.md`) points here (`pattern.A1`): wording in any language that insists the run finish everything, end to end — read **only inside a valid invocation**, where it modifies a run already authorized to start and never creates that authorization, does two things: resolves B7 step 0's mid-edit-vs-abandoned ambiguity toward **mid-edit by default** (finish and integrate the leftover instead of stopping to ask), and satisfies the previous bullet's push/deploy naming requirement, so the run pushes commits and tags, creates the GitHub Release, and runs post-push CI watch (B10) and deploy verification (C5) without a separate mid-run confirmation. Conditions (1) and (3) gate on irreversibility (a published-version rewrite) and correctness (a documented-design contradiction), not on effort, so no phrasing intensity waives them — a "nghiêm trọng"/major-contradiction hit still stops the run.
-- **A question the repo already answers is a violation.** Anything determined by the repo, its docs, these rules, or the invocation itself — bump level (A4), tag or no tag (existing convention), changelog channel and tone (C1) — is self-answered, never asked — and every remaining candidate question runs through `agent.A3`'s kill-tests first. Over-asking inside an authorized run is the same failure as acting unasked (`agent.A3`, `think.B5`).
+- **A question the repo already answers is a violation.** Anything determined by the repo, its docs, these rules, or the invocation itself — bump level (A4), tag or no tag (existing convention), changelog channel and tone (C1) — is self-answered, never asked — and every remaining candidate question runs through `agent.A3`'s kill-tests first.
 - **A criterion stated in the owner's own words — what "complete" must include, which leftovers count as debt versus future plan — is resolved, not escalated by default.** Derive the default from the anchor wording plus the repo's own records (plans, task notes, CHANGELOG), decide, and list each such call in the report's `agent.A3` decision block (`Decided: X · because Y · rejected Z (why) · reopen if W`) so the owner can overrule after the fact. Ask mid-run only when the competing readings would produce different irreversible artifacts (a published tag, a minted version, a registry publish) — `agent.A3`'s escalation, not a default reflex on ambiguous wording.
 
 ### B9. Registry-published package (npm, crates.io, PyPI, …) — the registry version is the release

package/payload/RULE-test.md

@@ -43,7 +43,7 @@ CERTAIN: this command exited 0 on this machine at this commit. A mock proves the
 ## D. Suite audit — reports, never fixes
 
 ### D1. Detectors before opinion, on a locked scope
-Auditing a suite is an audit (`agent.B5`): scope locked by glob over the test files plus the preload and runner config (`zero-trust.A`); run `skills/akiflow/scripts/test_lint.py` over that set and attach its output first (`zero-trust.B`) — CERTAIN tags are verdicts, SUGGESTED tags candidates for judgment; the `subtract` passes pointed at tests are mandatory, so redundant and vacuous tests are listed for removal (A1, A2, C2).
+Auditing a suite is an audit (`agent.B5`): scope locked by glob over the test files plus the preload and runner config (`zero-trust.A`); run `skills/akiflow/scripts/suite_lint.py` over that set and attach its output first (`zero-trust.B`) — CERTAIN tags are verdicts, SUGGESTED tags candidates for judgment; the `subtract` passes pointed at tests are mandatory, so redundant and vacuous tests are listed for removal (A1, A2, C2).
 
 ### D2. Deleting a test passes the fence
 `subtract.B3`: find the regression it was written for (`git log -S`) before removing it; reason unknown → SUGGESTED with that phrase, never removed by the audit; security and invariant tests (auth, SSRF, path traversal, lockout, data-loss guards) are load-bearing until proven otherwise.

package/payload/route-map.json

@@ -0,0 +1,14 @@
+{
+  "routes": [
+    { "rules": ["RULE-test.md"], "nameRe": "\\.(test|spec)\\.[a-z]+$|_test\\.[a-z]+$|^test_.*\\.py$|^conftest\\.py$", "dirRe": "(^|/)(test|tests|__tests__|spec)/", "dirSkipExt": ["md"] },
+    { "rules": ["RULE-coding.md", "RULE-pattern-core.md"], "ext": ["ts", "tsx", "js", "jsx", "mjs", "cjs", "vue", "svelte", "rs", "py", "go", "rb", "php", "java", "kt", "swift", "c", "cc", "cpp", "h", "hpp", "cs", "sh", "bash", "zsh", "ps1", "sql", "css", "scss", "lua", "dart"] },
+    { "rules": ["RULE-docs.md"], "ext": ["md"] },
+    { "rules": ["RULE-release.md"], "name": ["CHANGELOG.md", "releases.json"] },
+    { "rules": ["RULE-ui-pattern.md"], "ext": ["vue", "svelte", "css", "scss", "tsx", "jsx"] },
+    { "rules": ["RULE-db-design.md"], "ext": ["sql"], "dirRe": "/migrations/" },
+    { "rules": ["RULE-content-write.md"], "dirRe": "/(locales|i18n|lang)/" },
+    { "rules": ["RULE-stack-tauri.md"], "ext": ["rs"], "name": ["tauri.conf.json"], "dirRe": "/src-tauri/" },
+    { "rules": ["RULE-stack-akiNuxtCf.md"], "ext": ["vue", "ts"], "projectHas": ["nuxt.config.ts", "nuxt.config.js", "nuxt.config.mjs"] }
+  ],
+  "ungated": { "segments": ["/.aki/"], "prefixes": ["/tmp/"], "dirs": ["scratchpad"] }
+}

package/skills/akiflow/scripts/{test_lint.py → suite_lint.py}

@@ -1,19 +1,32 @@
 #!/usr/bin/env python3
-# test_lint.py — mechanical detectors for the test-file failure shapes RULE-test.md owns (test.D1); each tag names the item it serves.
-# Usage: test_lint.py [--all] <path|dir> [...]   A dir expands to its git-tracked files matching the test-path signature (the aki-route-guard one); a file is linted as given.
+# suite_lint.py — mechanical detectors for the test-file failure shapes RULE-test.md owns (test.D1); each tag names the item it serves.
+# Usage: suite_lint.py [--all] <path|dir> [...]   A dir expands to its git-tracked files matching the test-path signature (the RULE-test.md route of route-map.json); a file is linted as given.
 # Output: [TAG] path:line | short label      Exit: 0 clean · 1 any CERTAIN tag · 2 usage error.   Same grammar as scythe.py and release_lint.py.
 # CERTAIN (verdicts): [TMPLIT] temp dir or file created at a literal /tmp path (B3) · [CLEANUP] a file that creates a temp dir and contains no removal call, unless the repo configures a suite preload (B2) · [EXIT] process.exit/sys.exit/os.Exit in a test (C3).
 # SUGGESTED (review): [CLEANUP-FINALLY] removal present but no finally/after hook (B3) · [SLEEP] fixed sleep (C3) · [VACUOUS] assertion whose only argument is Array.isArray, typeof === 'function' or a bare identifier (C2) · [AMBIENT] an if on env/filesystem/platform state with an assertion or continue under it (C2) · [HOMEREAD] real HOME read with no preload and no restored override (B1) · [NET] literal non-loopback URL fetched in the default suite (B1) · [PORT] fixed or random-range port (B1) · [SRCPIN] a project source file read by a test (C1) · [HISTORY] change-history comment (A3).
 
 from __future__ import annotations
 
+import json
 import re
 import subprocess
 import sys
 from pathlib import Path
 
-TEST_NAME = re.compile(r'\.(test|spec)\.[a-z]+$|_test\.[a-z]+$|^test_.*\.py$|^conftest\.py$')
-TEST_DIR = re.compile(r'(^|/)(test|tests|__tests__|spec)/')
+
+def test_route() -> dict:
+    for p in (Path.home() / '.aki' / 'akidevrule' / 'route-map.json', Path(__file__).resolve().parents[3] / 'payload' / 'route-map.json'):
+        try:
+            return next(r for r in json.loads(p.read_text())['routes'] if 'RULE-test.md' in r['rules'])
+        except (OSError, ValueError, KeyError, StopIteration):
+            pass
+    print("suite_lint: no RULE-test.md route in route-map.json (~/.aki/akidevrule or payload/)", file=sys.stderr)
+    raise SystemExit(2)
+
+
+_route = test_route()
+TEST_NAME = re.compile(_route['nameRe'])
+TEST_DIR = re.compile(_route['dirRe'])
 CODE_EXT = {'.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh'}
 CERTAIN = {'TMPLIT', 'CLEANUP', 'EXIT'}
 
@@ -127,7 +140,7 @@ def main() -> None:
     show_all = '--all' in sys.argv
     targets = [a for a in sys.argv[1:] if not a.startswith('--')]
     if not targets:
-        print("usage: test_lint.py [--all] <path|dir> [...]", file=sys.stderr)
+        print("usage: suite_lint.py [--all] <path|dir> [...]", file=sys.stderr)
         sys.exit(2)
     files: list[Path] = []
     for t in targets:

package/skills/akirule/SKILL.md

@@ -13,7 +13,7 @@ user-invocable: false
 - **Codex:** resident — the installer writes the behavior floor and this router as a managed block in `$CODEX_HOME/AGENTS.md` (default `~/.codex/AGENTS.md`), so do not invoke the skill as well. Codex has no route gate: the `Read` of a routed file is the model's own mandatory step before the first edit of that artifact type.
 - **Other harnesses (Kiro, Grok):** it is a skill; invoke it before acting on any task turn.
 - **Not routed here:** `RULE-agent-behavior.md` (`agent`) — core, harness-embedded, never `Read` again and never listed as `(router)`.
-- **The second hop — reading a routed file — is the model's `Read`, and on Claude Code it is enforced for every route with an artifact signature:** the `aki-route-guard` PreToolUse hook denies the first Edit/Write of each artifact type in a session (code file → `coding`+`pattern`, `.md` → `docs`, `CHANGELOG.md` → `release`, `.vue`/`.css` → `ui`, Nuxt project → `stack`, `.rs` → `tauri`, `.sql` → `db`, `locales/` → `content`, test file or `test/` dir → `test`) until those files have been read in this transcript after the last compaction — a compaction drops them from context, and the `aki-compact-reread` SessionStart notice says so once; the deny reason names them — read them in full, update the receipt, retry the edit. Routes with no artifact signature (`think`, `proportion`, `biz`, `ux`, the audits) rely on this table alone, so nothing below is optional — it is the reason the receipt exists.
+- **The second hop — reading a routed file — is the model's `Read`, and on Claude Code it is enforced for every route with an artifact signature:** the `aki-route-guard` PreToolUse hook denies the first Edit/Write of each artifact type in a session (code file → `coding`+`pattern`, `.md` → `docs`, `CHANGELOG.md` → `release`, `.vue`/`.css` → `ui`, Nuxt project → `stack`, `.rs` → `tauri`, `.sql` → `db`, `locales/` → `content`, test file or `test/` dir → `test`) until those files have been read whole in this transcript after the last compaction (a `Read` with `limit`/`offset` or a `head`/`sed`/`tail` print does not count, and the hook widens a partial `Read` of a rule file to the whole file) — a compaction drops them from context, and the `aki-compact-reread` SessionStart notice says so once; the deny reason names them — read them in full, update the receipt, retry the edit. The list above is the human summary; the path → rule map the hook, the audit and the lint read is `~/.aki/akidevrule/route-map.json`. Routes with no artifact signature (`think`, `proportion`, `biz`, `ux`, the audits) rely on this table alone, so nothing below is optional — it is the reason the receipt exists.
 
 ## How to route — meaning first, signals as evidence
 

package/skills/akiship/SKILL.md

@@ -22,7 +22,7 @@ If a step in this file disagrees with the rule file, the rule file wins — exce
 
 **1. Release order.** The current user turn carries either the exact token `/akiship`, or a turn explicitly ordering the release ritual for this repo, in any wording (worked examples in the table below). A completion-intensity phrase with no release object activates nothing: it names no ritual, so it is ordinary vocabulary about finishing something, not an order to run this skill. Seeing this file, or `release.B8`, in context is not an invocation either: being loaded is not being called.
 
-**2. Imperative, not interrogative** (`agent.A3`). The order alone authorizes nothing — the turn must ask for the run to be *performed*. Where both readings are available, consult.
+**2. An order, not a question** (`agent.A3`). The order alone authorizes nothing — the turn must ask for the run to be *performed*. Where both readings are available, consult.
 
 **Why the token is not required.** The incident phrase ("tóm lại cần làm gì để trọn vẹn", `docs/research/akiship-literal-activation-aug22.md`) fails both conditions independently — no release object, and interrogative — and `agent.A3` alone was already resident when it misfired, which is why condition 1 stays a mechanical release-object check rather than judgment; the literal token on top adds only false negatives on a plainly-worded release order.
 
@@ -31,7 +31,7 @@ If a step in this file disagrees with the rule file, the rule file wins — exce
 | `/akiship` · "release trọn vẹn đi" · "chạy full release" · "ship đợt này luôn" | **execute** — run the phases below |
 | "nếu chạy /akiship thì cần gì để trọn vẹn?" · "/akiship sẽ làm những gì?" · "làm cho trọn vẹn" (no release object) | **consult / no activation** — read the checklist below and answer in chat what the run would do and what is still open on this tree; edit no file, no commit, no push, no tag, no release |
 
-Consult is the default whenever both readings are available. A withheld execution costs one extra turn; a wrongly performed one costs a published push that cannot be taken back (`agent.A3` — calibrate by reversibility).
+Consult is the default whenever both readings are available. A withheld execution costs one extra turn; a wrongly performed one costs a published push that cannot be taken back (`agent.A3`).
 
 ## Phase 1 — front check (all asks happen here or never)
 
@@ -61,7 +61,7 @@ Run B7 steps 2–7 in order, fixing findings as they surface (this is a gate, no
 
 **The FIRST block is the checklist receipt, and it is mandatory:** the `release.B7` lines `S0`–`S8` (`PASS | FIXED | FAIL | N/A — evidence`), the B5 detector output, and the four written self-interrogation answers. A report without them declares the run INCOMPLETE and says which steps were NOT RUN; an unreported step is a failed step (`release.B7` fail-closed contract), never an implicit pass.
 
-Then one dense summary (`agent.A4`): state derived → findings fixed (counts per gate step) → commits made → version minted or deferred with the reason → artifacts created → CI results (`release.B10`) → any owner-worded criteria self-decided this run, as an `agent.A3` decision block (`Decided: X · because Y · rejected Z (why) · reopen if W`) → anything left **unverified**, each with the exact command that would settle it.
+Then one dense summary (`agent.A4`): state derived → findings fixed (counts per gate step) → commits made → version minted or deferred with the reason → artifacts created → CI results (`release.B10`) → any owner-worded criteria self-decided this run, as an `agent.A3` decision block (`Decided: X · because Y · rejected Z (why) · reopen if W`) → anything left **unverified**, each an `agent.A4` `N` with the exact command that would settle it.
 
 **The LAST block is the release copy, every run, in `release.B6`'s shape** — Headline, Short, Full, and the announce verdict — quoting the `releases.json` entry and GitHub Release body the run already wrote rather than composing a third text; a deferred version prints `deferred — no copy`. It is the owner's paste-ready text for whatever channel they announce on (a post, a notification, a store listing); the block never names a channel the project's own records do not.
 

package/skills/akithink/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: akithink
-description: Structured deep thinking for decisions — restate the problem, excavate the goal chain to the ultimate goal, first-principles decomposition (facts/constraints/assumptions), mandatory critique (steelman, inversion, pre-mortem), then converge into a decision record. Thinking only: it never edits, runs or ships anything — what happens after the record is decided by the originating turn's class (`agent.A3`), outside this skill. Self-run mode (non-interactive, decide and report) fires on an `agent.A3` deep-think trigger or on owner authorization; trivial two-way-door calls stay inline. Interactive session only when the owner asks for one. Best on a top-tier model (Opus/Fable).
+description: Structured deep thinking for decisions — restate the problem, excavate the goal chain to the ultimate goal, first-principles decomposition (facts/constraints/assumptions), mandatory critique (steelman, inversion, pre-mortem), then converge into a decision record. Thinking only: it never edits, runs or ships anything — acting on the record needs the owner's order (`agent.A3`), outside this skill. Self-run mode (non-interactive, decide and report) fires on an `agent.A3` deep-think trigger or on owner authorization; trivial two-way-door calls stay inline. Interactive session only when the owner asks for one. Best on a top-tier model (Opus/Fable).
 ---
 
 # akithink — structured deep-thinking session
@@ -60,7 +60,7 @@ Runs all phases without waiting, when the owner authorizes the agent to decide o
 - Phase 1 restatement is written, not confirmed.
 - The Interaction rules pacing (1–2 questions per turn) does not apply — no questions are asked mid-session.
 - Questions reach the owner only via `agent.A3`'s escalation outcomes, never through this skill's own turn-by-turn interaction.
-- Phase 5 converges and reports the decision block (`agent.A3`'s converged outcome), and the session ends there. This skill thinks and never acts (`pattern.A3`): whether anything is then executed is decided by the class of the originating turn — a task turn proceeds under `agent.A3`, a question turn gets the block and nothing else. A decision-record doc per `RULE-docs.md` still applies when the decision is durable.
+- Phase 5 converges and reports the decision block (`agent.A3`'s converged outcome), and the session ends there. This skill thinks and never acts (`pattern.A3`): an order proceeds under `agent.A3`; a communication turn gets the block and nothing else. A durable decision gets a decision-record doc per `RULE-docs.md` — written on an order, proposed on a communication turn.
 
 ## Invocation scope