@akinet/akidevrule 3.5.0 → 3.6.0

package/install.mjs

@@ -333,15 +333,15 @@ const ROUTER_SRC = join(SKILLS_SRC, "akirule", "SKILL.md");
 
 // The router's routes table is the single routing source; AG's native rule descriptions are derived from it.
 function routerClauses() {
-  const table = readFileSync(ROUTER_SRC, "utf-8").matchAll(/^\| `((?:RULE|METHOD)-[^`]+\.md)` \| ([^|]+) \|/gm);
+  const table = readFileSync(ROUTER_SRC, "utf-8").matchAll(/^\| `((?:RULE|METHOD)-[^`]+\.md)` · `[\w-]+` \| ([^|]+) \|/gm);
   return new Map([...table].map(([, file, clause]) => [file, clause.trim()]));
 }
 
-// Each entry: [ruleFile, trigger, globs, description] — globs is a raw JSON array string or ""; description only for core rules, which the router does not route.
+// Each entry: [ruleFile, trigger, globs] — globs is a raw JSON array string or ""; every model_decision description is derived from the router's route clause.
 const AG_RULE_MAP = [
   ["RULE-agent-behavior.md", "always_on", ""],
-  ["RULE-coding.md", "model_decision", "", "Coding philosophy, source-of-truth discipline, error handling and security. Load when writing, reviewing or refactoring code."],
-  ["RULE-pattern-core.md", "model_decision", "", 'Universal design laws: single source of truth, Rule of Three, single-responsibility "and"-test, composition over inheritance, naming by role. Load on any structural or decomposition decision.'],
+  ["RULE-coding.md", "model_decision", ""],
+  ["RULE-pattern-core.md", "model_decision", ""],
   ["RULE-docs.md", "model_decision", ""],
   ["RULE-content-write.md", "model_decision", ""],
   ["RULE-stack-akiNuxtCf.md", "glob", '["**/*.vue", "nuxt.config.*", "wrangler.toml", "app/**", "server/**", "composables/**", "middleware/**", "plugins/**", "layouts/**"]'],
@@ -366,8 +366,7 @@ function agDestName(ruleFile) {
   return `akirule-${stem.toLowerCase()}.md`;
 }
 
-function agRuleDescription(ruleFile, core, clauses) {
-  if (core) return core;
+function agRuleDescription(ruleFile, clauses) {
   if (!clauses.has(ruleFile)) throw new Error(`akirule has no route for ${ruleFile}`);
   // agy denies view_file on ~/.gemini/config/rules/ (hardcoded protection boundary, measured 2026-09-26), so the description names the readable copy.
   return `Load when the task ${clauses.get(ruleFile)}: view_file ~/.aki/akidevrule/${ruleFile} (this rules directory itself is not readable).`;
@@ -380,10 +379,10 @@ function installAgRules() {
   const unmapped = listDir(join(REPO_ROOT, "payload")).filter((n) => /^(RULE|METHOD)-.*\.md$/.test(n) && !mapped.has(n));
   if (unmapped.length) throw new Error(`AG_RULE_MAP has no entry for: ${unmapped.join(", ")}`);
 
-  const rendered = AG_RULE_MAP.map(([ruleFile, trigger, globs, core]) => {
+  const rendered = AG_RULE_MAP.map(([ruleFile, trigger, globs]) => {
     const lines = ["---", `trigger: ${trigger}`];
     if (globs) lines.push(`globs: ${globs}`);
-    if (trigger !== "always_on") lines.push(`description: ${JSON.stringify(agRuleDescription(ruleFile, core, clauses))}`);
+    if (trigger !== "always_on") lines.push(`description: ${JSON.stringify(agRuleDescription(ruleFile, clauses))}`);
     lines.push("---", "", `<!-- Generated by akidevrule from payload/${ruleFile}. Do not edit here. -->`, "");
     lines.push(readFileSync(join(REPO_ROOT, "payload", ruleFile), "utf-8"));
     return [join(GEMINI_RULES_DIR, agDestName(ruleFile)), lines.join("\n")];
@@ -469,6 +468,26 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
     ],
   });
 
+  if (!Array.isArray(hooks.PreToolUse)) hooks.PreToolUse = [];
+  const isAkiRouteGuard = (entry) => {
+    try {
+      return (entry.hooks || []).some((h) => (h.command || "").includes("aki-route-guard"));
+    } catch {
+      return false;
+    }
+  };
+  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,
+      },
+    ],
+  });
+
   writeTextLf(settingsPath, JSON.stringify(data, null, 2) + "\n");
 }
 
