@akinet/akidevrule 3.5.0 → 3.7.0

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

@@ -0,0 +1,154 @@
+#!/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 { homedir } from "node:os";
+import { join, dirname, basename, extname } from "node:path";
+
+const HOME = homedir();
+const RULE_DIR = join(HOME, ".aki", "akidevrule");
+const CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR || join(HOME, ".claude");
+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)\//;
+
+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) {
+  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 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");
+  }
+  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) {
+  const p = filePath.replace(/\\/g, "/");
+  if (p.includes("/.aki/")) 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;
+  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();
+  try {
+    for (const line of readFileSync(join(CONFIG_DIR, "CLAUDE.md"), "utf8").split("\n")) {
+      const m = line.match(/^@.*\/((?:RULE|METHOD)-[\w-]+\.md)\s*$/);
+      if (m) out.add(m[1]);
+    }
+  } catch {
+    /* no global file: nothing is resident */
+  }
+  return out;
+}
+
+/** The transcript that records this actor's own tool calls: the subagent file when the hook fires inside a subagent, else the session transcript. */
+function transcriptFor(input) {
+  const main = input.transcript_path;
+  if (input.agent_id) {
+    const sub = join(dirname(main), input.session_id, "subagents", `agent-${input.agent_id}.jsonl`);
+    if (existsSync(sub)) return sub;
+  }
+  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). */
+function scanTranscript(path, wanted) {
+  const read = new Set();
+  const denials = new Map();
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return { read, denials, unreadable: true };
+  }
+  for (const line of text.split("\n")) {
+    if (!line.includes("akidevrule") && !line.includes(MARK) && !line.includes(COMPACT)) continue;
+    let d;
+    try {
+      d = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (d.type === "system" && d.subtype === COMPACT) {
+      read.clear();
+      denials.clear();
+    } else if (d.type === "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 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);
+        }
+      }
+    } 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);
+    }
+  }
+  return { read, denials, unreadable: false };
+}
+
+function deny(missing, 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.`;
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }) + "\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 || {};
+  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 resident = residentRules();
+  const gated = wanted.filter((r) => !resident.has(r));
+  if (gated.length === 0) allow();
+  const { read, 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);
+}
+
+try {
+  main();
+} catch {
+  allow();
+}

package/claude/hooks/aki_version_check.mjs

@@ -66,9 +66,9 @@ function isFile(p) {
   }
 }
 
-/** True when installRoot looks intact enough to compare (CHANGELOG.md and index.md both present). */
+/** True when installRoot looks intact enough to compare (CHANGELOG.md and the core rule both present). */
 export function localInstallPresent(installRoot) {
-  return isFile(join(installRoot, "CHANGELOG.md")) && isFile(join(installRoot, "index.md"));
+  return isFile(join(installRoot, "CHANGELOG.md")) && isFile(join(installRoot, "RULE-agent-behavior.md"));
 }
 
 /** One of the STATE_* constants — see README.md "Update notifications" for the full 5-state table. */

package/docs/ref/{macos-codesign-tcc.md → fact-macos-codesign-tcc.md}

@@ -1,6 +1,8 @@
 # Local macOS codesign and TCC
 
-The one AkiDevRule lookup for this chain. `tauri.B7` is the concise rule (do not delete it); the installer (`install.mjs`) deploys this file to `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`. Evidence trail: `docs/research/macos-tcc-tauri-boundary-aug21.md`.
+`updated 2026-09-30 · v3.5.0`
+
+The one AkiDevRule lookup for this chain. `tauri.B7` is the concise rule (do not delete it); the installer (`install.mjs`) deploys this file to `~/.aki/akidevrule/docs/ref/fact-macos-codesign-tcc.md`. Evidence trail: `docs/research/macos-tcc-tauri-boundary-aug21.md`.
 
 **Stable self-signed identity keeps TCC grants across rebuilds. Apple ad-hoc (`codesign --sign -`) does not.** Artifact names, install paths, and identity names live in that project’s own docs — not here.
 

package/install.mjs

@@ -45,6 +45,7 @@ const GEMINI_RULES_DIR = join(GEMINI_DIR, "config", "rules");
 const GEMINI_SKILLS_DIR = join(GEMINI_DIR, "config", "skills");
 
 const CODEX_SKILLS_DIR = join(HOME, ".agents", "skills");
+const CODEX_HOME = process.env.CODEX_HOME ? expandTilde(process.env.CODEX_HOME.trim()) : join(HOME, ".codex");
 const KIRO_SKILLS_DIR = join(HOME, ".kiro", "skills");
 const GROK_SKILLS_DIR = join(HOME, ".grok", "skills");
 const SKILLS_SRC = join(REPO_ROOT, "skills");
@@ -333,15 +334,16 @@ 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-test.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 +368,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 +381,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")];
@@ -397,6 +398,63 @@ function installAgRules() {
   return rendered.length;
 }
 
+// ---------------------------------------------------------------------------
+// Codex global instructions — behavior floor + router as a managed block in $CODEX_HOME/AGENTS.md
+// (docs/research/codex-instruction-delivery.md: Codex hard-loads that file; it expands no imports and reads no Claude global file)
+// ---------------------------------------------------------------------------
+
+const CODEX_BLOCK_START = "<!-- >>> akidevrule managed: behavior floor + router, regenerated on every install — edit the source repo, never this block -->";
+const CODEX_BLOCK_END = "<!-- <<< akidevrule managed -->";
+const CODEX_DOC_BUDGET = 131072; // Codex stops adding instruction files once global + project files reach project_doc_max_bytes (32 KiB by default); the managed block alone is larger
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const TOML_HEADER = /^[ \t]*\[\[?[ \t]*[\w.\-"' ]+[ \t]*\]\]?[ \t]*(#.*)?$/m; // a whole-line [table] or [[array]] header, not a nested-array line inside a multi-line value
+
+function codexInstructionBlock() {
+  const preamble =
+    "# akidevrule on Codex\n\n" +
+    "This block is the resident rule context for Codex: the behavior floor (`RULE-agent-behavior.md`) and the rule router (`skills/akirule/SKILL.md`), both installed under `~/.aki/akidevrule/`. Codex has no route gate: the Read of a routed rule file is your own mandatory step before the first edit of that artifact type. Do not invoke the `akirule` skill as well — the routing below is already loaded.";
+  const floor = readFileSync(join(REPO_ROOT, "payload", "RULE-agent-behavior.md"), "utf-8").trim();
+  const router = readFileSync(ROUTER_SRC, "utf-8").trim();
+  return [CODEX_BLOCK_START, preamble, floor, router, CODEX_BLOCK_END].join("\n\n") + "\n";
+}
+
+// Top-level TOML keys must precede the first table header, so the key is inserted before it, once, and only when absent.
+function ensureCodexDocBudget(blockBytes) {
+  const cfg = join(CODEX_HOME, "config.toml");
+  const text = isFile(cfg) ? readFileSync(cfg, "utf-8") : "";
+  const firstTable = text.search(TOML_HEADER);
+  const top = (firstTable === -1 ? text : text.slice(0, firstTable)).replace(/\s*$/, "");
+  const m = top.match(/^\s*project_doc_max_bytes\s*=\s*(\d+)/m);
+  if (m) return { value: Number(m[1]), written: false, enough: Number(m[1]) >= blockBytes };
+  const line = `project_doc_max_bytes = ${CODEX_DOC_BUDGET} # akidevrule: the managed block in AGENTS.md plus project instructions exceed Codex's 32 KiB default\n`;
+  const after = (top ? top + "\n\n" : "") + line + (firstTable === -1 ? "" : "\n" + text.slice(firstTable));
+  if (text) {
+    backup(cfg);
+    pruneBackups(cfg);
+  }
+  writeTextLf(cfg, after);
+  return { value: CODEX_DOC_BUDGET, written: true, enough: true };
+}
+
+function installCodexInstructions() {
+  if (!isDir(CODEX_HOME)) return null;
+  const file = join(CODEX_HOME, "AGENTS.md");
+  const before = isFile(file) ? readFileSync(file, "utf-8") : "";
+  const block = codexInstructionBlock();
+  const user = before.replace(new RegExp(`\\n?${escapeRe(CODEX_BLOCK_START)}[\\s\\S]*?${escapeRe(CODEX_BLOCK_END)}\\n?`), "\n").trim();
+  const after = (user ? user + "\n\n" : "") + block;
+  const changed = after !== before;
+  if (changed) {
+    backup(file);
+    pruneBackups(file);
+    writeTextLf(file, after);
+  }
+  const override = join(CODEX_HOME, "AGENTS.override.md");
+  const shadowed = isFile(override) && readFileSync(override, "utf-8").trim() !== "";
+  const bytes = Buffer.byteLength(block, "utf-8");
+  return { file, bytes, changed, shadowed, budget: ensureCodexDocBudget(bytes) };
+}
+
 // ---------------------------------------------------------------------------
 // settings.json merge (Claude Code)
 // ---------------------------------------------------------------------------