@@ -540,6 +559,7 @@ function installClaudeDir(claudeDir) {
   mkdirSync(hooksDest, { recursive: true });
   copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki-update-check.mjs"), join(hooksDest, "aki-update-check.mjs"));
   copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki_version_check.mjs"), join(hooksDest, "aki_version_check.mjs"));
+  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki-route-guard.mjs"), join(hooksDest, "aki-route-guard.mjs"));
   for (const legacy of ["aki-update-check.py", "aki_version_check.py"]) {
     const p = join(hooksDest, legacy);
     if (existsSync(p)) rmrf(p);
@@ -564,11 +584,11 @@ function installClaudeDir(claudeDir) {
   const localMdTilde = toTildePath(localMd);
   const ruleSourceBlock =
     "\n## akidevrule — edit source, not deployed copy (ABSOLUTE)\n\n" +
-    `The deployed rule files at \`${INSTALL_ROOT}\` are **overwritten on every install**.\n` +
-    "To change any shared rule:\n" +
-    `1. Edit in the **source repo**: \`${join(REPO_ROOT, "payload")}/\`\n` +
-    `2. Run \`${propagateCmd}\` to propagate.\n\n` +
-    `**NEVER edit files under \`${INSTALL_ROOT}\` directly** — changes will be silently lost on the next install.\n\n` +
+    `The rule files at \`${INSTALL_ROOT}\` and the skills, agents and hooks under \`${toTildePath(claudeDir)}\` are deployed copies, **overwritten on every install**. To change a shared rule, skill or hook:\n` +
+    `1. Read \`${join(REPO_ROOT, "CLAUDE.md")}\` first — it names the files that must change together.\n` +
+    `2. Edit in the source repo: \`${join(REPO_ROOT, "payload")}/\` (rules), \`${join(REPO_ROOT, "skills")}/\` (skills), \`${join(REPO_ROOT, "claude")}/\` (Claude Code assets).\n` +
+    `3. Run \`${propagateCmd}\` to propagate.\n\n` +
+    `**NEVER edit the deployed copies directly** — changes are silently lost on the next install.\n\n` +
     `@${localMdTilde}\n`;
   writeTextLf(claudeMd, claudeMdSrc + ruleSourceBlock);
 
@@ -764,19 +784,12 @@ function printSummary(claudeDirs, preAllow) {
   console.log();
 
   console.log(cyanBold("Rules deployed:"));
-  const indexPath = join(INSTALL_ROOT, "index.md");
-  if (isFile(indexPath)) {
-    const tierColors = [["Core", redBold], ["Contextual", yellowBold], ["Analytical", blueBold]];
-    for (const line of readFileSync(indexPath, "utf-8").split("\n")) {
-      const m = line.match(/^\|\s*`([^`]+)`\s*\|\s*([^|]+?)\s*\|(.+)\|/);
-      if (m) {
-        const fname = m[1];
-        const tier = m[2].trim();
-        const desc = m[3].trim();
-        const entry = tierColors.find(([k]) => tier.startsWith(k));
-        const tierStr = entry ? entry[1](tier.padEnd(12)) : tier.padEnd(12);
-        console.log(`  ${tierStr} ${fname.padEnd(30)} ${desc}`);
-      }
+  {
+    const clauses = routerClauses();
+    for (const [ruleFile, trigger] of AG_RULE_MAP) {
+      const [tier, color] = trigger === "always_on" ? ["Core", redBold] : ruleFile.startsWith("METHOD-") ? ["Analytical", blueBold] : ["Contextual", yellowBold];
+      const desc = trigger === "always_on" ? "behavior floor — resident every session" : `loads when the task ${clauses.get(ruleFile) || "?"}`;
+      console.log(`  ${color(tier.padEnd(12))} ${ruleFile.padEnd(34)} ${desc}`);
     }
   }
 
@@ -815,6 +828,7 @@ function printSummary(claudeDirs, preAllow) {
 
   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; AKI_ROUTE_GUARD=0 disables");
   console.log("  📢 aki-update-check (SessionStart, notify-only) — notifies when a new rule version is available");
 
   console.log(`\n${greenBold("==============================")}`);
@@ -883,8 +897,8 @@ async function runInstall(claudeDirs) {
 
   copyFileSync(join(REPO_ROOT, "CHANGELOG.md"), join(INSTALL_ROOT, "CHANGELOG.md"));
 
-  const tccSrc = join(REPO_ROOT, "docs", "ref", "macos-codesign-tcc.md");
-  const tccDest = join(INSTALL_ROOT, "docs", "ref", "macos-codesign-tcc.md");
+  const tccSrc = join(REPO_ROOT, "docs", "ref", "fact-macos-codesign-tcc.md");
+  const tccDest = join(INSTALL_ROOT, "docs", "ref", "fact-macos-codesign-tcc.md");
   rmrf(join(INSTALL_ROOT, "docs"));
   mkdirSync(dirname(tccDest), { recursive: true });
   copyFileSync(tccSrc, tccDest);

package/lib/permissions.mjs

@@ -1,5 +1,5 @@
 // Script pre-allow for every agent harness akidevrule deploys skills to.
-// Matcher facts per harness: docs/ref/cli-permission-allowlist-standard.md.
+// Matcher facts per harness: docs/ref/fact-cli-permission-allowlist-standard.md.
 import { existsSync, readdirSync, readFileSync, mkdirSync } from "node:fs";
 import { join, dirname, relative, isAbsolute, sep } from "node:path";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinet/akidevrule",
-  "version": "3.5.0",
+  "version": "3.6.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",
@@ -46,7 +46,7 @@
     "payload/",
     "skills/",
     "claude/",
-    "docs/ref/macos-codesign-tcc.md",
+    "docs/ref/fact-macos-codesign-tcc.md",
     "CHANGELOG.md"
   ],
   "publishConfig": {

package/payload/GEMINI.md

@@ -33,8 +33,8 @@ These directives patch Antigravity's known weak spots. They are hard-loaded (no
 
 ## 3. Always comply with the akirule corpus — and with rule 0
 - The shared rule corpus installed at `~/.aki/akidevrule/` ("akirule") applies to you, not only to other agents. When a task touches an area it covers, follow it.
-- **Session start, before the first task action:** `view_file` `~/.aki/akidevrule/RULE-coding.md` and `~/.aki/akidevrule/RULE-pattern-core.md` in full. They are core rules; the rules budget cannot inline them, so this read is how they enter context. Read every `~/.aki/akidevrule/` file from that directory — the copies under `~/.gemini/config/rules/` are not readable by `view_file`.
-- **First line of every response is the receipt** `[RULES] agent (always_on) + coding,pattern,<topics you viewed this session> (viewed)` — topic addresses from `~/.aki/akidevrule/index.md`. A rule absent from the line was not read; the line is self-reported and is a diagnostic, never proof of compliance.
+- **Nothing is read at session start.** `RULE-coding.md` and `RULE-pattern-core.md` are attached natively by their rule descriptions on code turns (`akirule-coding`, `akirule-pattern-core`), like every other contextual rule; a turn that only reads, counts or explains what exists loads nothing. When a rule must be viewed, read it from `~/.aki/akidevrule/` — the copies under `~/.gemini/config/rules/` are not readable by `view_file`.
+- **First line of every response is the receipt** `[RULES] agent (always_on) + <topics attached or viewed this session> (viewed)` — a topic is the rule's name stem (`akirule-coding` → `coding`), an item inside it `topic.A1`. A rule absent from the line was not read; the line is self-reported and is a diagnostic, never proof of compliance.
 - **Re-assertion of rule 0, by design:** whatever else you are doing, you comply with the prime directive. Never act outside the requested scope.
 
 ## 4. Rule 0 again — no unrequested action, at any cost

package/payload/RULE-agent-behavior.md

@@ -1,6 +1,6 @@
 # Core Agent Rules
 
-<!-- Address map: agent.§0 · agent.A1-5 · agent.B1-5 · agent.C1-5 -->
+<!-- Address map: agent.§0 · agent.A1-5 · agent.B1-6 · agent.C1-5 -->
 
 ## §0. Penalty cards — one vocabulary for the highest-frequency violations
 
@@ -25,7 +25,7 @@ Being called with a card means: re-read the root rule, fix **every** instance in
 - Prefer reading current files over relying on memory
 - Use the smallest safe change that solves the task
 - Report blockers early and specifically
-- **Every tool call re-sends the entire conversation.** A turn is not incremental — the whole history is the input each time. So the cost of work is driven by *number of round trips*, not by how much each one does. Three habits follow, and they are not stylistic preferences:
+- **Round trips are the unit of cost, not the size of one call.** Every call carries the whole history again (cached after the first turn, but re-read every time), so the work's cost follows the number of round trips. Three habits follow, and they are not stylistic preferences:
   - **Read/Edit the file, never `cat`/`sed`/`head` to print-then-read it.** Bash is for what it is uniquely good at: multi-file scans and transforms, pipes and aggregation, genuinely shell-native tasks (git, npm, processes). Shelling out to read one known file spends a round trip to obtain what one tool call already returns.
   - **Find every edit site before touching any of them, then apply the whole set in one pass.** Editing line by line as sites are discovered turns one change into N full-history round trips. If the sites are not all known yet, that is a signal to search first, not to start editing.
   - **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.
@@ -36,7 +36,7 @@ Classify every turn before acting: is it **communication** (a question, discussi
 - **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:** before the question leaves, confirm the answer is not already sitting in the three sources you are expected to have exhausted — the rule corpus (`akirule` routes it; the core files are already in context), the deep-think budget (`METHOD-deep-think.md`, run to convergence, not one shallow pass), and the owner's original request read verbatim plus the conversation history. A question those three already answer is amnesia, not a genuine unknown; re-reading them is cheaper than an interrupt and is not optional. This test only redirects a question you could answer yourself — it never overrides the escalation floor below: a real one-way door with outward effect is still asked, no matter how self-sufficient the reasoning feels. A question dressed as a "decision with a recommendation" still costs a read and an answer — the shape does not exempt it from these tests.
+- **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.
@@ -50,25 +50,13 @@ The reader often context-switches across many tasks and reads in a terminal; opt
 - 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
-A worker is a subagent, or the same or another CLI called headlessly (`claude -p`, `agy -p`, equivalents).
-
-**Narrow at the source before delegating.** If one bounded command, restricted read, pipeline, or batch can return the answer — or a digest that loses nothing the decision needs — run it in this thread. Repository size and raw input size alone do not justify a worker when aggregation prevents that raw volume from entering the context.
-
-**Probe once only when the route cannot yet be specified.** If the target, question, or required output shape is unclear, run one bounded orientation probe. The probe may finish the task; never delegate work the probe already answered. If the residue still requires broad reading or comprehension that cannot be narrowed before entering a context, cross the process boundary with exact paths or targets, the exact question, and the exact output shape.
-
-**Route by context need, not by the word “exploration.”** Conversation-dependent synthesis, ambiguous classification, and per-item judgment stay with the caller; delegate only the retrieval that feeds them. Prefer a fresh worker for a precise, context-free digest. Use a fork only when a bounded bulk task genuinely needs substantial accumulated context that would be expensive to restate. A worker never delegates again unless the caller explicitly grants a fan-out with bounded depth and width.
-
-**When delegation is warranted, use the cheap wide-context tier the host resolves, one shot** — the literal command, model id and read-only mechanism per host live in one table (`skills/akiflow/references/harness-facts.md` § Model tiers › Host resolution), never in this rule. That tier holds a very large context; its failure mode is skimming, so the counter is prompt precision rather than a bigger model: name the exact paths, the exact question, and the exact output shape, and leave it nothing to improvise. Keep it to a single call — multi-turn on those CLIs degrades badly.
-
-**Know which kind of cheap you are buying.** A stateless cheap call is cheap *per call* and must re-receive its context every time. A persistent worker (`claude -p --session-id <uuid>`, later `--resume <uuid>`) is cheap *per turn after the first*, because its prefix is cached — roughly an eighth of the opening turn, then flat — and it keeps everything **it** was told, though nothing the caller knows. Use the first for one wide question, the second for a worker you will come back to. The session id is scoped to the directory it was created in.
-- **A worker inherits nothing** — not your context, not your rules, not your router. Name the exact rule files it must read and the exact paths or targets it must look at. "Follow the project rules" loads nothing and reads as compliance.
-- **Require the return leg — the worker reports what it actually received.** Naming the files is only half the loop: a brief that was ignored, a path that no longer resolves, and a rule read in full all produce output that looks the same. The worker's first line is a receipt — `[RULES] agent,coding (brief)` — naming the topic address of every rule file it read; a file the brief named that is absent from the line was not read. A worker gets one round, so this is not conditional: with no receipt, a later violation cannot be traced to either the brief or the behavior, and those two have opposite fixes. Format and the session-side duty: `skills/akirule/SKILL.md` § Load confirmation.
-- **Set both dials, every time: model tier and thinking effort.** An omitted parameter does not fall back to something cheap; it silently inherits the caller's own expensive settings. Silence is an expensive choice made by accident.
-- **Enforce read-only by mechanism, not by wording**, wherever "fixing while I'm here" would be unrecoverable — restrict the worker's tool set, or use the CLI's read-only/plan mode. A prompt-worded ban is one the model can talk itself out of.
-- **If a program will parse the output, use the structured-output flag** rather than asking for JSON in prose.
-- **Ask for the conclusion, not the dump.** Have the worker aggregate in-shell and return the answer; pulling raw search output back into the caller's context is the exact cost the delegation was meant to avoid.
-- **Judgment does not delegate downward.** A cheap tier is for retrieval. Deciding what a finding *means* stays with the caller — a cheap model's confident misclassification costs more than the sweep saved.
-- **Spend that crosses a process or CLI boundary is invisible to the caller's own accounting.** If the total matters, read each call's own usage figures and add them by hand.
+A worker is a subagent, or a CLI called headlessly (`claude -p`, `agy -p`, equivalents).
+- **Narrow at the source first.** If one bounded command, restricted read, pipeline or batch returns the answer — or a digest that loses nothing the decision needs — run it in this thread; repository size alone never justifies a worker when aggregation keeps the raw volume out of this context. When the target, question or output shape is unclear, run one bounded orientation probe; never delegate what the probe already answered.
+- **Route by context need, not by the word "exploration".** Conversation-dependent synthesis, ambiguous classification and per-item judgment stay with the caller; delegate the retrieval that feeds them, to a fresh worker with a context-free brief. A fork only when a bulk task needs accumulated context that is expensive to restate. A worker never delegates again unless granted a fan-out with bounded depth and width.
+- **A worker inherits nothing** — not your context, not your rules, not your router. Name the exact rule files it must read, the exact paths, the exact question and the exact output shape; "follow the project rules" loads nothing and reads as compliance. **Require the return leg:** the worker's first line is a receipt — `[RULES] agent,coding (brief)` — naming every rule file it read (format: `skills/akirule/SKILL.md` § Load confirmation); a file the brief named that is absent from the line was not read. Without it a later violation cannot be traced to the brief or to the behavior, and those two have opposite fixes.
+- **Set both dials, every time: model tier and thinking effort.** An omitted parameter silently inherits the caller's own expensive settings. Which tier per host, the cheap wide-context tier's literal command, and what stateless versus persistent workers cost: `skills/akiflow/references/harness-facts.md` § Model tiers, § Stateful workers — never restated here.
+- **Enforce read-only by mechanism, not by wording** — a restricted tool set, or the CLI's read-only/plan mode — wherever "fixing while I'm here" would be unrecoverable. If a program parses the output, use the structured-output flag. Ask for the conclusion, aggregated in-shell, never the dump.
+- **Judgment does not delegate downward.** A cheap tier retrieves; what a finding *means* is decided here — a confident misclassification costs more than the sweep saved. Spend across a process boundary is invisible to the caller's accounting: read each call's usage figures and add them by hand.
 
 ## B. Scope & decision discipline
 
@@ -88,7 +76,7 @@ A worker is a subagent, or the same or another CLI called headlessly (`claude -p
 
 ### B3. Decision boundaries
 Ask before:
-- 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.B5`'s ladder instead of asking
+- 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
 - any test, benchmark, or trial run that spends paid API credits or session quota
@@ -113,6 +101,15 @@ An audit — of code, docs, versions, UI, or a working tree — **reports**; it
 
 Domain audits: `docs.C` (docs vs reality), `release.B` (version state), `release.B7` (pre-ship gate), `ui.C` (class/token), `METHOD-audit-flow.md` (flow/state).
 
+### B6. Precedence
+When rules conflict, use this order:
+1. Current local source code, runtime output, and build output
+2. User's explicit instruction in the current conversation
+3. User's standing instructions — `~/.claude/CLAUDE.md` and the machine-local `~/.claude/CLAUDE.local.md`. An item marked ABSOLUTE there is never weakened by anything below it, including a shared rule that grants an autonomy other projects rely on; ordinary guidance there yields to a more specific project rule.
+4. Project `CLAUDE.md` — may add project facts and stricter constraints; must not silently weaken core safety, verification, or source-of-truth rules
+5. Aki-RULE shared files
+6. Older docs, memory, or prior conversation context
+
 ## C. Files & memory
 
 ### C1. File creation and naming
@@ -131,8 +128,9 @@ Domain audits: `docs.C` (docs vs reality), `release.B` (version state), `release
 - Only break lines where the structure is genuinely intentional: table rows, code blocks, and nested sub-bullets under a parent bullet.
 - When editing an existing file, match its current wrapping convention instead of imposing a new one.
 - **Prompts are the highest-frequency offender**: when asked to compose a prompt (for another AI, tool, or template), never hard-wrap it — the text is pasted verbatim, so inserted newlines become part of the artifact. One instruction/paragraph = one logical line.
+- **Anything meant to be copied verbatim — a prompt, a template, a file body, a multi-line command block — is fenced with four backticks, never three.** The artifact often contains a fence of its own, and a three-backtick wrapper closes early and silently truncates what gets copied; the wider fence also marks the block as a paste-ready artifact rather than an illustration. Inline code stays for a single token.
 - This also applies inside code: do not insert a hard newline mid-comment, mid-docstring, or mid-string-literal just because the line is long — a learned training-data habit (e.g. ~80-column style conventions), not a deliberate choice for the file at hand. Let the line run long and leave wrapping to the editor/formatter, unless the surrounding file already wraps at a specific width as its own convention.
-- **The reverse direction is equally forbidden and more dangerous**: never collapse multiple physical lines into one just to "clean up" wrapping. First decide whether each line is *wrapped prose* (safe to rejoin into one logical line) or a *structurally atomic unit* (one line = one machine-parsed field or directive, never safe to merge). Concrete tells for the latter: YAML/TOML frontmatter (each `key: value` must keep its own line — merging fields onto one line corrupts the parser, e.g. `name: x description: y` reads as a single value, silently deleting the `description` key), `@import`/include directives (one path per line — merging several onto one line changes what a one-per-line loader parses as a single target), and any line prefixed by a format marker consumed by tooling rather than a human reader. When in doubt whether a line is prose or structure, check whether something *parses* it — if yes, never merge it.
+- **The reverse direction is equally forbidden and more dangerous**: never collapse multiple physical lines into one to "clean up" wrapping. Rejoin only *wrapped prose*; never a *structurally atomic unit* — one line = one machine-parsed field or directive. Tells: YAML/TOML frontmatter (`key: value` per line — merged, `name: x description: y` parses as one value and the second key vanishes), `@import`/include directives (one path per line), any line prefixed by a marker tooling consumes. When in doubt whether something *parses* a line, it does: never merge it.
 
 ### C4. Memory discipline
 - **Never write, update, or delete a persistent memory on your own initiative — always ask the user first.** This applies to every memory file and the `MEMORY.md` index. Do not save a fact, feedback, or project note just because it seems useful.

package/payload/RULE-coding.md

@@ -36,15 +36,25 @@ A principle with the procedure that guarantees it — apply to any edit of code
 - **Before:** grasp the flow and intent of the code before you change it — read the docs it references first (code often points to `docs/...`), then the code, and the git history only when the logic is complex or has been reworked many times (Chesterton's Fence: know why a piece is there before you remove it).
 - **After:** confirm the intents and flows you did NOT set out to touch still hold — a fix scoped to problem X must not silently break an unrelated property Y.
 
-### B3. Verification
-- Done means verified — never claim success from intention alone.
-- Verify by the **narrowest tool that actually settles the doubt**: static reading and type/lint/unit checks first. Never spin up a full build or dev server just to catch a typo a typecheck would catch.
-- **Never move uncommitted work to attribute a failing check.** No `git stash`/`checkout -- <path>`/`restore`/`reset`/`clean` to learn whether a typecheck or build error pre-exists: read the error against the changed files, or rebuild the committed tree in a separate `git worktree`. The working tree may hold the owner's unfinished work, and a known pre-existing failure yields no information worth risking it.
-- **Static reading IS verification** when the property is fully determined by visible code flow — state what was read as the evidence and close the checklist item on that evidence. Escalate a tier (typecheck → unit → runtime) only when you can name the specific doubt that tier settles.
-- **Never gate a done-transition on human manual testing for a check that static reading or an automated tier settles.** A plan's verify checklist stays fully detailed — the violation is not the checklist, it is parking finished work as "waiting for manual test" on items whose truth the code flow already proves. Hand the human only what genuinely needs human runtime judgment: UX feel, visual rendering, live external integration.
-- **Running the app is not a default verification step — but not running it does not let you claim "Done".** Starting a dev server or making live network calls stays **user-triggered**, not self-authorized (cost and side effects are the user's call). A full build and the test suite are **not** in that category — they are self-authorized, gated by the moment instead: **after edits** → typecheck/lint/related unit tests, never a full build per edit; **committing a large batch** (spans several modules, or touches build config/dependencies) → add the build; **ship/release/deploy** → full build plus full test suite is mandatory and self-authorized, commands derived per `release.B7` step 6. When a change's real risk lives **only at runtime** — hydration, layout/z-index, route/auth flow, a dynamically-built class a build step may purge — and you cannot settle it statically, you may **not** report "Done": halt and report the state as **"unverified — needs a runtime check"**, propose the exact command, and hand it to the user (see [[RULE-agent-behavior]] A3). "Done" for logic you only compiled is not done.
-- **When a runtime check genuinely needs a human, hand over one ledger, not one per phase.** Collect every human-run check into a single batch at the end of the run, deduped by flow: the same flow is run once, at its final state. Re-running one flow at several milestones is legitimate only when an earlier run is the baseline that makes a later regression attributable — and that reason is written beside it. Three requests to run one launch-and-navigate flow is not three times the verification, it is three interruptions.
-- **A change that requires a separate action against an external system to take effect is not done when the file describing that action is written.** Migrations, remote config, env vars, cache purges, cron/schedule registration — writing the script/config is not the same event as the target system actually reflecting it. Git diff and a green build both stay silent about this gap: neither touches the external system, so both can look complete while the real target (a remote database, a dashboard toggle, a deployed cron) is still on the old state. Verify the action was actually executed **against the real target**, not just that the instructions to perform it exist locally, before reporting "Done" on that change. Domain instantiation: [[RULE-release]] (a release/CHANGELOG entry is not truthful until this holds) and stack-specific execution commands (e.g. `RULE-stack-akiNuxtCf.md` §C8 for D1 migrations).
+### B3. Verification — what counts, and who performs it
+Done means verified — never claim success from intention alone. Verify by the narrowest tool that settles the doubt, and hand a check to the owner only as the last rung of the ladder below.
+
+**What counts**
+- **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).
+- **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.
+- **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.
+1. **Read the flow.** Most "needs testing" items are "nobody traced the call path yet".
+2. **Search the local tree** — a convention line in `README`, a CI matrix, a sibling implementation. *Worked example: "does the Windows rendering break?" was one `README` line naming this repo's `py -3` convention — no Windows machine involved.*
+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.
+
+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.
 
 ### B4. Self-documenting code — comments are a last resort
 Domain application of the density root (`agent.A4` — every line must carry information the reader does not already have); the naming root is `pattern.A7`. Penalty card: `[YAP]` (`agent` §0).
@@ -54,26 +64,6 @@ Domain application of the density root (`agent.A4` — every line must carry inf
 - Comments rot: no compiler checks a comment, so it drifts silently as the code under it changes, and a stale comment misleads worse than none — one more reason deletion is the default, and why a rationale that must stay current lives in a doc the code references ([[RULE-docs]] B3), never duplicated inline.
 - One line when a comment is genuinely needed; a rationale bigger than that lives in docs, with the comment holding only the reference (see [[RULE-docs]] B3).
 
-### B5. Handing a check to the human is the last rung of a ladder, never the default
-
-`B3` decides what counts as verification; this decides **who performs it**. A hand-off is not neutral bookkeeping — it costs the owner a context switch, a read, and an action, and it converts a finished report into homework. It is a question in disguise, so it faces `agent.A3`'s kill-tests *and* this ladder first. Climb in order, stop at the first rung that settles the doubt, and record which rung settled it.
-
-1. **Read the flow.** Static reading is verification when the property is fully determined by visible code (`B3`). Most "needs testing" items are really "nobody traced the call path yet".
-2. **Search the local tree.** The answer is often already written down here — a convention line in `README`, an existing platform branch, a CI matrix, a sibling implementation. Grep before assuming it is unknown. *Worked example: "does the Windows rendering break?" was answered by one `README` line stating this repo's own `py -3` interpreter convention — no Windows machine involved.*
-3. **Search the vendor's docs and the open web.** A claim about someone else's platform is settled by their published behavior, not by re-observing it locally. **A check that would only reproduce documented vendor behavior is already answered**: cite the source and write a reopen trigger instead of scheduling an experiment.
-4. **Probe mechanically, right here.** Simulate the environment you do not have instead of requesting it — render the other OS's path with `PureWindowsPath`, stub the clock/env var, run the pure function that builds the artifact and read the string it produces. A derived artifact can almost always be computed without the machine that would consume it.
-5. **Run the real thing, reversibly.** First **check whether the tool is actually present** (`command -v`, `--version`) — "the owner's machine has that CLI" is an assumption until the shell says otherwise, and it is the single most common false hand-off. A setting that can be backed up, flipped, exercised and restored is a two-way door (`think.A1`): that is available work, not owner work. Back up first, restore in a `trap`, and report the before/after state.
-6. **Hand off** — only what survives all five.
-
-Rules for whatever residue reaches rung 6:
-- **Each handed-off item names the rung that failed and why**, in one line, in the artifact that carries it ("needs the paid vendor account: rung 5, no sandbox tier exposes this endpoint"). An item with no such line is a violation, not a to-do — it is indistinguishable from an item nobody tried to settle.
-- **Hand over a result to confirm, not a task to design.** The exact command, the expected output, and what a deviation would mean. If you cannot state the expected output, you have not finished rung 1.
-- **Re-climb the ladder at closing time.** A ledger that accumulated during a long run is full of items that later work made answerable; the state of knowledge at the end is not the state that filed them.
-- **Default to the report.** A plan whose ending is five owner-run items and no findings has usually skipped rungs 1–5. "Here is the result and what it means" is the deliverable; "please run this and tell me" is the fallback.
-- Forbidden rationalizations, all of which mean *the ladder was not climbed*: "can only be verified end-to-end", "needs a real machine", "only the owner can decide", "I don't have access to that platform" — each is a claim about rungs 3–5 that must be demonstrated, not asserted.
-
-None of this weakens `B3`'s honesty floor: what genuinely stays unverified is still reported as unverified and never as "Done". The target is the manufactured hand-off, not the real one.
-
 ## C. Runtime safety
 
 ### C1. Error handling

package/payload/RULE-docs.md

@@ -59,7 +59,7 @@ The harness prepends this file to every request, so every line in it is paid on
 2. **Reach** — it governs the majority of requests in this project. A line that matters to one domain belongs in the doc that domain's route loads (`feat/`, `arch/`, `biz/`, a project rule file), not here.
 3. **Not derivable** — it cannot be read from the code, the manifest (`package.json`, `Cargo.toml`), or a doc the router already loads for that task.
 4. **Not a restatement** — a shared-corpus rule is pointed at by address (`coding.B3`), never copied; a copy drifts and doubles the cost.
-5. **Facts and limits, not behavior** — the file binds the project's facts (stack, reference implementation, test and compile command, ship platform, hard limits) and stricter constraints; behavior rules live in the corpus (`index.md` § Precedence). Those bindings are the router's standing signal for every task in the project.
+5. **Facts and limits, not behavior** — the file binds the project's facts (stack, reference implementation, test and compile command, ship platform, hard limits) and stricter constraints; behavior rules live in the corpus (`agent.B6` Precedence). Those bindings are the router's standing signal for every task in the project.
 
 One file is the source: a per-project `GEMINI.md` or `AGENTS.md` is a bootstrap that points at `CLAUDE.md`, never a second copy.
 

package/payload/RULE-pattern-core.md

@@ -2,7 +2,7 @@
 
 <!-- Address map: pattern.A1-8 · pattern.B1-3 · pattern.C1 -->
 
-**Tier: Core** — `@`-imported by `~/.claude/CLAUDE.md`, in context every session. Stack-agnostic. This file is the universal pattern philosophy — the "forest view" that keeps a codebase coherent as it grows, instead of accreting local patches. It applies to every project type: backend, API/worker, Tauri/desktop, CLI, library, DB layer, and UI.
+**Tier: Contextual, gated** — routed by `akirule` on every code turn and enforced on Claude Code by the `aki-route-guard` hook, which denies the first code edit of a session until this file was read. Stack-agnostic. This file is the universal pattern philosophy — the "forest view" that keeps a codebase coherent as it grows, instead of accreting local patches. It applies to every project type: backend, API/worker, Tauri/desktop, CLI, library, DB layer, and UI.
 
 It **sharpens** `RULE-coding.md` (which owns baseline DRY/YAGNI/SRP and the Result pattern); it does not restate it. UI-specific enforcement of these same laws lives in `RULE-ui-pattern.md`.
 
@@ -19,7 +19,7 @@ These are constraints on **structure and reuse**, not style. Reach for this file
 
 ---
 
-## A. The 8 laws — checkable, stack-agnostic
+## A. The 9 laws — checkable, stack-agnostic
 
 **A1 — Single Source of Truth.** Every value, rule, or decision that can change lives in exactly one place; everything else references it. This covers config, constants, types, enums, business thresholds, and visual tokens — not just one category. A value written twice is a future inconsistency, not a convenience.
 
@@ -35,10 +35,12 @@ These are constraints on **structure and reuse**, not style. Reach for this file
 **A6 — Stable boundaries between modules.** Split along independent responsibilities/domains (bounded context). Modules talk through a narrow, explicit contract — a stable ID, a typed interface, a `Result` — and never reach into another module's internals. Volatile details (provider SDKs, frameworks, transport) sit at the edges behind a boundary; stable abstractions sit at the core, and dependencies point inward toward them.
 
 **A7 — Name by role, never by concrete value.** Name things for what they *mean*, not what they *currently are*: `retryLimit` not `three`, `PrimaryAction` not `BlueButton`, `AuthBoundary` not `FirebaseWrapper`. Value-names rot the instant the value changes and force codebase-wide find-and-replace.
-- *Root rule for naming.* Every other naming item in this corpus (`agent.C1` file names, `ui.A` tokens, `stack.C1` component names, `release.A3` version/tag format, `content` semantic stability) is a **domain application** of A7, not a competing rule — do not restate A7 in them, and do not move them out of their domain. Address map: `index.md` § Cross-cutting lens.
+- *Root rule for naming.* Every other naming item in this corpus (`agent.C1` file names, `ui.A` tokens, `stack.C1` component names, `release.A3` version/tag format, `content` semantic stability) is a **domain application** of A7, not a competing rule — do not restate A7 in them, and do not move them out of their domain.
 
 **A8 — One flow, made natural — not guarded.** When the same guard / check / fallback keeps reappearing around a path, the path's shape is wrong. Reshape the flow so the correct behavior is automatic; do not stack more enforcement on a weak path. "Correct" is measured against the project's pinned facts (`coding.C1`), so a guard for a state those facts rule out is a patch, not a flow. Full method: `METHOD-audit-flow.md`.
 
+**A9 — Draft, then commit once.** Anything still being explored — a gesture in progress, a form being typed, a version being accumulated, a question being weighed — lives in a draft owned by the unit showing it. The record (shared state, storage, IPC, network, git, a released version) changes once, at an explicit commit event, from the draft. Cancel discards the draft; if cancel needs an undo, the two phases were merged.
+
 ---
 
 ## B. Decomposition & the forest pass

package/payload/RULE-release.md

@@ -194,8 +194,8 @@ The B7 gate plus its surrounding ritual (fix findings → sync docs → CHANGELO
 ### B9. Registry-published package (npm, crates.io, PyPI, …) — the registry version is the release
 
 A package installed from a registry is a distributed artifact (A5): users get what the registry serves, so a tag plus GitHub Release with no registry version leaves `npx`/`pip install` on the old one. Released = tag + GitHub Release + `npm view <pkg>@<version> version` (or the registry's equivalent) returning the new version (`coding.B3`).
-- **The publish mechanism is derived, never designed.** Read the existing convention first: project `CLAUDE.md`, `.github/workflows/`, and sibling packages the same account already publishes (`npm access list packages`) — a working sibling is the template (`coding.B5` rung 2). A CI publish job with a registry token adds a secret and automation: `agent.B3` territory, never the default.
-- **Account facts are probed, not inferred** (`coding.B5` rung 5): `npm whoami` (session), `npm org ls <scope>` (scope ownership — a 404 on the package name means the name is unpublished, never that the scope is unowned), `npm profile get` (2FA mode).
+- **The publish mechanism is derived, never designed.** Read the existing convention first: project `CLAUDE.md`, `.github/workflows/`, and sibling packages the same account already publishes (`npm access list packages`) — a working sibling is the template (`coding.B3` rung 2). A CI publish job with a registry token adds a secret and automation: `agent.B3` territory, never the default.
+- **Account facts are probed, not inferred** (`coding.B3` rung 5): `npm whoami` (session), `npm org ls <scope>` (scope ownership — a 404 on the package name means the name is unpublished, never that the scope is unowned), `npm profile get` (2FA mode).
 - **2FA `auth-and-writes` makes `npm publish` the run's single hand-off** (rung 6: the OTP is human-held). Everything else is agent work — push, tag, GitHub Release, tarball verification — so the owner receives one command and the `npm view` check that proves it landed, never a list of prerequisites.
 - **A published version number is burned forever** (`npm unpublish` is time-limited and a number is never reusable), so verify the tarball before publishing: `npm pack --dry-run` against the `files` allowlist, manifest version == CHANGELOG top == tag (A3), and the `bin` executed from the packed tarball installed in the scratchpad. A `bin` that writes to `$HOME` takes the override on its own command — `printf y | HOME="$SANDBOX" bin`, never `HOME="$SANDBOX" printf y | bin`, which scopes the variable to `printf` and runs against the real home.
 

package/payload/RULE-stack-tauri.md

@@ -56,4 +56,4 @@ Three switches, routinely confused — pick by what each actually controls:
 - **Ad-hoc signing loses the grant on every rebuild.** `codesign --sign -` (Xcode's "Sign to Run Locally") produces a new signature each build, and the authorization is tied to that exact build — so a permission granted yesterday is simply gone today, which reads as a random TCC bug. The fix is a **stable self-signed certificate**, which keeps grants across rebuilds; `tccutil reset All <bundle-id>` only clears the stale state, it does not prevent the next loss.
 - **Scope limit — this chain governs consent-based reads.** It does not apply to paths the user picked in an Open/Save dialog or by drag-and-drop (user intent grants access directly), and Apple's own analysis excludes file *writes* from it. A write-only or file-picker-driven sidecar failing is a different diagnosis; don't reach for these switches first.
 
-When you cannot tell which switch fired, watch it rather than guess: `log show --predicate 'subsystem == "com.apple.TCC"' --last 5m` prints the `AttributionChain` (which process was held responsible) and the request's result. Claims and sources: `docs/research/macos-tcc-tauri-boundary-aug21.md` in the akidevrule repo. Full lookup (switches + rebuild/DR mechanism): `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`.
+When you cannot tell which switch fired, watch it rather than guess: `log show --predicate 'subsystem == "com.apple.TCC"' --last 5m` prints the `AttributionChain` (which process was held responsible) and the request's result. Claims and sources: `docs/research/macos-tcc-tauri-boundary-aug21.md` in the akidevrule repo. Full lookup (switches + rebuild/DR mechanism): `~/.aki/akidevrule/docs/ref/fact-macos-codesign-tcc.md`.

package/payload/RULE-ui-pattern.md

@@ -11,6 +11,7 @@
 - **Composition over duplication (Law 5)** → slots / dynamic components / `v-for`, never hand-copied markup.
 - **OCP (Law 4)** → extend a component via props / variant / slot, never fork a copy.
 - **Name by role (Law 7)** → semantic tokens and variants, never value-names.
+- **Draft, then commit once (Law 9)** → `dragenter`/`dragover`/`pointermove`/`input` handlers touch a local draft only; `drop`/`pointerup`/`Enter`/Save writes the store once. Grep: no store setter, `localStorage`, IPC or fetch inside a preview handler.
 - **Reshape, don't stack (Law 8)** → before packaging a repeated style, try to remove it. The tier ladder only *packages* repetition; Law 8 is the only thing that *eliminates* it, and without it a codebase obeys every rule here while growing without bound.
 - **Documentation** → every global pattern is looked up before writing and recorded after, so the next agent reuses instead of rewriting.
 

package/skills/akiflow/SKILL.md

@@ -212,7 +212,7 @@ python3 ~/.claude/skills/akiflow/scripts/council_cost.py --session <uuid>
 - **Claude Code:** roster in one batch; `SendMessage` for peer challenge and for resuming completed seats; continuity travels as the plan doc or diff named in the prompt, since the one `subagent_type` that inherits session history (`fork`) is gated off by default; `isolation: "worktree"` for concurrent writers. An agent the *user* stopped refuses to resume via message and must be resumed from its own transcript panel — do not respawn a duplicate.
 - **Headless (`claude -p`):** nobody can answer an escalation or a permission prompt. Record it as `BLOCKED: needs owner` in `checklist.md` and continue the other items — never guess what the owner would have wanted.
 - **Antigravity / AGY:** supports native subagents via `invoke_subagent`. When `/akiflow` is invoked with multiple experts or dispatch lanes, the lead MUST spawn the roster via `invoke_subagent` concurrently in one batch. Simulating multiple seats sequentially in a single session context without spawning real subagents is strictly forbidden (role collapse / self-approval violation). Where AGY is reachable from a Claude Code lead, it may also serve as a wide-context worker substrate (`aki-hands`).
-  - **Script paths in this skill's literal commands are written for Claude Code** (`~/.claude/skills/akiflow/scripts/...`). This file is deployed byte-identical to `~/.gemini/config/skills/` too (`docs/ref/agent-skills-standard.md`), so either root's path runs the same script under Antigravity/agy. **Run the command exactly as written above** — the installer pre-allows both roots in both renderings (expanded and tilde-literal), so the form you copy is never what gets denied. Background: agy's matcher compares command strings literally, with no glob or tilde expansion, so a rule and a command that render the same path differently do not match — which is why the pre-allow covers every rendering instead of asking you to normalize one (`docs/ref/cli-permission-allowlist-standard.md` §1.2).
+  - **Script paths in this skill's literal commands are written for Claude Code** (`~/.claude/skills/akiflow/scripts/...`). This file is deployed byte-identical to `~/.gemini/config/skills/` too (`docs/ref/fact-agent-skills-standard.md`), so either root's path runs the same script under Antigravity/agy. **Run the command exactly as written above** — the installer pre-allows both roots in both renderings (expanded and tilde-literal), so the form you copy is never what gets denied. Background: agy's matcher compares command strings literally, with no glob or tilde expansion, so a rule and a command that render the same path differently do not match — which is why the pre-allow covers every rendering instead of asking you to normalize one (`docs/ref/fact-cli-permission-allowlist-standard.md` §1.2).
 
 Verified harness facts behind every flag named here: `references/harness-facts.md` — its § Worker invocation quick-facts is the lookup table (literal command, read-only mechanism, silent failure per lane); the rest of the file is why. Design record: `docs/arch/akiflow.md` in the akidevrule repo.
 

package/skills/akiflow/scripts/release_lint.py

@@ -43,11 +43,10 @@ def _changelog_blocks(lines: list[str]) -> list[dict]:
     return blocks
 
 
-def lint_changelog(path: Path, latest: bool) -> tuple[list[str], list[str]]:
+def lint_changelog(path: Path, latest: bool) -> tuple[list[str], list[str], list[str]]:
     lines = path.read_text(encoding='utf-8', errors='replace').splitlines()
-    blocks = _changelog_blocks(lines)
-    if latest:
-        blocks = blocks[:1]
+    all_blocks = _changelog_blocks(lines)
+    blocks = all_blocks[:1] if latest else all_blocks
     findings: list[str] = []
     for b in blocks:
         if b['version'] is None:
@@ -69,10 +68,12 @@ def lint_changelog(path: Path, latest: bool) -> tuple[list[str], list[str]]:
         if std != sorted(dict.fromkeys(std), key=SECTIONS.index) and len(set(std)) == len(std):
             expected = ', '.join(sorted(std, key=SECTIONS.index))
             findings.append(f"[ORDER] {path}:{b['line']} | {b['version']}: {', '.join(std)} — expected {expected}")
-    return findings, [b['version'].lstrip('v') for b in blocks if b['version']]
+    scoped_versions = [b['version'].lstrip('v') for b in blocks if b['version']]
+    all_versions = [b['version'].lstrip('v') for b in all_blocks if b['version']]
+    return findings, scoped_versions, all_versions
 
 
-def lint_releases(path: Path, changelog_versions: list[str], latest: bool) -> list[str]:
+def lint_releases(path: Path, changelog_versions: list[str], all_changelog_versions: list[str], latest: bool) -> list[str]:
     findings: list[str] = []
     try:
         data = json.loads(path.read_text(encoding='utf-8'))
@@ -93,9 +94,10 @@ def lint_releases(path: Path, changelog_versions: list[str], latest: bool) -> li
     for v in [x for x in changelog_versions if x.lower() != 'unreleased']:
         if v not in json_versions:
             findings.append(f"[PARITY] {path}:1 | CHANGELOG version {v} has no releases.json entry")
+    # Reverse check needs the full history: with [Unreleased] on top, --latest's one block never holds the newest shipped version.
     for r, v in zip(items, json_versions):
         n = line_of(v)
-        if v not in changelog_versions:
+        if v not in all_changelog_versions:
             findings.append(f"[PARITY] {path}:{n} | releases.json version {v} has no CHANGELOG entry")
         changes = r.get('changes', [])
         for c in changes:
@@ -120,10 +122,10 @@ def lint_target(target: str, latest: bool) -> list[str]:
     if not changelog.is_file():
         print(f"release_lint: no CHANGELOG.md at {target}", file=sys.stderr)
         sys.exit(2)
-    findings, versions = lint_changelog(changelog, latest)
+    findings, versions, all_versions = lint_changelog(changelog, latest)
     releases = changelog.parent / 'app' / 'data' / 'releases.json'
     if releases.is_file():
-        findings.extend(lint_releases(releases, versions, latest))
+        findings.extend(lint_releases(releases, versions, all_versions, latest))
     return findings
 
 

package/skills/akihelp/SKILL.md

@@ -11,14 +11,14 @@ Invoke with `/akihelp`, or whenever the user asks, in any wording, what this set
 
 ## Steps
 
-1. Read `~/.aki/akidevrule/index.md` — the file manifest with tiers and purposes.
+1. Read the Routes table in `~/.claude/skills/akirule/SKILL.md` — one row per rule file: its topic, when it loads, its signals. `RULE-agent-behavior.md` is the one resident rule and is not in the table.
 2. List `~/.claude/skills/` and read the frontmatter (`name` + `description`) of each skill whose directory is prefixed `aki` — these are the installed Aki skills.
 3. List `~/.claude/agents/` and read the frontmatter (`name` / `description` / `tools` / `model`) of each file prefixed `aki-` — these are the installed Aki agent definitions. The directory is shared with the user's own agents, so introduce only the `aki-` ones. If the directory does not exist, that layer is simply not installed: drop the section rather than describing it.
 4. Render a compact overview with these sections:
 
    - **Skills (active, user-invoked)** — one row per aki-skill: its `/name`, its one-line description (from frontmatter), and when to reach for it.
    - **Agent definitions (who the work gets handed to)** — one row per installed `aki-` agent from step 3: what it is for, and the property that is mechanical rather than promised (its `tools:` list, which is what makes a read-only agent actually read-only, and its `model:`, so a tier is never improvised). Say the thing people get wrong: this is a catalog, not a roster — an agent is spawned because a specific requirement needs it, never because it exists.
-   - **Passive system (akirule)** — explain the load mechanisms: core rules and the router always loaded (`@`-imported by `CLAUDE.md`); contextual/analytical rules read when the task's domain matches a route — by meaning, never keywords; full load when the owner asks for the whole corpus. `akirule` is hidden from the `/` menu by design (`user-invocable: false`) — it is imported, not a command.
+   - **Passive system (akirule)** — explain the load mechanisms: the behavior floor and the router always loaded (`@`-imported by `CLAUDE.md`); every other rule read when the task's domain matches a route — by meaning, never keywords — and, on Claude Code, enforced for artifact routes by the `aki-route-guard` hook (the first edit of a code file, `.md`, `CHANGELOG.md`, `.vue`, `.rs`, `.sql` … is denied until its rule was read); full load when the owner asks for the whole corpus. `akirule` is hidden from the `/` menu by design (`user-invocable: false`) — it is imported, not a command.
    - **One brain, three modes** — `METHOD-deep-think.md` is read passively by the router inside normal tasks (brief, inline, at most one clarifying question), as a triggered self-run when an `agent.A3` trigger holds or `/akithink` self-runs on a genuine decision (non-interactive, depth scaled to difficulty, ends in decide-and-report or escalation), and interactively by `/akithink` when the owner asks for a session. Short version of the comparison, not the full METHOD text.
    - **Editing rules** — this whole system is generated from a source repo (akidevrule); the installed copies under `~/.aki/akidevrule` and `~/.claude` are deployed output, never edited directly. Changes go through the source repo + `install.sh`. Note for context: the same skill corpus (not the rule corpus) is also synced by `install.sh` to Antigravity/Gemini and to Codex, Kiro, and Grok CLIs on this machine if present — this skill itself only introduces the Claude Code side.
 
@@ -42,6 +42,6 @@ Invoke with `/akihelp`, or whenever the user asks, in any wording, what this set
    | An analysis in chat is too dense to read as text | `/akihtmlreport` | Renders the analysis already in the conversation as one self-contained HTML file — it visualizes, it does not re-analyze |
    | Unsure whether a rule loaded at all | Read the `[RULES]` line, or ask to load the whole corpus | Every response carries a `[RULES]` receipt naming every rule file in context, so "the rule never arrived" (absent from the line) is visibly different from "the rule arrived and was ignored" — the two have opposite fixes. A full-load request reads everything |
 
-6. Close with the one caveat that changes how people use all of the above: **the router is guaranteed, a routed file is not** — `index.md`, the three core rule files and the router are `@`-imported through `CLAUDE.md`, but a contextual file enters context only when the model `Read`s it on a route match. When something must be deterministic, name the file in the prompt (*"Read `~/.aki/akidevrule/RULE-ui-pattern.md`, then …"*) instead of trusting the signal to fire.
+6. Close with the one caveat that changes how people use all of the above: **the router is guaranteed, a routed file is not** — `RULE-agent-behavior.md` and the router are `@`-imported through `CLAUDE.md`; a routed file enters context when the model `Read`s it — enforced by the route-gate hook when the task edits a matching artifact, best-effort on meaning-only routes. When something on a meaning-only route must be deterministic, name the file in the prompt (*"Read `~/.aki/akidevrule/RULE-ui-pattern.md`, then …"*) instead of trusting the signal to fire.
 
 7. Keep the output scannable: compact tables or short bulleted sections, not an essay. Respond in the user's language, and translate the example prompts into that language rather than pasting them verbatim in English.

package/skills/akiopen/SKILL.md

@@ -25,7 +25,7 @@ grep -rn -i 'needs owner\|needs mac\|manual test\|unverified' docs/plan/*.md 2>/
 | Active plans | `docs/plan/*.md` outside `done/` with open `- [ ]` items, or a plan whose text says done but still sits outside `done/` (`docs.B1`) |
 | Inbox files | any top-level `docs/*.md` with open `- [ ]` items — tasks pushed in from an upstream standard or another repo |
 | Release | `[Unreleased]` has entries, or the tree changed with no entry yet (`release.A`) |
-| Hand-offs | a line in an active plan waiting on the owner or another machine (`coding.B5`) |
+| Hand-offs | a line in an active plan waiting on the owner or another machine (`coding.B3`) |
 
 A surface the project does not have is skipped silently. A project `CLAUDE.md` may name additional inbox or plan paths; read it before scanning.