@@ -457,7 +515,14 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
       return false;
     }
   };
-  hooks.SessionStart = hooks.SessionStart.filter((e) => !isAkiUpdate(e));
+  const isAkiCompact = (entry) => {
+    try {
+      return (entry.hooks || []).some((h) => (h.command || "").includes("aki-compact-reread"));
+    } catch {
+      return false;
+    }
+  };
+  hooks.SessionStart = hooks.SessionStart.filter((e) => !isAkiUpdate(e) && !isAkiCompact(e));
   hooks.SessionStart.push({
     matcher: "startup|resume",
     hooks: [
@@ -468,6 +533,36 @@ function mergeSettings(settingsPath, installRoot, claudeDir) {
       },
     ],
   });
+  hooks.SessionStart.push({
+    matcher: "compact",
+    hooks: [
+      {
+        type: "command",
+        command: `node "${join(claudeDir, "hooks", "aki-compact-reread.mjs")}"`,
+        timeout: 5,
+      },
+    ],
+  });
+
+  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 +635,8 @@ 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"));
+  copyFileSync(join(REPO_ROOT, "claude", "hooks", "aki-compact-reread.mjs"), join(hooksDest, "aki-compact-reread.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 +661,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);
 
@@ -725,6 +822,8 @@ async function inspectStatus(claudeDirs) {
     }
   }
 
+  if (isDir(CODEX_HOME)) console.log(`🤖 Codex (${toTildePath(CODEX_HOME)}): will write the managed block in AGENTS.md (your own lines kept) and set project_doc_max_bytes in config.toml when absent`);
+
   if (isDir(GEMINI_DIR)) {
     const agSettings = join(GEMINI_DIR, "antigravity-cli", "settings.json");
     if (isFile(agSettings)) {
@@ -750,7 +849,7 @@ async function inspectStatus(claudeDirs) {
 // print_summary (post-install)
 // ---------------------------------------------------------------------------
 
-function printSummary(claudeDirs, preAllow) {
+function printSummary(claudeDirs, preAllow, codex) {
   console.log(`\n${greenBold("=== INSTALL SUCCEEDED ===")}`);
 
   const gitHash = gitShortHash(REPO_ROOT);
@@ -764,19 +863,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}`);
     }
   }
 
@@ -804,6 +896,19 @@ function printSummary(claudeDirs, preAllow) {
   console.log(`  🤖 Kiro CLI  : ${KIRO_SKILLS_DIR}`);
   console.log(`  🤖 Grok CLI  : ${GROK_SKILLS_DIR}`);
 
+  console.log();
+  console.log(cyanBold("Codex global instructions (behavior floor + router, resident):"));
+  if (!codex) {
+    console.log(`  ℹ️  ${toTildePath(CODEX_HOME)} not found — skipped; set CODEX_HOME or install Codex and re-run`);
+  } else {
+    console.log(`  📝 ${toTildePath(codex.file)} — managed block ${(codex.bytes / 1024).toFixed(1)} KB${codex.changed ? "" : ", unchanged"}; lines of your own in that file are kept`);
+    const b = codex.budget;
+    const budgetNote = b.written ? "written to config.toml — Codex stops loading instruction files past 32 KiB by default" : b.enough ? "already set" : `⚠️  smaller than the managed block (${codex.bytes} B) — raise it in ${toTildePath(join(CODEX_HOME, "config.toml"))}`;
+    console.log(`  ⚙️  project_doc_max_bytes = ${b.value} — ${budgetNote}`);
+    if (codex.shadowed) console.log(`  ⚠️  ${toTildePath(join(CODEX_HOME, "AGENTS.override.md"))} is non-empty and shadows AGENTS.md — Codex ignores the managed block until it is removed`);
+    console.log(`  ℹ️  Codex does not read a project's CLAUDE.md; opt in per machine with project_doc_fallback_filenames = ["CLAUDE.md"] in config.toml (a native AGENTS.md in the same directory still wins)`);
+  }
+
   console.log();
   console.log(cyanBold("Skill scripts pre-allowed (no prompt when a skill runs its own scripts):"));
   console.log("  ⚙️  claude       settings.json in every target above — plus Read(~/.aki/akidevrule/**)");
@@ -815,6 +920,8 @@ 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 after the last compaction; 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");
 
   console.log(`\n${greenBold("==============================")}`);
@@ -883,8 +990,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);
@@ -907,10 +1014,11 @@ async function runInstall(claudeDirs) {
     installClaudeDir(cDir);
   }
 
-  // --- 3. Other CLI skill roots ---
+  // --- 3. Other CLI skill roots, and Codex's resident instructions ---
   syncAkiSkills(CODEX_SKILLS_DIR);
   syncAkiSkills(KIRO_SKILLS_DIR);
   syncAkiSkills(GROK_SKILLS_DIR);
+  const codex = installCodexInstructions();
 
   // --- 4. GEMINI.md (only when ~/.gemini exists) ---
   if (isDir(GEMINI_DIR)) {
@@ -975,7 +1083,7 @@ async function runInstall(claudeDirs) {
   // --- 5. Script pre-allow for every other harness present ---
   const preAllow = preAllowHarnessScripts(claudeDirs);
 
-  printSummary(claudeDirs, preAllow);
+  printSummary(claudeDirs, preAllow, codex);
 }
 
 // ---------------------------------------------------------------------------

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.7.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/METHOD-audit-subtraction.md

@@ -35,6 +35,7 @@ Run only what the project actually has; name what was skipped and why (`zero-tru
 | Docs | docs nothing links, plans whose work shipped, superseded research with no chain marker | `docs.C3` |
 | Content | i18n keys nobody reads, strings for removed features | `content.A3` |
 | Operational leftovers | migrations already run and still pending-located, one-shot scripts, dead flags and env vars | `release.B5`, `stack.C8` |
+| Tests | a test that checks nothing, duplicates another, compares to the implementation's own value, or carries a fixture larger than its boundary | `test.A1`, `test.A2`, `test.D` |
 
 ### B2. Severity classes for subtraction — and the class that forbids removal
 - **Dead** — no reference anywhere in the locked scope. CERTAIN, machine-decidable, countable.

package/payload/METHOD-audit-zero-trust.md

@@ -14,7 +14,7 @@ Zero trust means nothing counts as clean because it looks clean: a finding exist
 
 ## B. Mechanical pass runs first
 
-1. **Run the detectors before forming any opinion** — typecheck, the repo's linter, `scythe.py` (`skills/akiflow/scripts/scythe.py` in the akidevrule source repo) for `[WRAP]`/`[YAP]`, and the targeted `grep` scans the relevant rule file already specifies (`ui.C1` for frontend, `flow` for state, `release.B` for version state).
+1. **Run the detectors before forming any opinion** — typecheck, the repo's linter, `scythe.py` (`skills/akiflow/scripts/scythe.py` in the akidevrule source repo) for `[WRAP]`/`[YAP]`, and the targeted `grep` scans the relevant rule file already specifies (`ui.C1` for frontend, `flow` for state, `release.B` for version state, `test.D1` for a test suite).
 2. **Run only what the project actually has**, and name what you skipped and why. A missing `tsconfig.json` means there is no typecheck to run, not a gap to invent one for. Never run a build or a dev server to satisfy this step.
 3. **Attach the raw output**, and attach it *before* stating a conclusion. A tool run afterwards to confirm something already asserted is not verification.